> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Individual KYC

> Submit identity verification data for an individual customer

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.

<Note>
  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.
</Note>

```
POST https://kyc.yativo.com/api/individual-kyc/submit
```

## Identity fields

<ParamField body="customer_id" type="string" required>
  The customer UUID returned by `POST /customer`.
</ParamField>

<ParamField body="first_name" type="string" required>
  Customer's first name. Max 1024 characters.
</ParamField>

<ParamField body="last_name" type="string" required>
  Customer's last name. Max 1024 characters.
</ParamField>

<ParamField body="middle_name" type="string">
  Customer's middle name. Optional.
</ParamField>

<ParamField body="email" type="string" required>
  Customer's email address.
</ParamField>

<ParamField body="calling_code" type="string" required>
  Country dial code. Must match `^\+\d{1,4}$`, e.g. `"+1"`, `"+44"`, `"+234"`.
</ParamField>

<ParamField body="phone" type="string" required>
  Phone number digits only, 8–15 characters. Do not include the country code.
</ParamField>

<ParamField body="birth_date" type="string" required>
  Date of birth in `YYYY-MM-DD` format. Must be before today.
</ParamField>

<ParamField body="nationality" type="string" required>
  ISO 3166-1 alpha-2 country code, e.g. `"US"`, `"NG"`, `"BR"`.
</ParamField>

<ParamField body="gender" type="string" required>
  `"male"` or `"female"`.
</ParamField>

<ParamField body="taxId" type="string" required>
  Tax identification number. Max 100 characters.
</ParamField>

<ParamField body="selfie_image" type="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.
</ParamField>

<ParamField body="bvn" type="string">
  Bank Verification Number. **Required when `nationality` is `"NG"`**. Exactly 11 digits.
</ParamField>

<ParamField body="nin" type="string">
  National Identification Number. **Required when `nationality` is `"NG"`**. Exactly 11 digits.
</ParamField>

## Residential address

<ParamField body="residential_address" type="object" required>
  Customer's current residential address.

  <Expandable title="residential_address fields">
    <ParamField body="street_line_1" type="string" required>
      Street address line 1. Max 256 characters.
    </ParamField>

    <ParamField body="street_line_2" type="string">
      Street address line 2. Optional.
    </ParamField>

    <ParamField body="city" type="string" required>
      City. Max 256 characters.
    </ParamField>

    <ParamField body="state" type="string" required>
      State or province. Accepts full ISO 3166-2 codes like `"US-CA"` or the subdivision segment `"CA"` — both are normalised.
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal or ZIP code. Validated per country.
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code.
    </ParamField>

    <ParamField body="proof_of_address_file" type="string" required>
      Proof of address document (utility bill, bank statement, etc.). Hosted URL or base64. PDF/JPG/JPEG/PNG/HEIC/TIF, max 5 MB.
    </ParamField>
  </Expandable>
</ParamField>

## Identifying information

<ParamField body="identifying_information" type="array" required>
  At least one government-issued ID document. Accepted document types depend on `issuing_country` — see the [ID types reference](/yativo-fiat/kyc#id-types-by-country).

  <Expandable title="identifying_information item fields">
    <ParamField body="type" type="string" required>
      Document type. Common values: `"passport"`, `"national_id"`, `"other"`. Country-specific types also apply (e.g. `"ssn"` for US, `"bvn"` for NG).
    </ParamField>

    <ParamField body="issuing_country" type="string" required>
      ISO 3166-1 alpha-2 country code of the issuing authority.
    </ParamField>

    <ParamField body="number" type="string" required>
      Document number.
    </ParamField>

    <ParamField body="date_issued" type="string" required>
      Issue date in `YYYY-MM-DD` format. Must be before today.
    </ParamField>

    <ParamField body="expiration_date" type="string" required>
      Expiration date in `YYYY-MM-DD` format. Must be after today.
    </ParamField>

    <ParamField body="image_front_file" type="string" required>
      Front image of the document. Hosted URL or base64. PDF/JPG/JPEG/PNG, max 5 MB.
    </ParamField>

    <ParamField body="image_back_file" type="string">
      Back image of the document. Required for documents that have a reverse side (e.g. national ID cards). Hosted URL or base64. PDF/JPG/JPEG/PNG, max 5 MB.
    </ParamField>
  </Expandable>
</ParamField>

## Risk and purpose

<ParamField body="employment_status" type="string" required>
  Customer's employment status. One of: `"employed"`, `"exempt"`, `"homemaker"`, `"retired"`, `"self_employed"`, `"student"`, `"unemployed"`.
</ParamField>

<ParamField body="most_recent_occupation_code" type="string" required>
  6-digit occupation code. Retrieve the full list from `GET /auth/occupation-codes`. Example: `"151252"` (Software developer).
</ParamField>

<ParamField body="expected_monthly_payments_usd" type="string" required>
  Expected monthly transaction volume. One of: `"0_4999"`, `"5000_9999"`, `"10000_49999"`, `"50000_plus"`.
</ParamField>

<ParamField body="source_of_funds" type="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"`.
</ParamField>

<ParamField body="account_purpose" type="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"`.
</ParamField>

<ParamField body="account_purpose_other" type="string">
  Required when `account_purpose` is `"other"`. Provide a plain-text description.
</ParamField>

<ParamField body="acting_as_intermediary" type="boolean">
  Set to `true` if the customer is acting on behalf of third parties. Defaults to `false`.
</ParamField>

## Supporting documents

<ParamField body="uploaded_documents" type="array" required>
  At least one supporting document is required.

  <Expandable title="uploaded_documents item fields">
    <ParamField body="type" type="string" required>
      A label identifying the document type, e.g. `"bank_statement"`, `"tax_return"`.
    </ParamField>

    <ParamField body="file" type="string" required>
      Hosted URL or base64-encoded file. PDF/JPG/JPEG/PNG, max 5 MB.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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}],
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Submitted theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json Validation error theme={null}
  {
    "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."]
    }
  }
  ```
</ResponseExample>