Request
POST https://app.datumforms.com/api/developer-api
Operation: responses.update
Permissions: responses:write.
Correct ordinary answers using response_id, expected_revision, reason and answers.
Send operation as a query parameter for GET, or a top-level JSON member for POST. Every POST also needs idempotency_key (8–100 permitted characters). Fields marked data belong inside the JSON data object.
| Parameter | Location | Type | Required | Meaning |
|---|---|---|---|---|
response_id |
top level | integer | Yes | ID from responses.list. |
expected_revision |
data | integer | Yes | Current response revision from responses.list. |
reason |
data | string | Yes | Nonblank reason, up to 1000 characters. |
answers |
data | array | Yes | Answer cells in the original version; null clears a cell. |
Response
Successful results contain success: true plus these operation fields. Fields returned by shared form and resource services retain their normal definitions.
| Field | Type or shape |
|---|---|
response_id |
integer |
revision |
integer |
See schemas for answer cells, responses and collection details. Use IDs from your project: groups.list returns group IDs, surveys.get returns page/question IDs, and responses.list returns response IDs and revisions.
Examples
Set DATUMFORMS_API_KEY. Replace example IDs with IDs returned by the preceding reads. Replace docs-run-001 with your persisted job identity. Write examples perform the named operation; keep the exact request and identity unchanged when retrying. JavaScript and Python examples use the downloadable clients.
cURL
curl --fail-with-body 'https://app.datumforms.com/api/developer-api' \
-H "Authorization: Bearer $DATUMFORMS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"operation":"responses.update","response_id":123,"data":{"expected_revision":1,"reason":"Correct item label","answers":[{"questionRef":456,"value":"Updated label"}]},"idempotency_key":"docs-run-001:responses-update"}'
JavaScript
import { request } from './client.mjs';
const result = await request("POST", {
"operation": "responses.update",
"response_id": 123,
"data": {
"expected_revision": 1,
"reason": "Correct item label",
"answers": [
{
"questionRef": 456,
"value": "Updated label"
}
]
},
"idempotency_key": "docs-run-001:responses-update"
});
console.log(JSON.stringify(result, null, 2));
Python
import json
from client import request
payload = json.loads('{"operation": "responses.update", "response_id": 123, "data": {"expected_revision": 1, "reason": "Correct item label", "answers": [{"questionRef": 456, "value": "Updated label"}]}, "idempotency_key": "docs-run-001:responses-update"}')
result = request('POST', payload)
print(json.dumps(result, indent=2))
Pagination and errors
This operation does not use cursor pagination. For 400, check required values and types; for 401, check authentication; for 403, check permissions and project scope; for 404, check the resource ID. For 409, resolve the current revision or review conflict. Retry uncertain writes with the identical request and original key. Managed recruitment responses are protected; use these data-writing operations for ordinary surveys. See error recovery and the operation index.