DOCS
HomeFor logistics providers Zonos Clarify Complete a questionnaire

Complete a questionnaire

Clarify pre-fills what it can from your item data; you confirm or correct the rest, then finalize.

GraphQL

Once you know which programs apply (see Check compliance requirements), the recommended flow is three calls:

  1. Infer - complianceQuestionnaireInfer opens a session with answers pre-filled from your item data.
  2. Review and correct - questionnaireAnswersSubmit to change anything the shipper disagrees with and answer what's left.
  3. Attest - questionnaireSessionAttest to accept and finalize.

If you already have every answer, you can submit a complete response in one call instead — see Submit a complete response below.

Scopes

Reading requires the COMPLIANCE_READ scope; submitting answers requires COMPLIANCE_WRITE. See OAuth.

Answer values are JSON-encoded

Every answer value is a JSON-encoded string: a boolean is "true", a select or text value is quoted like "\"cosmetic\"", a multi-select is "[\"a\",\"b\"]", and a number is "42".

Infer and prefill 

complianceQuestionnaireInfer resolves the applicable programs for your items, opens a session, and pre-answers questions from your item data. Each pre-filled answer has provenance: INFERRED and a confidence score.

Pass intendedUse to guide inference — storefront flows should send CONSUMER.

1mutation InferQuestionnaire($input: ComplianceQuestionnaireInferInput!) {
2 complianceQuestionnaireInfer(input: $input) {
3 session {
4 id
5 status
6 lines {
7 id
8 programId
9 status
10 currentQuestion {
11 code
12 prompt
13 answerType
14 }
15 }
16 }
17 lines {
18 lineId
19 state
20 remainingRequiredCount
21 }
22 }
23}

Each line's state tells you what's next:

  • READY_TO_ATTEST - every required question is answered. Go straight to Attest (below).
  • PARTIAL - some answers were pre-filled, but required questions remain. Answer them at currentQuestion.
  • NOT_INFERRED - nothing could be pre-filled; answer it as a plain questionnaire.

Programs already satisfied by an existing response are skipped and returned in alreadySatisfied (omitted above).

Review and correct 

The session holds pre-filled answers — not a finalized response. For each answer, the shipper either:

  • accepts it — leaves it untouched, and it stays INFERRED, or
  • corrects it — submits a new value with questionnaireAnswersSubmit, which becomes MANUAL.

Submit one answer or several at once. Clarify advances currentQuestion to the next remaining question and, when none are left, finalizes the line's response (its responseId is populated).

Accepted answers are kept, not discarded

Correcting one answer overrides only that answer. The finalized response holds the full set — accepted answers stay INFERRED, corrections are MANUAL — so you always keep a record of what the AI supplied versus what a person changed.

For example, the shipper accepts the inferred intended_use but corrects contains_color_additives, so they submit just that one answer:

1mutation SubmitAnswers($input: QuestionnaireAnswersSubmitInput!) {
2 questionnaireAnswersSubmit(input: $input) {
3 status
4 lines {
5 id
6 status
7 responseId
8 answers {
9 questionCode
10 value
11 provenance
12 confidence
13 }
14 }
15 }
16}

Attest 

When a line is READY_TO_ATTEST — every required answer already pre-filled and the shipper agrees — accept it in one call with questionnaireSessionAttest. It finalizes every eligible line, or only the lineIds you pass.

1mutation AttestSession($input: QuestionnaireSessionAttestInput!) {
2 questionnaireSessionAttest(input: $input) {
3 id
4 status
5 lines {
6 id
7 status
8 responseId
9 }
10 }
11}

To discard an in-progress session, call questionnaireSessionAbandon(id: ID!).

Submit a complete response 

If you already have every answer — for example a reusable answer set for a CATALOG_ITEM — skip the session and submit directly with questionnaireResponseSubmit. It replaces any previous response for the same item and program.

1mutation SubmitResponse($input: QuestionnaireResponseSubmitInput!) {
2 questionnaireResponseSubmit(input: $input) {
3 id
4 status
5 completedAt
6 answers {
7 questionCode
8 value
9 provenance
10 }
11 }
12}

Prefer to answer without inference? questionnaireSessionStart opens a session for the programs you choose, and then you use the same Review and correct and Attest calls above.

Read responses and readiness 

Fetch a finalized record with questionnaireResponse(id), and check whether a whole container is ready to file with containerComplianceReadiness — ready is true only when every line has a complete response.

1query ContainerReadiness($containerType: ContainerType!, $containerId: ID!) {
2 containerComplianceReadiness(
3 containerType: $containerType
4 containerId: $containerId
5 ) {
6 ready
7 totalLineCount
8 outstandingLineCount
9 }
10}

Next steps 

GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

ComplianceQuestionnaireInferInput QuestionnaireAnswersSubmitInput QuestionnaireResponseSubmitInput QuestionnaireSessionAttestInput

MUTATIONS

complianceQuestionnaireInfer questionnaireAnswersSubmit questionnaireResponseSubmit questionnaireSessionAttest

Was this page helpful?

Get support·Legal docs·© 2026 Zonos
On this page:
  • Complete a questionnaire
  • Infer and prefill
  • Review and correct
  • Attest
  • Submit a complete response
  • Read responses and readiness
  • Next steps