Users
Advance the user application
https://api.firstleeward.com/v0/users/:id/applicationAdvances the user KYC application. Only valid while the application is in a pending state. Which verification method applies is fixed by your project configuration rather than chosen per request, and determines the request you send. With no body (First Leeward-run verification), First Leeward returns a provider SDK token in nextAction for the client to complete and approval arrives later via webhook. For Sumsub Token Sharing, a share token is ingested and the user moves to IN_REVIEW; the final decision arrives on the same compliance webhook as Managed KYC. For a full verified data pack, the response nextAction lists the supporting documents to upload via POST /users/:id/application/documents. Send an Idempotency-Key to safely retry without re-consuming a single-use share token.
Authorizations
Authorizationstring · headerrequiredAPI key as Bearer token, e.g. Bearer YOUR_API_KEY
Headers
Leeward-Versionenum<string>requiredAPI version (YYYY-MM-DD). Available option: 2026-09-18
Idempotency-KeystringUnique key for safely retrying this request. Up to 255 characters; we recommend a UUIDv4. The first request executes and its response is cached; subsequent requests with the same key replay the cached response (24h retention).
Path Parameters
idstring<uuid>requiredUser ID
Body
application/json
Option 1 · Managed KYC
methodstringrequiredOption 2 · Sumsub Token Sharing
methodstringrequiredtokenstringrequiredSumsub applicant share token
Option 3 · Universal KYC
methodstringrequiredproviderobjectrequiredThe verification the applicant completed
Show child attributes
namestringrequiredName of the KYC provider that performed the verification
statusstringrequiredOverall verification outcome reported by the provider
APPROVEDREJECTEDWARNINGNOT_EXECUTEDdataobject[]requiredRaw verification result payload from the provider
identityobjectrequiredVerified identity of the applicant
Show child attributes
firstNamestringrequiredGiven name
middleNamestringMiddle name
lastNamestringFamily name
fullNamestringrequiredFull legal name as verified
dateOfBirthstring<date>requiredDate of birth (YYYY-MM-DD)
nationalitystringrequiredNationality
documentsobjectrequiredMetadata for the supporting documents uploaded separately
Show child attributes
idDocumentobjectrequiredGovernment-issued identity document
Show child attributes
typestringrequiredIdentity document type
PASSPORTID_CARDDRIVERS_LICENCERESIDENCE_PERMITnumberstringrequiredDocument number as shown on the document
countrystringrequiredCountry that issued the document
issuingDatestring<date>Date the document was issued (YYYY-MM-DD), when available
expiryDatestring<date>Date the document expires (YYYY-MM-DD), when applicable
proofOfAddressobjectrequiredProof-of-address document
Show child attributes
typestringrequiredProof-of-address document type
ID_CARDDRIVERS_LICENCERESIDENCE_PERMITUTILITY_BILLUTILITY_BILL2numberstringrequiredDocument number as shown on the document
countrystringrequiredCountry that issued the document
issuingDatestring<date>Date the document was issued (YYYY-MM-DD), when available
expiryDatestring<date>Date the document expires (YYYY-MM-DD), when applicable
addressobjectrequiredResidential address of the applicant
Show child attributes
countrystringrequiredCountry
postCodestringPostal or ZIP code
streetstringStreet
townstringTown or city
subStreetstringAdditional street line
statestringState, province, or region
buildingNamestringBuilding name
flatNumberstringFlat, unit, or apartment number
buildingNumberstringBuilding or house number
formattedAddressstringrequiredFull address as a single formatted line
livenessobjectrequiredResult of the applicant liveness check
Show child attributes
resultstringrequiredLiveness-check outcome
APPROVEDREJECTEDWARNINGNOT_EXECUTEDcheckedAtstring<date-time>When the liveness check was performed (ISO 8601). Required unless the check was not executed.
jurisdictionDetailsobjectJurisdiction-specific KYC data required for certain BIN countries
Show child attributes
jurisdictionstringrequiredcountryOfBirthstringrequiredCountry of birth
economicActivitystringrequiredThe applicant's occupation or economic activity
authorityIdIssuerstringrequiredIssuer of the government identity document
INESREuboAttestationbooleanrequiredWhether the applicant has attested their ultimate beneficial ownership status
phonestringContact phone number. Required for Mexican nationals.
emailstring<email>Contact email address. Required for Mexican nationals.
taxIdstringMexican tax identifier (RFC). Required for Mexican nationals.
curpstringMexican population registry code (CURP). Required for Mexican nationals.
Option 4 · KYC Attestation
methodstringrequiredproviderobjectrequiredThe verification the applicant completed
Show child attributes
namestringrequiredName of the KYC provider that performed the verification
recordIdstringrequiredIdentifier of the verification record in the provider's system
identityobjectrequiredVerified identity of the applicant
Show child attributes
firstNamestringrequiredGiven name
lastNamestringrequiredFamily name
dateOfBirthstring<date>requiredDate of birth (YYYY-MM-DD)
idDocumentobjectrequiredGovernment-issued identity document
Show child attributes
typestringrequiredIdentity document type
PASSPORTID_CARDDRIVERS_LICENCEnumberstringrequiredDocument number
countrystringrequiredIssuing country
addressobjectrequiredResidential address of the applicant
Show child attributes
line1stringrequiredAddress line 1
line2stringrequiredAddress line 2. Must not be empty; when the address has no second line, use the district, area, or building name.
citystringrequiredCity
postCodestringPostal or ZIP code
countrystringrequiredCountry
Response
200Application state after advancing
providerstringDeprecated: use nextAction.provider. Populated only when nextAction.type is PROVIDER_SDK.
sdkTokenstringDeprecated: use nextAction.sdkToken. Populated only when nextAction.type is PROVIDER_SDK.
statusstringrequiredCurrent KYC application status
NOT_STARTEDAWAITING_DOCUMENTSIN_REVIEWAPPROVEDREJECTEDRETRY_REQUIREDnextActionobject | nullrequiredAction the client must take next, or null if none remains
Show child attributes
Option 1 · Provider SDK
typestringrequiredproviderstringrequiredSUMSUBsdkTokenstringrequiredToken for initializing the provider verification widget
Option 2 · Document upload
typestringrequireddocumentsobject[]requiredSupporting documents to upload, each with its current upload state
Show child attributes
typestringrequiredSupporting document category
IDENTITYPROOF_OF_ADDRESSCURPstatusstringrequiredReview state of this document
PENDINGUPLOADEDRETRY_REQUIREDREJECTED400Response for status 400
Option 1 · InvalidApplicationStatusError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 2 · SumsubTokenInvalidError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 3 · InvalidJurisdictionDataError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 4 · ApplicationSubmissionRejectedError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired403The requested verification method is not enabled for this project
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired404User not found
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired409Response for status 409
Option 1 · UserApplicationFinalizingError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 2 · SumsubTokenAlreadyUsedError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired422Response for status 422
Option 1 · SumsubApplicantNotApprovedError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 2 · SumsubApplicantIncompleteError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 3 · SumsubTokenLevelMismatchError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired503Service is temporarily unavailable. Please retry.
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired