Identity Verification (KYC)

Every individual user is verified in levels. Basic screening runs automatically when you create the user. Standard KYC verifies the user's identity document and selfie. Advanced KYC collects additional documents.

Before you start


Sandbox base URL	`https://sandbox-api.aparatech.io`
Authentication	HTTP Basic auth with your API username and password
`MID` header	Required only if your account uses merchants. Format: `customer_merchant_submerchant`

All endpoints on this page are under /v1/public.

Levels

Level	What is checked	How it runs
Basic	Screening of the details sent when the user is created	Automatically, after Create user
Standard	Identity document and selfie	Hosted flow, Sumsub import, or document upload

Flow

Create the user. You receive a userId, and basic screening starts.
Wait for basic screening to be approved.
Run Standard KYC using one of the three methods.
Check the KYC status.

Step 1: Create the user

POST /v1/public/users/individual

curl --location 'https://sandbox-api.aparatech.io/v1/public/users/individual' \
  -u 'USERNAME:PASSWORD' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "isAgeAllowed": true,
    "email": "john.doe@example.com",
    "phone": "2125551234",
    "phoneCode": "+1",
    "country": "US",
    "countryOfResidence": "US",
    "date": "15-06-1990",
    "gender": "male",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    }
  }'

Field	Required	Format
`firstName`	Yes	1–50 characters
`lastName`	Yes	1–50 characters
`isAgeAllowed`	Yes	Boolean. Confirms the user is at least 18 and not more then 70. `false` is rejected with `AGE_LIMIT_ERROR`
`email`	Yes	Valid email, up to 100 characters
`phone`	Yes	8–15 digits, without the country code
`phoneCode`	Yes	Country calling code, for example `+1`
`country`	Yes	ISO 3166-1 alpha-2 code, for example `US`
`countryOfResidence`	Yes	ISO 3166-1 alpha-2 code
`address.street`	Yes	Text
`address.city`	Yes	Text
`address.state`	Yes	Text
`address.postalCode`	Yes	Text
`date`	No	Date of birth, `DD-MM-YYYY`. When sent, the user must be at least 18
`gender`	No	`male` or `female`

Response

{
  "status": "success",
  "data": {
    "userId": "UX-261102080659432863"
  }
}

If a user with the same email or phone already exists, the response returns that user's userId with "code": "USER_ALREADY_EXISTS". Store the userId: every KYC call needs it.

Step 2: Wait for basic screening

Basic screening runs in the background after the user is created. Until it is approved, hosted verification and Sumsub import return BASIC_KYC_NOT_APPROVED.

To check it

curl --location 'https://sandbox-api.aparatech.io/v1/public/users/individual?email=john.doe@example.com' \
  -u 'USERNAME:PASSWORD'

Step 3: Run Standard KYC

Method	When to use it	Endpoint
Hosted verification (default)	The user completes verification on the Apara page	`POST /v1/public/kyc/standard`

Hosted verification

curl --location 'https://sandbox-api.aparatech.io/v1/public/kyc/standard' \
  -u 'USERNAME:PASSWORD' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "UX-261102080659432863",
    "redirectUrl": "https://yourapp.example.com/kyc/complete"
  }'

Field	Required	Format
`userId`	Yes	The `userId` from Create user, starts with `UX-`
`redirectUrl`	Yes	Valid URL. The user returns here after verification

{
  "status": "success",
  "data": {
    "userId": "UX-261102080659432863",
    "kycUrl": "https://sandbox-pay-widget.aparatech.io/user/initiate-kyc?token=..."
  }
}

Send the user to kycUrl. When they finish, they return to your redirectUrl. Then check the status.

Step 4: Check the KYC status

GET /v1/public/kyc/status/{userId}

curl --location 'https://sandbox-api.aparatech.io/v1/public/kyc/status/UX-261102080659432863' \
  -u 'USERNAME:PASSWORD'

{
  "rejectLabels": [],
  "status": "kyc_success"
}

status is the user's current status. rejectLabels lists the reasons when verification is rejected, and is empty otherwise. This response is not wrapped in status and data.

Statuses

Status	Meaning
`user_created`	User created. Basic screening has not finished
`user_approved`	Basic screening approved
`user_rejected`	Basic screening rejected. KYC cannot be started
`kyc_initiated`	Hosted Standard KYC started. Waiting for the user
`kyc_manual_review`	Under manual review
`kyc_success`	Standard KYC approved
`kyc_failed`	Verification failed
`kyc_rejected`	Verification rejected. See `rejectLabels`
`kyc_expired`	Verification expired
`kyc_blocked`	User blocked

Was this page helpful?