---
title: "Submit KYC for a customer (via image URL)"
method: POST
path: "/v1/headless_kyc"
tags: ["Headless KYC"]
---

# Submit KYC for a customer (via image URL)

`POST /v1/headless_kyc`

Submits KYC data for a customer on behalf of the merchant. Only TIER_2 is supported. Idempotent on customerReferenceId.

This API spec details the request body for the **`application/json` content type**. For the **`multipart/form-data` content type**, please refer to the `Submit KYC for a customer (via image upload)` endpoint.

**Note:** This endpoint is only available to merchants configured by the Breeze team. Please reach out to the Breeze team to find out more.

## Request body

- SubmitHeadlessKycWithImageUrlRequest — KYC submission details
  - `customerReferenceId` string, required
  - `tier` 'TIER_2', required
  - `email` string, email, required
  - `firstName` string, required
  - `lastName` string, required
  - `middleName` string
  - `dateOfBirth` string, required
  - `country` string, required
  - `phoneNumber` string, required
  - `address` object, required
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `country` string, required
    - `state` string
    - `postalCode` union
      - string
      - string
  - `taxId` string
  - `document` union, required
    - object — These document types require both front and back image URLs.
      - `type` 'DRIVERS_LICENSE' | 'NATIONAL_ID' | 'RESIDENCE_PERMIT' | 'PERMANENT_RESIDENCE_CARD', required
      - `frontImageUrl` string, uri, required
      - `backImageUrl` string, uri, required
      - `documentNumber` string, required
    - object — These document types only require a front image URL.
      - `type` 'PASSPORT' | 'PASSPORT_CARD', required
      - `frontImageUrl` string, uri, required
      - `documentNumber` string, required
  - `consent` object, required
    - `termsAcceptedAt` integer, required
    - `ipAddress` union, required
      - string, ipv4
      - string, ipv6
    - `userAgent` string

## Response `200`

Success

- object — The created or existing KYC request
  - `status` 'SUCCEEDED', required
  - `data` SubmitHeadlessKycWithImageUrlResponse, required — Response data for headless KYC endpoints
    - `id` string, required
    - `customerId` string
    - `accountId` string
    - `kycId` string
    - `kycStatus` 'pending' | 'processing' | 'approved' | 'rejected' | 'under_review', required — HeadlessKycStatus - mirrors KYC tier status for merchant-facing API
    - `customerReferenceId` string, required
    - `tier` 'TIER_0' | 'TIER_1' | 'TIER_2' | 'TIER_3', required
    - `rejectionReason` string
    - `createdAt` number, required
    - `updatedAt` number, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized

---

[API](https://skmtc.dev/breeze/apis/breeze-api.md) · [All operations](https://skmtc.dev/breeze/apis/breeze-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/breeze/breeze-api/revisions/8911892bdf29/schema)