Skip to main content
The API method is the default KYC submission path. You collect identity documents and data from your user, upload them via POST /partner/files, and include the KYC data in the cardholder creation request.

​
Flow

  1. Upload documents via POST /partner/files
  2. Call POST /partner/cardholders with kycSource: "api" (or omit kycSource for backward compatibility)
  3. KYC data is stored and a backing Sumsub applicant is created automatically

​
Create a cardholder with API KYC

curl -X POST https://api.contro.me/v1/partner/cardholders \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_42",
    "kycSource": "api",
    "kycLevel": "LEVEL_1",
    "email": "jane@example.com",
    "phoneNumber": "+14155552671",
    "customerKycLevel1": {
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1990-01-01",
      "gender": "F",
      "idType": "passport",
      "idNo": "AB1234567",
      "idExpiryDate": "2030-01-01",
      "nationality": "US",
      "countryCode": "US",
      "idCardFrontImageUploadId": "upload_abc123",
      "facePhotoImageUploadId": "upload_def456",
      "email": "jane@example.com",
      "residenceCountryCode": "US"
    }
  }'
The kycSource field can be omitted — it defaults to "api" for backward compatibility. Existing integrations continue to work without changes.

​
Required fields

See Cardholders for the full field reference for customerKycLevel1, customerKycLevel2, and customerKycLevel3.

​
Sandbox behavior

In sandbox mode, KYC is auto-approved immediately. The Sumsub applicant creation step is skipped.