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".
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.
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:
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.
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.
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.
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.
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] }.
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.
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.
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:
complianceQuestionnaireInferopens a session with answers pre-filled from your item data.questionnaireAnswersSubmitto change anything the shipper disagrees with and answer what's left.questionnaireSessionAttestto 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.
Answering and attesting use their own scope,
COMPLIANCE_SESSION_ANSWER;COMPLIANCE_WRITEalone is not enough. See OAuth.complianceQuestionnaireInfer,questionnaireSessionStart,questionnaireResponseSubmit,questionnaireSessionAbandon,complianceQuestionnaireAmend,complianceObligationsRemediate,complianceObligationsCopyAnswersCOMPLIANCE_WRITEcomplianceQuestionnaireOpenCOMPLIANCE_QUESTIONNAIRE_OPENquestionnaireAnswersSubmit,questionnaireAnswersStage,questionnaireSessionAttestCOMPLIANCE_SESSION_ANSWERquestionnaireSessionCOMPLIANCE_SESSION_READquestionnaireSessions,questionnaireResponse,containerComplianceReadiness,complianceObligationsCOMPLIANCE_READEvery answer
valueis 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
complianceQuestionnaireInferresolves the applicable programs for your items, opens a session, and pre-answers questions from your item data. Each pre-filled answer hasprovenance: INFERREDand aconfidencescore.Pass
intendedUseto guide inference — storefront flows should sendCONSUMER.mutation InferQuestionnaire($input: ComplianceQuestionnaireInferInput!) {complianceQuestionnaireInfer(input: $input) {session {idstatuslines {idprogramIdstatuscurrentQuestion {codepromptanswerType}}}lines {lineIdstateremainingRequiredCount}}}Each line's
statetells 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 atcurrentQuestion.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:
INFERRED, orquestionnaireAnswersSubmit, which becomesMANUAL.Submit one answer or several at once. Clarify advances
currentQuestionto the next remaining question and, when none are left, finalizes the line's response (itsresponseIdis populated).Correcting one answer overrides only that answer. The finalized response holds the full set — accepted answers stay
INFERRED, corrections areMANUAL— so you always keep a record of what the AI supplied versus what a person changed.For example, the shipper accepts the inferred
intended_usebut correctscontains_color_additives, so they submit just that one answer:mutation SubmitAnswers($input: QuestionnaireAnswersSubmitInput!) {questionnaireAnswersSubmit(input: $input) {statuslines {idstatusresponseIdanswers {questionCodevalueprovenanceconfidence}}}}Attest
When a line is
READY_TO_ATTEST— every required answer already pre-filled and the shipper agrees — accept it in one call withquestionnaireSessionAttest. It finalizes every eligible line, or only thelineIdsyou pass.mutation AttestSession($input: QuestionnaireSessionAttestInput!) {questionnaireSessionAttest(input: $input) {idstatuslines {idstatusresponseId}}}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 withquestionnaireResponseSubmit. It replaces any previous response for the same item and program.mutation SubmitResponse($input: QuestionnaireResponseSubmitInput!) {questionnaireResponseSubmit(input: $input) {idstatuscompletedAtanswers {questionCodevalueprovenance}}}Prefer to answer without inference?
complianceQuestionnaireOpentakes the same input ascomplianceQuestionnaireInferbut opens lines from the item facts you supply without guessing any answers, andquestionnaireSessionStartopens 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. Omititemsand 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.shipToCountrymay be omitted here too.{ "input": { "containerType": "CATALOG_ITEM", "containerId": "catalog_item_77aa31bf90c2" } }Then correct answers with
questionnaireAnswersSubmitand accept withquestionnaireSessionAttest, exactly as above. To save answers without finalizing them, usequestionnaireAnswersStageinstead ofquestionnaireAnswersSubmit. It takes the same input, but a line with nothing required left stays open until you callquestionnaireSessionAttest.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 withquestionnaireAnswersSubmit, or accept them withquestionnaireSessionAttest. 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
questionnaireSessionswithfilter: { containerType: CATALOG_ITEM, containerId: "<catalog item id>", statuses: [COMPLETED] }.mutation AmendQuestionnaire($input: ComplianceQuestionnaireAmendInput!) {complianceQuestionnaireAmend(input: $input) {session {idlines {idprogramIdstatusanswers {questionCodevalue}}}lines {lineIdstate}}}Omit
lineIdsto 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 withcontainerComplianceReadiness—readyistrueonly when every line has a complete response.query ContainerReadiness($containerType: ContainerType!, $containerId: ID!) {containerComplianceReadiness(containerType: $containerTypecontainerId: $containerId) {readytotalLineCountoutstandingLineCount}}Next steps
ComplianceQuestionnaireAmendInput ComplianceQuestionnaireInferInput QuestionnaireAnswersSubmitInput QuestionnaireResponseSubmitInput QuestionnaireSessionAttestInput
complianceQuestionnaireAmend complianceQuestionnaireInfer questionnaireAnswersSubmit questionnaireResponseSubmit questionnaireSessionAttest
Was this page helpful?