{
  "id": "p_LxU31Eqk2H8nN1cx",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_LxU31Eqk2H8nN1cx",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "You are two days from shipping the signup flow for a cross-border payments product. Before any customer can move money, they have to get through KYC or KYB, and you have been asked to pick how that happens. Sending people to a hosted page is the easy route. Driving verification from your own screens is the better experience, if the API underneath it holds up. So you open the Due KYC API on APIs.io and start reading.\n\nDue is a London-founded payments infrastructure company that bridges banking rails and blockchain networks for cross-border transfers and fiat-to-stablecoin ramps. Its KYC API is the onboarding half of that business. The contract is OpenAPI 3.2.0, with a production server at api.due.network, a sandbox at api.sandbox.due.network, and bearer auth across the board.\n\nThe 17 operations fall into four groups. Four make up the standard flow: get the hosted KYC/KYB link, initiate, create an access session, and share an existing Sumsub applicant. Nine make up submissions. Three cover endorsements, and one creates a KYC session.\n\nThe submissions group is the part that catches your eye. It is a full programmatic path through verification without the hosted link. You list and get submissions, provide applicant info, add questionnaire answers, set relations, create a child applicant, request an upload token, upload documents and mark the submission complete. The schemas look built for it. Requirements come back as a oneOf with a kind discriminator (static, oneOf, conditional), and questionnaire questions are typed: multiple choice, multiple countries, number, text, files. You start sketching your screens.\n\nThen you look at the responses, and this is the finding. Every one of the 17 operations documents exactly one response: 200 OK. A verification flow is mostly made of things that go wrong. A document fails. An applicant is missing information. A submission is not ready to complete. The contract describes none of them. You cannot tell what a rejected document returns, or what an incomplete submission returns, so you will find out at runtime.\n\nThere are two more things to watch. There are two session endpoints whose names differ by one letter. POST /v1/kyc/session takes no body and returns a KYCSession. POST /v1/kyc/sessions takes a JSON body and returns a JwtToken. The contract does not say when to use which. And three endorsement operations carry summaries marked x-summary-source: derived, such as \"Get v1 kyc endorsements code\". Those were written by the catalog because Due's fragments had none, so nothing in the contract says what an endorsement is.\n\nHere the post turns on its own record, and you should read that part carefully before you trust any of it. The catalog assembled this contract from Due's per-operation OpenAPI fragments on due.readme.io, and the counts disagree with each other. The API page description says 15 operations, while its own operation list holds 17. The overview says Due publishes 18 APIs on the network, while the provider record counts 1. Those are the catalog's own seams to fix, not Due's. The scores are in the same spirit: Due scores 48.3 on the Kin Score (developing) and 26.0 on Agent Readiness (agent-aware). The provider also carries an Arazzo workflow named \"Onboard a customer account with KYC/KYB\", which strings these calls together.\n\nSo you have a decision with an honest shape. The submissions path is a real alternative to sending users to a hosted page, and the typed requirement schemas show it was built for that. But the contract will not tell you how it fails.\n\nWhat you take away is a short list. Build your error handling from the sandbox, not from the contract. Confirm which session endpoint your flow needs before you ship. Treat the derived endorsement summaries as the catalog's words, not Due's. And do not lean on the operation counts until the catalog reconciles them. You close the tab and open the sandbox.\n\nRead the original: https://apis.io/2026/11/09/due-kyc-api-documents-17-operations-and-only-one-response-code/",
  "title": "Your onboarding flow just got a 17-operation contract with one answer",
  "topics": [
    "kyc-api",
    "error-handling",
    "api-contracts",
    "payments-onboarding"
  ],
  "published_at": "2026-11-09T14:39:55.375Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}