Skip to main content
Submit KYC data for an individual customer. The customer must already exist in your account (created via POST /customer). After submission the status will be "submitted" and will move to "approved" once review is complete.
This endpoint is hosted on the KYC platform at https://kyc.yativo.com, not the main API base URL. Include an Idempotency-Key header on every request.
POST https://kyc.yativo.com/api/individual-kyc/submit

Identity fields

customer_id
string
required
The customer UUID returned by POST /customer.
first_name
string
required
Customer’s first name. Max 1024 characters.
last_name
string
required
Customer’s last name. Max 1024 characters.
middle_name
string
Customer’s middle name. Optional.
email
string
required
Customer’s email address.
calling_code
string
required
Country dial code. Must match ^\+\d{1,4}$, e.g. "+1", "+44", "+234".
phone
string
required
Phone number digits only, 8–15 characters. Do not include the country code.
birth_date
string
required
Date of birth in YYYY-MM-DD format. Must be before today.
nationality
string
required
ISO 3166-1 alpha-2 country code, e.g. "US", "NG", "BR".
gender
string
required
"male" or "female".
taxId
string
required
Tax identification number. Max 100 characters.
selfie_image
string
required
Selfie photo of the customer. Provide as a hosted URL (from POST /storage/upload) or a base64-encoded string. Accepted formats: PDF, JPG, JPEG, PNG, HEIC, TIF. Max 5 MB.
bvn
string
Bank Verification Number. Required when nationality is "NG". Exactly 11 digits.
nin
string
National Identification Number. Required when nationality is "NG". Exactly 11 digits.

Residential address

residential_address
object
required
Customer’s current residential address.

Identifying information

identifying_information
array
required
At least one government-issued ID document. Accepted document types depend on issuing_country — see the ID types reference.

Risk and purpose

employment_status
string
required
Customer’s employment status. One of: "employed", "exempt", "homemaker", "retired", "self_employed", "student", "unemployed".
most_recent_occupation_code
string
required
6-digit occupation code. Retrieve the full list from GET /auth/occupation-codes. Example: "151252" (Software developer).
expected_monthly_payments_usd
string
required
Expected monthly transaction volume. One of: "0_4999", "5000_9999", "10000_49999", "50000_plus".
source_of_funds
string
required
Primary source of funds. One of: "salary", "business_income", "company_funds", "savings", "investments_loans", "inheritance", "gifts", "government_benefits", "pension_retirement", "sale_of_assets_real_estate", "ecommerce_reseller", "gambling_proceeds", "someone_elses_funds".
account_purpose
string
required
Intended use of the account. One of: "receive_salary", "business_transactions", "purchase_goods_and_services", "personal_or_living_expenses", "payments_to_friends_or_family_abroad", "receive_payment_for_freelancing", "investment_purposes", "protect_wealth", "ecommerce_retail_payments", "operating_a_company", "charitable_donations", "other".
account_purpose_other
string
Required when account_purpose is "other". Provide a plain-text description.
acting_as_intermediary
boolean
Set to true if the customer is acting on behalf of third parties. Defaults to false.

Supporting documents

uploaded_documents
array
required
At least one supporting document is required.
curl -X POST 'https://kyc.yativo.com/api/individual-kyc/submit' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: kyc-ind-2026-001' \
  -d '{
    "customer_id": "c586066b-0f29-468f-b775-15483871a202",
    "first_name": "Alex",
    "last_name": "Smith",
    "email": "alex.smith@example.com",
    "calling_code": "+1",
    "phone": "5551234567",
    "gender": "male",
    "birth_date": "1990-01-15",
    "nationality": "US",
    "taxId": "998-88-7766",
    "selfie_image": "https://storage.yativo.com/documents/abc/selfie.jpg",
    "residential_address": {
      "street_line_1": "123 Maple Street",
      "city": "Austin",
      "state": "TX",
      "postal_code": "78701",
      "country": "US",
      "proof_of_address_file": "https://storage.yativo.com/documents/abc/utility-bill.pdf"
    },
    "identifying_information": [
      {
        "type": "passport",
        "issuing_country": "US",
        "number": "P12345678",
        "date_issued": "2019-06-01",
        "expiration_date": "2029-06-01",
        "image_front_file": "https://storage.yativo.com/documents/abc/passport-front.jpg"
      }
    ],
    "employment_status": "employed",
    "most_recent_occupation_code": "151252",
    "expected_monthly_payments_usd": "0_4999",
    "source_of_funds": "salary",
    "account_purpose": "receive_salary",
    "acting_as_intermediary": false,
    "uploaded_documents": [
      {
        "type": "bank_statement",
        "file": "https://storage.yativo.com/documents/abc/bank-statement.pdf"
      }
    ]
  }'
