Submit answers for an assessment

POST https://www.example.com/api/v2/assessments/:id/submit_answers

Atomically submits one or more answers for an assessment. All answers are validated before any are persisted — if any answer is invalid, the entire batch is rejected. Requires a last_updated token for optimistic concurrency control.

Request

Path Parameters

id string required
Assessment UUID

Header Parameters

authorization string required
Example: Bearer privacy_api_key.abc123

• application/json

Body required

answers object required
Map of question UUID to answer value. Text-type answers use a plain string (e.g. "We collect email addresses for marketing"). Select-type answers use a { key } object where key matches one of the option keys defined in the template (e.g. "Yes", "No", "Not_Sure"). Multi-select answers use an array of { key } objects. Date answers use an ISO 8601 date string (e.g. "2026-06-01").

property name* object

oneOf

• string
• object
• object[]

string

Text or date answer

last_updated string required
Optimistic concurrency token (millisecond epoch timestamp). Obtain from the assessment detail endpoint or a previous submit_answers response.

Example: 1714500000000

{
  "answers": {
    "uuid-text-q1": "We collect email addresses for marketing",
    "uuid-radio-q2": {
      "key": "Yes"
    },
    "uuid-multiselect-q3": [
      {
        "key": "namefullfirstorlast"
      },
      {
        "key": "nationality"
      }
    ],
    "uuid-date-q4": "2026-06-01"
  },
  "last_updated": "1714500000000"
}

Responses

• 200
• 404
• 409
• 422

Answers accepted

• application/json

Schema

data object

id uuid

status string
Possible values: ["not_started", "in_progress", "pending_approval", "approved"]

answers_accepted integer
Example: 3

answers_rejected integer
Example: 0

errors object

property name* string

progress integer | null nullable
Percentage of questions answered (0-100)

Example: 50

last_updated string
Optimistic lock token for subsequent submissions

Example: 1714500000000

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "not_started",
    "answers_accepted": 3,
    "answers_rejected": 0,
    "errors": {},
    "progress": 50,
    "last_updated": "1714500000000"
  }
}

Assessment not found

Conflict — stale last_updated or non-editable status

• application/json

Schema

error string

{
  "error": "string"
}

Validation failure

• application/json

Schema

error string
Example: One or more answers failed validation

data object

answers_accepted integer
Example: 0

answers_rejected integer
Example: 1

errors object

property name* string

{
  "error": "One or more answers failed validation",
  "data": {
    "answers_accepted": 0,
    "answers_rejected": 1,
    "errors": {
      "uuid-s2q3": "Select-type answers must use { key } format"
    }
  }
}

CURL Example

curl -L 'https://www.example.com/api/v2/assessments/:id/submit_answers' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "answers": {
    "uuid-text-q1": "We collect email addresses for marketing",
    "uuid-radio-q2": {
      "key": "Yes"
    },
    "uuid-multiselect-q3": [
      {
        "key": "namefullfirstorlast"
      },
      {
        "key": "nationality"
      }
    ],
    "uuid-date-q4": "2026-06-01"
  },
  "last_updated": "1714500000000"
}'

Base URL

Edit

https://www.example.com

Parameters

id — path required

authorization — header required

Body required

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.