Skip to main content
Every operation belongs to one of your end users. You register users with the API, Kravata runs an automatic KYC review, and a user can operate once their status is APPROVED.

​
Register a user

Call User Registration with the user’s data and the x-integration-register header. Kravata gives you the value of that header when it configures your integration.
The response contains the user ID (user_id). Store it: you use it in every user endpoint, for example to register accounts and wallets or to create operations.
The fields that are required depend on the configuration of your integration. The endpoint reference lists the default set. If a required field is missing, the response says which one.
Always send a stable external_user_id, your own ID for that user. Kravata uses it to recognize the user when you send them again.

​
Update a user

There is no separate update endpoint: send the user again to the same User Registration endpoint. Kravata finds the existing user by external_user_id first, then by document number, phone and email, in that order.
  • If the user exists, Kravata updates the data and returns the same user_id. You don’t get a duplicate or a conflict.
    • Names and document data are replaced.
    • Contact data and additional fields are merged; the values you send win.
    • Kravata keeps a history of the previous values.
  • If no user matches, a new user is created.
How an update affects the status:
If the document you send belongs to a different user of your company, the request is rejected with 400 and a message like Webhook error: 409 - ... already exists. Check that you are not mixing up two users.

​
Check a user’s status

The KYC review is asynchronous: right after you register a user, their status is usually IN_REVIEW. Don’t rely on the registration response for the status. Instead:
  • Subscribe to the user.updated webhook, which fires when the status changes.
  • Or query Get Users (GET /api/v1/admin/users). It accepts page and pageSize (pagination applies only when you send both), orderBy, orderDirection, and numberPhone to filter by part of a phone number.

​
Statuses

Only APPROVED users can operate. Operations for any other user are rejected with 403.

​
How the KYC review works

After registration, Kravata checks the user against restrictive lists and PEP lists, applies its compliance rules and computes a risk score. The result sets the status:
  • No findings → APPROVED.
  • A finding that requires a manual review → EHD.
  • A blocking finding → REJECTED.
If a list provider is not available at that moment, the user goes to EHD instead of being approved without the check. The data you send affects the review: date of birth, occupation, PEP declaration, income, expenses, assets and liabilities, residence, document issue date, and source of funds. Send complete and accurate data to avoid unnecessary manual reviews. If your integration doesn’t send its own identity-verification results, or when a user is in REPROCESSING_REQUIRED, call Generate KYC Link (POST /api/v1/provider/kyc/user/generateurl/{user_id}). Send the user to the verificationUrl in the response. When the user finishes the verification, the status is updated and you receive user.updated.

​
User webhooks

The payload is the user as a flat JSON object. It includes userId, status, the names, identificationType, identificationNro and metadata; user.updated also includes tradeName and contactData. Metadata can include large values, such as documents encoded in Base64. See Webhooks to register your endpoint.

​
Errors