const response = await fetch('https://kyc.yativo.com/api/individual-kyc/submit', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `kyc-${customerId}-${Date.now()}`,
  },
  body: JSON.stringify({
    customer_id: customerId,
    first_name: 'Alex',
    last_name: 'Smith',
    email: 'alex.smith@example.com',
    calling_code: '+1',
    phone: '5551234567',
    gender: 'male',
    birth_date: '1990-01-15',
    nationality: 'US',
    taxId: '998-88-7766',
    selfie_image: selfieUrl,
    residential_address: {
      street_line_1: '123 Maple Street',
      city: 'Austin',
      state: 'TX',
      postal_code: '78701',
      country: 'US',
      proof_of_address_file: addressProofUrl,
    },
    identifying_information: [{
      type: 'passport',
      issuing_country: 'US',
      number: 'P12345678',
      date_issued: '2019-06-01',
      expiration_date: '2029-06-01',
      image_front_file: passportFrontUrl,
    }],
    employment_status: 'employed',
    most_recent_occupation_code: '151252',
    expected_monthly_payments_usd: '0_4999',
    source_of_funds: 'salary',
    account_purpose: 'receive_salary',
    acting_as_intermediary: false,
    uploaded_documents: [{ type: 'bank_statement', file: statementUrl }],
  }),
});
const data = await response.json();
import requests

response = requests.post(
    'https://kyc.yativo.com/api/individual-kyc/submit',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
        'Idempotency-Key': f'kyc-{customer_id}-001',
    },
    json={
        'customer_id': customer_id,
        'first_name': 'Alex',
        'last_name': 'Smith',
        'email': 'alex.smith@example.com',
        'calling_code': '+1',
        'phone': '5551234567',
        'gender': 'male',
        'birth_date': '1990-01-15',
        'nationality': 'US',
        'taxId': '998-88-7766',
        'selfie_image': selfie_url,
        'residential_address': {
            'street_line_1': '123 Maple Street',
            'city': 'Austin',
            'state': 'TX',
            'postal_code': '78701',
            'country': 'US',
            'proof_of_address_file': address_proof_url,
        },
        'identifying_information': [{
            'type': 'passport',
            'issuing_country': 'US',
            'number': 'P12345678',
            'date_issued': '2019-06-01',
            'expiration_date': '2029-06-01',
            'image_front_file': passport_front_url,
        }],
        'employment_status': 'employed',
        'most_recent_occupation_code': '151252',
        'expected_monthly_payments_usd': '0_4999',
        'source_of_funds': 'salary',
        'account_purpose': 'receive_salary',
        'acting_as_intermediary': False,
        'uploaded_documents': [{'type': 'bank_statement', 'file': statement_url}],
    }
)
{
  "success": true,
  "message": "KYC submission received successfully",
  "data": {
    "submission": {
      "id": "sub_8f3b2a1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "type": "individual",
      "status": "submitted",
      "customer_id": "c586066b-0f29-468f-b775-15483871a202",
      "first_name": "Alex",
      "last_name": "Smith",
      "email": "alex.smith@example.com",
      "endorsements": [
        {
          "service": "base",
          "status": "pending",
          "link": "https://kyc.yativo.com/endorsement/base/c586066b-0f29-468f-b775-15483871a202"
        }
      ],
      "created_at": "2026-06-01T10:00:00.000000Z"
    }
  }
}
{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed",
  "data": {
    "nationality": ["The nationality must be 2 characters."],
    "expected_monthly_payments_usd": ["The selected expected monthly payments usd is invalid."],
    "identifying_information": ["The identifying information field is required."]
  }
}