# Register a new customer

Registers a new customer (borrower) for the authenticated partner. The customer is created
with status pending_kyc and the response includes the kyc array with the documents and
verifications required for this profile. The next step is to submit documents
via POST /customers/{id}/documents.

Idempotent behavior: if the same CPF/CNPJ with the same external_id already exists,
the existing customer is returned (200 OK). The 409 error occurs only when the
external_id differs for the same CPF/CNPJ. See also the customer.* webhooks
to track registration progress.

Endpoint: POST /customers
Version: 2026-03-01
Security: bearerAuth

## Header parameters:

  - `Idempotency-Key` (string)
    Unique string for idempotent POST requests. Cached for 24 hours.

## Request fields (application/json):

  - `cpf` (string, required)
    Customer CPF (required)
    Example: "123.456.789-00"

  - `cnpj` (string,null)
    Company CNPJ
    Example: "12.345.678/0001-90"

  - `name` (string)
    Example: "Joao Silva"

  - `email` (string)
    Example: "joao@example.com"

  - `phone` (string)
    E.164 format
    Example: "+5511999999999"

  - `trading_name` (string)
    Example: "Loja do Joao"

  - `external_id` (string)
    Partner external reference for this customer
    Example: "partner-ref-123"

## Response 201 fields (application/json):

  - `id` (string, required)

  - `status` (string, required)
    Enum: "pending_kyc", "under_review", "active"

  - `cpf` (string, required)
    Example: "123.456.789-00"

  - `cnpj` (string,null, required)
    Example: "12.345.678/0001-90"

  - `name` (string, required)
    Example: "Joao Silva"

  - `email` (string, required)
    Example: "joao@example.com"

  - `phone` (string, required)
    Example: "+5511999999999"

  - `trading_name` (string,null, required)
    Example: "Loja do Joao"

  - `external_id` (string,null, required)
    Example: "partner-ref-123"

  - `kyc` (array, required)

  - `kyc.kind` (string, required)
    document for document submissions, data for data field corrections
    Enum: "document", "data"

  - `kyc.type` (string, required)
    Document type key (e.g., ccmei, selfie, identity_card_front)
    Example: "ccmei"

  - `kyc.description` (string, required)
    Human-readable label
    Example: "Certificado MEI"

  - `kyc.message` (string,null, required)
    Present when rejected — from the review feedback

  - `kyc.uploaded_at` (string,null, required)

  - `created_at` (string, required)

  - `updated_at` (string, required)

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 409 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)