Collecting responses
Read submitted forms and consent decisions, keep sensitive fields masked by default, and explicitly retrieve protected answers or files.
Plans of kind form or consent can produce responses. The questions and
consent terms are configured in Workspace; the API reads what came back.
List and read responses
GET https://api.keepable.co/sender/v2/correspondence/cor_01J8ZQ4T/responses?limit=50
Authorization: Bearer {{KEEPABLE_TOKEN}}Only participants who responded have a record. Read one by participant:
GET https://api.keepable.co/sender/v2/correspondence/cor_01J8ZQ4T/responses/prt_01J8ZQ4T
Authorization: Bearer {{KEEPABLE_TOKEN}}{
"participant_id": "prt_01J8ZQ4T",
"display_name": "Chioma Okeke",
"ref": "CUST-100400",
"verification": "nin",
"state": "submitted",
"fields": [
{ "ref": "full_name", "label": "Full name", "value": "Chioma Okeke" },
{ "ref": "bvn", "label": "BVN", "sensitive": true, "masked_value": "••• •••• 0000" },
{ "ref": "id_doc", "label": "Government-issued ID", "files": [{ "name": "nin-slip.pdf", "size_bytes": 61440 }] }
]
}Sensitive answers
responses.read returns sensitive fields masked. Reveal selected fields from
one record with both responses.read and responses.sensitive:
POST https://api.keepable.co/sender/v2/correspondence/cor_01J8ZQ4T/responses/prt_01J8ZQ4T/reveal
Authorization: Bearer {{KEEPABLE_TOKEN}}
Idempotency-Key: 9ae486f4-7e50-4620-80fc-739d5d726262
Content-Type: application/json
{ "refs": ["bvn"] }Each reveal is recorded before the value is returned. Omit refs to reveal all
sensitive fields on that response.
Submitted files
Download a file by the question field_ref, not by a generic document id:
GET https://api.keepable.co/sender/v2/correspondence/cor_01J8ZQ4T/responses/prt_01J8ZQ4T/documents/{field_ref}?index=0
Authorization: Bearer {{KEEPABLE_TOKEN}}This operation requires responses.sensitive and returns the original bytes.
Use index when the answer contains several files.
Response deletion, consent acknowledgements and receipts, general exports, and operator closing actions remain in Workspace.