DOCS

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

Answering and attesting use their own scope, COMPLIANCE_SESSION_ANSWER; COMPLIANCE_WRITE alone is not enough. See OAuth.

Operation↕Scope↕
complianceQuestionnaireInfer, questionnaireSessionStart, questionnaireResponseSubmit, questionnaireSessionAbandon, complianceQuestionnaireAmend, complianceObligationsRemediate, complianceObligationsCopyAnswersCOMPLIANCE_WRITE
complianceQuestionnaireOpenCOMPLIANCE_QUESTIONNAIRE_OPEN
questionnaireAnswersSubmit, questionnaireAnswersStage, questionnaireSessionAttestCOMPLIANCE_SESSION_ANSWER
questionnaireSessionCOMPLIANCE_SESSION_READ
questionnaireSessions, questionnaireResponse, containerComplianceReadiness, complianceObligationsCOMPLIANCE_READ
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? complianceQuestionnaireOpen takes the same input as complianceQuestionnaireInfer but opens lines from the item facts you supply without guessing any answers, and questionnaireSessionStart opens a session for the programs you choose. Either way, you then use the same Review and correct and Attest calls above.

Catalog items 

For a CATALOG_ITEM, the container is the catalog item itself. Omit items and Clarify reads the item facts it already holds for that catalog item, so you only pass its id. If inference already ran for the item's current content, the open session comes back untouched: no new inference, and earlier answers stay as they are. shipToCountry may be omitted here too.

{
  "input": {
    "containerType": "CATALOG_ITEM",
    "containerId": "catalog_item_77aa31bf90c2"
  }
}

Then correct answers with questionnaireAnswersSubmit and accept with questionnaireSessionAttest, exactly as above. To save answers without finalizing them, use questionnaireAnswersStage instead of questionnaireAnswersSubmit. It takes the same input, but a line with nothing required left stays open until you call questionnaireSessionAttest.

Correct answers that are already finalized

Once a line is finalized, open an amendment with complianceQuestionnaireAmend, passing the completed session's id. It returns a new session whose lines start with the answers currently in force. Edit them with questionnaireAnswersSubmit, or accept them with questionnaireSessionAttest. The new responses replace the old ones only when they finalize; until then, the item keeps its current answers.

To find the completed session for a catalog item, query questionnaireSessions with filter: { containerType: CATALOG_ITEM, containerId: "<catalog item id>", statuses: [COMPLETED] }.

1mutation AmendQuestionnaire($input: ComplianceQuestionnaireAmendInput!) {
2 complianceQuestionnaireAmend(input: $input) {
3 session {
4 id
5 lines {
6 id
7 programId
8 status
9 answers {
10 questionCode
11 value
12 }
13 }
14 }
15 lines {
16 lineId
17 state
18 }
19 }
20}

Omit lineIds to amend every line of that session that has a finalized response.

Many catalog items

There is no CSV import for questionnaire answers. To work through many catalog items, list their obligations with complianceObligations, then pass up to 100 obligation ids per call to:

  • complianceObligationsRemediate - opens or resumes a session for each obligation. An obligation that is already satisfied opens a revision seeded from its current answers.
  • complianceObligationsCopyAnswers - copies every answer from one catalog item's completed response onto obligations for the same program and route. It copies item-specific answers too, so review each item before attesting.

Each call reports successes and failures per obligation. Answer and attest the sessions it returns with the 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 

Book a demo

Was this page helpful?


Get support·Legal docs·© 2026 Zonos