DOCS

Answer compliance questions via API

For pharmacies: get a webhook when a shipment needs FDA personal-import answers, read what is open, and submit everything in one call. Samples use example names and contact details.

When this starts. You can register and test your webhook today, so you are ready for January 20, 2027, when Type 13 entries are required. Zonos uses webhooks to obtain this information when making Type 13 entries. We are also testing this flow with a few shippers. If you would like to take part, contact support@zonos.com or your Zonos rep.

How it works 

When one of your shipments needs per-shipment compliance answers, Zonos sends your server a webhook with a session ID. You read that session once and submit every answer in one call.

  1. Register. Create a COMPLIANCE_COLLECT_REQUEST webhook once per environment.
  2. Receive. Zonos posts {eventType, sessionId} to your URL.
  3. Read. Query the session for its lines and open questions.
  4. Submit. Send all answers in one questionnaireAnswersSubmit per line.

Before you go live

  • All requests go to https://api.zonos.com/graphql with your credential in the credentialToken header.
  • Your credential needs WEBHOOK_WRITE (register and test), COMPLIANCE_READ (read sessions) and COMPLIANCE_WRITE (submit answers).
  • Answer each product's catalog questions once (drug name, manufacturer). Then shipment sessions only ask the short per-shipment questions in this guide.
  • Webhooks belong to a mode. Register your production URL with your LIVE credential and a staging URL with your TEST credential.

1. Register your webhook 

Do this once with your LIVE credential and once with your TEST credential. Store the returned secret on your server: it signs every delivery. Zonos generates it, and it cannot be set or rotated. If you lose it, read it again with webhook(id: "<id>") { secret }.

Request

POST https://api.zonos.com/graphql
Content-Type: application/json
credentialToken: <your LIVE or TEST credential>

mutation {
  webhookCreate(input: {
    type: COMPLIANCE_COLLECT_REQUEST
    status: ENABLED
    url: "https://pharmacy.example.com/zonos/compliance"
  }) {
    id
    type
    status
    url
    mode
    secret
  }
}

Response

