KYC / Identity Verification

Individual end-users must verify their identity before they can trade. Coinify runs the verification itself: you start an identification attempt, send the end-user to Coinify's verification flow, and find out the result once it is processed.

ℹ️

Using the Trade Widget or SDK? The widget handles identity verification for the end-user, so there is nothing to implement. This page applies to Full API Integration →.

Corporate users don't go through KYC. They complete a KYB document review instead, which Coinify triggers by email. See Mandatory User Information →.


How it works

  1. Initiate an identification attempt for the authenticated end-user.
  2. Redirect the end-user to the redirectUrl returned in the response.
  3. The end-user completes verification on Coinify's side and is returned to your returnUrl.
  4. Wait for the final result, which arrives as a webhook (or can be fetched via API).

KYC is the last step of the individual onboarding sequence. The end-user's address must already be provided, along with the other mandatory information →, before you initiate an attempt.


Step 1: Initiate the identification attempt

Call Initiate identification attempt → with the end-user's access token:

POST https://app-api.sandbox.coinify.com/kyc/identification-attempts
Authorization: Bearer <access_token>
{
  "returnUrl": "https://yourapp.com/kyc-complete",
  "deviceType": "desktop"
}
ParameterDescription
returnUrlRequired. Where the end-user is sent after completing (or failing) verification.
deviceTypeOptional: android, ios or desktop. Helps Coinify tailor the experience. If omitted, it is detected from the request's User-Agent header.
ℹ️

If you call this endpoint from your backend rather than from the end-user's device, pass deviceType explicitly, because the User-Agent your server sends won't reflect the end-user's device.

The response is an identification attempt → object containing the attempt's id, its state, the redirectUrl, and the expireTime after which the link is no longer valid.


Step 2: Redirect the end-user

Send the end-user to the redirectUrl. This is where they actually verify their identity. Nothing happens until they visit it.

ℹ️

Identification attempts expire. Once an attempt has expired, its redirectUrl can no longer be used to complete verification. If the end-user comes back after that, call Initiate identification attempt → again to get a new attempt and a fresh redirectUrl.

⚠️

Camera access is required. Identity verification uses the end-user's device camera. We recommend a full-page redirect (or opening the redirectUrl in the device's browser) and handling the return via returnUrl. If you use an in-app webview or iframe, make sure it has camera permission.


Step 3: Handle the return

When the end-user finishes, Coinify redirects them to your returnUrl with a result query parameter appended:

resultMeaning
submittedThe end-user submitted their documents.
failedThe end-user failed to submit their identification.

For example, https://yourapp.com/kyc-complete becomes https://yourapp.com/kyc-complete?result=submitted. Any query parameters already on your returnUrl are preserved.

ℹ️

result=submitted does not mean the end-user is approved. It only means the documents were handed over. Verification is processed afterwards, so show a "verification in progress" screen rather than letting them trade.


Step 4: Get the final result

An identification attempt moves through these states:

StateTypeMeaning
pendingStartingThe attempt was initiated and is waiting for the end-user to complete verification.
approvedFinalThe attempt was approved. Also used when a manual review ended in approval.
rejectedFinalThe attempt was rejected. The rejectReason field says why.

Rather than polling, listen for the webhook events identification-attempt.approved and identification-attempt.rejected. See Webhook Events →. You can also fetch the current state with Get identification attempt info →, or see all of an end-user's attempts with List identification attempts →.

Rejection reasons

rejectReasonMeaning
DENIED_UNSUPPORTED_ID_COUNTRYThe ID document was issued in a country Coinify doesn't support.
MANUAL_REVIEWThe attempt is under manual review by Coinify compliance. This is not a final decision.

Other reasons may also be returned. See all Reject reasons →.

ℹ️

Manual review can take 1-3 days. Coinify emails the end-user the final decision and sends the corresponding webhook to your endpoint. Tell the end-user their verification is under review, and don't present it as a rejection.


Testing in sandbox

You can approve an identification attempt instantly without going through the process itself in Sandbox environment. See Skipping KYC in sandbox → on the Sandbox & Testing page.


Next steps


Did this page help you?