Onboarding & compliance lifecycle

After an account is created, Due sometimes needs more information from your user: to finish KYC, to open a new rail, to let a transfer through, or to answer a compliance question. This guide explains the objects involved one by one, lists every status, and then shows how to build on webhooks so you always know whether your user has something to do.

The building blocks

Submission: the form

A submission is a form your user fills in. It lists what Due needs (requirements: fields, documents, questionnaires, agreements) and holds what has been provided so far.

• Every time Due needs information from a user, it is collected through a submission. There is no other way to provide data.
• You fill it through the API (/v1/kyc/submissions/{id}/…) or send the user to a hosted link.
• It is editable while it is open. Once completed it is frozen: a correction is always a new submission, never an edit of the old one.

A submission tells you what to collect. It does not tell you why it is needed or whether it was accepted. That is what the next objects are for.

→ Submission statuses · How to fill one: Individual KYC process, Business KYB process · Hosted submission link

Information request: the reason and the review

An information request is Due asking for information, with a reason, and reviewing the answer. Think of it as a container for submissions rather than as a record of its own: it points to the submission being reviewed (submissionId), and if that submission needs correcting it opens another one and asks again.

Due raises an information request when it needs something beyond base KYC:

Information requests can appear at any time, including long after onboarding. Only those with kind: endorsement belong to an endorsement (their presetCode is the endorsement code).

→ Information request statuses · Requests for information on transfers · Video-identification EDD

Endorsement: a rail to unlock

An endorsement is an additional approval that unlocks specific channels, for example named EUR accounts or USD accounts at a partner bank (see endorsementsRequired in GET /v1/channels). You request it; if more information is needed, Due raises information requests for it. Once they are approved, the endorsement continues by itself.

→ Endorsement statuses · KYC/KYB endorsements

Account KYC: the base verification

kyc.status on the account is the result of base KYC/KYB. Base KYC is the one case with no information request: its form is a submission on its own, and the outcome shows on kyc.status.

→ Account KYC statuses · Handle KYC status webhooks · Sumsub KYC Sharing

How they fit together

The one rule to build on: your user has a task when a submission is open and it either belongs to an information request that is requested, or is a base-KYC submission while kyc.status is pending or resubmission_required. See What the user sees and Opening a task.

Statuses

Submission

stateDiagram-v2
    direction LR
    [*] --> open
    open --> processing: user completes
    processing --> completed

A submission only moves forward. Once it leaves open it can't be read or written through /v1/kyc/submissions/{id}, and its hosted link stops working.

Information request

stateDiagram-v2
    direction LR
    [*] --> requested
    [*] --> approved: nothing was missing
    requested --> on_review
    on_review --> approved
    on_review --> requested: resubmission needed, new submission
    on_review --> rejected
    rejected --> [*]
    approved --> expired: validity ended

If a review needs something corrected, the information request goes back to requested rather than being rejected. It keeps its id and carries a new submissionId, and that new submission is the user's task. Watch the status, not the id.

rejected is final. It is not a step on the way to another attempt.

An information request with submissionId: null needed nothing new and was created approved. A fast review can go from requested straight to approved or rejected.

Endorsement

There is no rejected. An endorsement can be requested only when kyc.status is passed. If nothing is missing it starts at processing or approved.

If an endorsement's information request is rejected, the endorsement stays requested. It does not move to an error status, and the rail does not open. Read the endorsement's information requests to know whether it is still progressing.

Account KYC

A status can change again after a review (for example passed → resubmission_required). Always act on the latest value.

Building on webhooks

What to store

Where each row first comes from

Store what your own calls return, and let webhooks create everything Due starts. A submission webhook for an id no information request claims is base KYC.

What each webhook carries

Body: { id, type, data, occurredAt, attemptedAt }. occurredAt is when Due recorded the event for delivery, not when the change itself happened, but it stays the same across redeliveries of the same event. ownerId is the account id everywhere.

Deliveries can be retried and can arrive out of order. Make handlers idempotent; keep a submission's latest status (it only moves forward), and for the other objects ignore events with an older occurredAt than the one you last applied.

What the user sees

function tasks(account):
    if account.status == "deactivated" or account.kycStatus == "failed":
        return []
    return submissions where accountId == account.id and status == "open" and (
             (informationRequestId is set and information_requests[informationRequestId].status == "requested")
          or (informationRequestId is empty and account.kycStatus in ["pending", "resubmission_required"]))

If there are no tasks, the user waits:

Opening a task

Get the link when the user taps the task; don't store it.

• Submission with an information request: POST /v1/information_requests/{informationRequestId}/session
• Base-KYC submission: POST /v1/kyc/sessions with {"submissionId": "…"}

Then open https://app.due.network/kyc_submissions/{submissionId}?token={token}.

• 422 err_kyc_submission_finalized means the submission was completed meanwhile: mark it as no longer open and refresh.
• A token lasts 7 days. A token being issued does not mean the submission is open; your submissions.status does.

To render the form yourself instead, use the submission's requirements, write through /v1/kyc/submissions/{id}/… and finish with POST /v1/kyc/submissions/{id}/complete.

What webhooks don't tell you

You don't need to track expiry. When an approved information request stops counting, Due raises a new one and you receive it as requested.

To repair one account's rows (missed delivery, new deployment), rebuild them from GET /v1/accounts/{id}, GET /v1/information_requests, GET /v1/kyc/submissions and GET /v1/kyc/endorsements.

When to contact Due

Mistakes to avoid

• Driving tasks from the information request's status. requested outlives the user's work; use submission.status == "open".
• Waiting for a webhook to learn an endorsement's submissions. They are in the response to your call.
• Guessing what a submission is for from presetCode. Use its information request; if none, it's base KYC.
• Treating an information request id as one round of review. The same id can be sent back to requested with a new submission.
• Treating requested as always meaning a first attempt. It also means a correction was asked for.
• Showing base-KYC submissions once kycStatus is passed or manual_review. Leftover submissions are not closed.
• Moving a submission backward because an older webhook arrived late.

Example: opening a rail that needs one more field

If the review needs something corrected, you receive information_request.updated (requested) for the same information request, now carrying a new submissionId. That new submission shows up as a task.

If the review rejects it, the information request becomes rejected and the endorsement stays requested. The rail does not open and there is nothing for the user to do.