{
  "data": {
    "webhookCreate": {
      "id": "webhook_e3ecd323-1939-485f-9eea-5de47175c2a0",
      "type": "COMPLIANCE_COLLECT_REQUEST",
      "status": "ENABLED",
      "url": "https://pharmacy.example.com/zonos/compliance",
      "mode": "TEST",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}
Field↕Type↕What to do with it↕
idIDKeep it if you want to update or delete the webhook later.
modeLIVE or TESTSet by the credential you registered with.
secretStringStore securely. Used to verify the zonos-signature header.
urlStringWhere Zonos will POST deliveries.

2. Receive the webhook 

Zonos sends one POST per shipment session that needs answers. Respond with any 2xx quickly and do the work afterwards.

Delivery to your URL

POST https://pharmacy.example.com/zonos/compliance
Content-Type: application/json
Accept: application/json
zonos-signature: timestamp=1791327122874,hmac=YOUR_BASE64_HMAC
checksum: YOUR_HEX_CHECKSUM

{"eventType":"COMPLIANCE_COLLECT_REQUEST","sessionId":"questionnaire_session_0rva0ybvxp1gp"}
Field↕Type↕What to do with it↕
eventTypeStringAlways COMPLIANCE_COLLECT_REQUEST for this webhook.
sessionIdIDMap to your order. Pass it to the session query in step 3.
zonos-signatureHeadertimestamp=<ms>,hmac=<base64>. Verify the hmac before trusting the body.
checksumHeaderA separate hex HMAC keyed with your API credential, not the webhook secret. You can ignore it once you verify zonos-signature.

Verify the signature

  1. Take the hmac value from the zonos-signature header.
  2. Compute HMAC-SHA256 of the raw request body bytes, keyed with your webhook secret, and Base64-encode it.
  3. Compare the two in constant time. If they differ, respond 401 and do nothing else.

Hash the body exactly as it arrived. Parsing the JSON and re-serializing it changes the bytes, and the hash will not match. The timestamp is the send time in milliseconds but is not part of the signed data, so do not rely on it to block replays.

Verify the signature (Node.js / Express)

import crypto from "node:crypto";
import express from "express";

const app = express();

// express.raw keeps the body as the exact bytes Zonos signed.
app.post("/zonos/compliance", express.raw({ type: "application/json" }), (req, res) => {
  if (!isFromZonos(req.body, req.get("zonos-signature"), process.env.ZONOS_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);
  const { sessionId } = JSON.parse(req.body);
  // Queue sessionId for steps 3 and 4.
});

function isFromZonos(rawBody, signatureHeader = "", webhookSecret) {
  // signatureHeader looks like "timestamp=1791327122874,hmac=G/yrP1..."
  const received = signatureHeader.split(",").find(part => part.startsWith("hmac="))?.slice(5) ?? "";
  const expected = crypto.createHmac("sha256", webhookSecret).update(rawBody).digest("base64");
  // timingSafeEqual throws on unequal lengths, so check length first.
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

3. Read the session 

One query tells you what is open. Each line is one program (such as US_FDA) for one item, and you answer each line separately.

Request

POST https://api.zonos.com/graphql
Content-Type: application/json
credentialToken: <your credential>

query ReadSession($id: ID!) {
  questionnaireSession(id: $id) {
    status
    containerType
    containerId
    lines {
      id
      status
      targetType
      answerScopes
      program { name }
      currentQuestion { code answerType answerScope prompt }
      visibleQuestions(requirements: [REQUIRED]) {
        question { code answerType answerScope requirement prompt options { value label } }
        answer { value }
      }
    }
  }
}

{ "id": "questionnaire_session_0rv8xh6y3xpbm" }

Response: prescription drug, US resident

{
  "data": {
    "questionnaireSession": {
      "status": "IN_PROGRESS",
      "containerType": "CONSIGNMENT",
      "containerId": "consignment_0rv8xh4vhdsem",
      "lines": [
        {
          "id": "questionnaire_session_line_0rv8xh6ybxpby",
          "status": "IN_PROGRESS",
          "targetType": "ITEM",
          "answerScopes": [
            "ITEM"
          ],
          "program": {
            "name": "US_FDA"
          },
          "currentQuestion": {
            "code": "fda_pip_treatment_basis",
            "answerType": "SINGLE_SELECT",
            "answerScope": "ITEM",
            "prompt": "Who is looking after this treatment?"
          },
          "visibleQuestions": [
            {
              "question": {
                "code": "fda_recipient_us_person",
                "answerType": "BOOLEAN",
                "answerScope": "ITEM",
                "requirement": "REQUIRED",
                "prompt": "Is the person receiving this medication a US citizen or permanent resident?",
                "options": []
              },
              "answer": {
                "value": "true"
              }
            },
            {
              "question": {
                "code": "fda_pip_treatment_basis",
                "answerType": "SINGLE_SELECT",
                "answerScope": "ITEM",
                "requirement": "REQUIRED",
                "prompt": "Who is looking after this treatment?",
                "options": [
                  {
                    "value": "US_PHYSICIAN",
                    "label": "A doctor licensed in the United States"
                  },
                  {
                    "value": "BEGUN_ABROAD",
                    "label": "No US doctor — this continues a treatment started in another country"
                  }
                ]
              },
              "answer": null
            },
            {
              "question": {
                "code": "fda_recipient_name",
                "answerType": "TEXT",
                "answerScope": "ITEM",
                "requirement": "REQUIRED",
                "prompt": "What is the full name of the person making this certification?",
                "options": []
              },
              "answer": null
            },
            {
              "question": {
                "code": "fda_recipient_phone",
                "answerType": "TEXT",
                "answerScope": "ITEM",
                "requirement": "REQUIRED",
                "prompt": "What is the certifier's phone number?",
                "options": []
              },
              "answer": null
            },
            {
              "question": {
                "code": "fda_recipient_email",
                "answerType": "TEXT",
                "answerScope": "ITEM",
                "requirement": "REQUIRED",
                "prompt": "What is the certifier's email address?",
                "options": []
              },
              "answer": null
            },
            {
              "question": {
                "code": "fda_pip_resident_attest",
                "answerType": "CHECKBOX",
                "answerScope": "ITEM",
                "requirement": "REQUIRED",
                "prompt": "I attest that the following is true and correct to the best of my knowledge and belief: …",
                "options": []
              },
              "answer": null
            }
          ]
        }
      ]
    }
  }
}
Field↕Type↕What to do with it↕
statusIN_PROGRESS or COMPLETEDCOMPLETED means nothing is left to answer.
containerIdIDThe Zonos shipment the session belongs to.
lines[].idIDMap to lineId when submitting.
lines[].program.nameStringWhich program the line is for, such as US_FDA.
lines[].statusIN_PROGRESS or COMPLETEDSkip lines that are already COMPLETED.
lines[].visibleQuestions[].question.codeStringMap to questionCode. See the question reference.
lines[].visibleQuestions[].question.answerTypeEnumDecides how to encode value.
lines[].visibleQuestions[].question.options[].valueStringAllowed values for SINGLE_SELECT questions.
lines[].visibleQuestions[].answerObject or nullAlready answered (often by Zonos). You can still send your own value.

Follow-up questions are not listed until they apply. The physician name and address only become visible after fda_pip_treatment_basis is US_PHYSICIAN. Send them anyway in the same call. Zonos accepts answers to follow-ups that your own answers unlock.

4. Submit all answers 

Send every answer for a line in one call. The response tells you whether the line, and the whole session, is done.

Request

POST https://api.zonos.com/graphql
Content-Type: application/json
credentialToken: <your credential>

mutation SubmitAnswers($input: QuestionnaireAnswersSubmitInput!) {
  questionnaireAnswersSubmit(input: $input) {
    status
    lines {
      id
      status
      currentQuestion { code }
    }
  }
}

{
  "input": {
    "sessionId": "questionnaire_session_0rv8xh6y3xpbm",
    "lineId": "questionnaire_session_line_0rv8xh6ybxpby",
    "answers": [
      {
        "questionCode": "fda_recipient_us_person",
        "value": "true"
      },
      {
        "questionCode": "fda_pip_treatment_basis",
        "value": "\"US_PHYSICIAN\""
      },
      {
        "questionCode": "fda_pip_physician_name",
        "value": "\"Dr. Maria Alvarez\""
      },
      {
        "questionCode": "fda_pip_physician_address",
        "value": "\"975 S Tech Ridge Dr, St George, UT 84770\""
      },
      {
        "questionCode": "fda_recipient_name",
        "value": "\"Jane Doe\""
      },
      {
        "questionCode": "fda_recipient_phone",
        "value": "\"+14355550100\""
      },
      {
        "questionCode": "fda_recipient_email",
        "value": "\"jane.doe@example.com\""
      },
      {
        "questionCode": "fda_pip_resident_attest",
        "value": "true"
      }
    ]
  }
}

Response: done

{
  "data": {
    "questionnaireAnswersSubmit": {
      "status": "COMPLETED",
      "lines": [
        {
          "id": "questionnaire_session_line_0rv8xh6ybxpby",
          "status": "COMPLETED",
          "currentQuestion": null
        }
      ]
    }
  }
}

Response: something still missing

{
  "data": {
    "questionnaireAnswersSubmit": {
      "status": "IN_PROGRESS",
      "lines": [
        {
          "id": "questionnaire_session_line_0rv8xh6ybxpby",
          "status": "IN_PROGRESS",
          "currentQuestion": {
            "code": "fda_pip_resident_attest"
          }
        }
      ]
    }
  }
}
Field↕Type↕Where it comes from and what it means↕
input.sessionIdIDFrom the webhook.
input.lineIdIDFrom lines[].id in step 3.
input.answers[].questionCodeStringFrom the question reference.
input.answers[].valueJSON-encoded stringEncoded by answerType. See the table below.
statusIN_PROGRESS or COMPLETEDCOMPLETED means you are done.
lines[].currentQuestion.codeString or nullIf a line is still IN_PROGRESS, this names the next missing question.

Encoding value

answerType↕Encoding↕Example↕
BOOLEANtrue or false, unquoted"true"
CHECKBOXtrue when ticked, unquoted"true"
TEXTA JSON string: the text wrapped in quotes"\"Jane Doe\""
SINGLE_SELECTA JSON string holding one option value"\"US_PHYSICIAN\""
NUMBERA bare number"3"
DOCUMENTOptional uploads, not covered by this guiden/a

Shipments with more than one line

Each item gets its own line, so a shipment with two drugs has two. Send one questionnaireAnswersSubmit per line, aliased, in the same request. The last one to finish returns the session as COMPLETED.

Request: two lines, one HTTP call

1
2
3
4
5
6
7
8
9
10
11
12
13
# One shipment with two drugs: one US_FDA line per item.
mutation SubmitShipment {
  firstDrug: questionnaireAnswersSubmit(input: {
    sessionId: "questionnaire_session_0rv8xh6y3xpbm"
    lineId: "<lines[0].id>"
    answers: [ { questionCode: "fda_recipient_us_person", value: "true" }, ... ]
  }) { status }
  secondDrug: questionnaireAnswersSubmit(input: {
    sessionId: "questionnaire_session_0rv8xh6y3xpbm"
    lineId: "<lines[1].id>"
    answers: [ { questionCode: "fda_recipient_us_person", value: "true" }, ... ]
  }) { status }
}

Question reference: drugs 

Which questions you get depends on the product's catalog answers (prescription or over-the-counter) and on the patient. All of them are ITEM scope, answered per shipment.

Prescription drug, patient is a US citizen or permanent resident

Required: 8 answers with a US prescriber, or 6 when the treatment began abroad (no physician questions).

questionCode↕answerType↕Required↕Prompt shown↕What to send↕Sample value↕
fda_recipient_us_personBOOLEANRequiredIs the person receiving this medication a US citizen or permanent resident?Patient residency. US citizen or permanent resident: true.true
fda_pip_treatment_basisSINGLE_SELECTRequiredWho is looking after this treatment?Prescriber. US-licensed prescriber: US_PHYSICIAN. Treatment started abroad with no US prescriber: BEGUN_ABROAD."US_PHYSICIAN"
fda_pip_physician_nameTEXTRequired if US_PHYSICIANWhat is the doctor's full name?Prescriber full name."Dr. Maria Alvarez"
fda_pip_physician_addressTEXTRequired if US_PHYSICIANWhat is the doctor's address?Prescriber practice address: street, city, state, ZIP."975 S Tech Ridge Dr, St George, UT 84770"
fda_recipient_nameTEXTRequiredWhat is the full name of the person making this certification?Patient, or the person certifying on their behalf."Jane Doe"
fda_recipient_phoneTEXTRequiredWhat is the certifier's phone number?Certifier phone, E.164 recommended."+14355550100"
fda_recipient_emailTEXTRequiredWhat is the certifier's email address?Certifier email."jane.doe@example.com"
fda_pip_resident_attestCHECKBOXRequiredI attest … serious medical condition; not an unreasonable risk; no more than a 3-month supply … (the full statement is shown with the question)Only true when the patient (or certifier) actually agreed to this statement.true

Prescription drug, patient is visiting the US

Required: 5 answers. The treatment-basis, physician and resident questions do not apply.

questionCode↕answerType↕Required↕Prompt shown↕What to send↕Sample value↕
fda_recipient_us_personBOOLEANRequiredIs the person receiving this medication a US citizen or permanent resident?Patient is in the US temporarily (visiting, studying, working): false.false
fda_recipient_nameTEXTRequiredWhat is the full name of the person making this certification?Patient, or the person certifying on their behalf."Jane Doe"
fda_recipient_phoneTEXTRequiredWhat is the certifier's phone number?Certifier phone."+14355550100"
fda_recipient_emailTEXTRequiredWhat is the certifier's email address?Certifier email."jane.doe@example.com"
fda_pip_visitor_attestCHECKBOXRequiredI attest … for a foreign national visiting the United States; no more than a 90-day supply … (the full statement is shown with the question)Only true when the certifier agreed to this statement.true
fda_recipient_passportDOCUMENTOptionalA copy of their passport or visaOptional upload. Not needed to complete.n/a
fda_recipient_prescriptionDOCUMENTOptionalA copy of the prescription, or a letter from the doctorOptional upload. Not needed to complete.n/a

Over-the-counter drug

Required: 4 answers. There is no residency question.

questionCode↕answerType↕Required↕Prompt shown↕What to send↕Sample value↕
fda_recipient_nameTEXTRequiredWhat is the full name of the person making this certification?Patient, or the person certifying on their behalf."Jane Doe"
fda_recipient_phoneTEXTRequiredWhat is the certifier's phone number?Certifier phone."+14355550100"
fda_recipient_emailTEXTRequiredWhat is the certifier's email address?Certifier email."jane.doe@example.com"
fda_pip_otc_attestCHECKBOXRequiredI attest … not for treatment of a serious condition; no known significant health risk; no more than a 3-month supply … (the full statement is shown with the question)Only true when the certifier agreed to this statement.true
fda_pip_letterDOCUMENTOptionalA letter confirming the medication is for personal useOptional upload. Not needed to complete.n/a

Recipient name, phone and email always go together in the same submit call. They are stored as one person.

Testing 

Use your TEST credential to fire a real test webhook at your registered TEST URL. It opens a real session for one of your catalogued products, so you can run steps 2 to 4 end to end. Test sessions are never filed with customs.

Request

POST https://api.zonos.com/graphql
Content-Type: application/json
credentialToken: <your TEST credential>

mutation {
  webhookTestSend(input: {
    type: COMPLIANCE_COLLECT_REQUEST
    complianceCollectRequest: { catalogItemId: "catalog_item_0rva0tsp86xqq" }
  }) {
    referenceId
    type
  }
}

Response

{
  "data": {
    "webhookTestSend": {
      "referenceId": "questionnaire_session_0rva0ybvxp1gp",
      "type": "COMPLIANCE_COLLECT_REQUEST"
    }
  }
}
Field↕Type↕Notes↕
input.typeWebhookTypeCOMPLIANCE_COLLECT_REQUEST.
input.complianceCollectRequest.catalogItemIdIDA catalog item whose catalog questions you have answered.
referenceIdIDThe session ID. The same ID arrives in the webhook.

Errors you may see 

Call↕When↕Message↕Fix↕
questionnaireAnswersSubmitRecipient name, phone or email sent without the other twoThe certifier's phone number, email address must be supplied with the rest of their details (fda_recipient_phone, fda_recipient_email): they are recorded as one party, not as separate answers.Always send all three together.
webhookTestSendType has no test supportTest webhooks are not supported for type ORDER_CREATEDUse COMPLIANCE_COLLECT_REQUEST.
webhookTestSendCalled with a LIVE credentialTest webhooks can only be sent with a TEST-mode credentialUse your TEST credential.
webhookTestSendNo enabled TEST webhook registeredRegister an enabled TEST-mode webhook of type COMPLIANCE_COLLECT_REQUEST before sending a testRun webhookCreate with your TEST credential first.
webhookTestSendcatalogItemId missingcomplianceCollectRequest.catalogItemId is required for COMPLIANCE_COLLECT_REQUESTPass the catalog item ID.
webhookTestSendCatalog item has nothing left to ask per shipmentCatalog item <id> has no open per-shipment compliance questions to testPick a catalog item that needs per-shipment answers, such as a prescription drug.

Was this page helpful?


Get support·Legal docs·© 2026 Zonos