# Customers

The **Customer** resource (`cust_`) represents a credit borrower on the platform.
The lifecycle follows: registration → KYC document submission → review → activation.

Two processes happen in parallel:
- **Credit analysis** — starts automatically upon registration
- **KYC verification** — the customer completes at their own pace



## Register a new customer

 - [POST /customers](https://dinie.redocly.app/apis/openapi/customers/createcustomer.md): 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.

## List customers

 - [GET /customers](https://dinie.redocly.app/apis/openapi/customers/listcustomers.md): Lists and searches customers for the authenticated partner. Supports filters by cpf,
external_id, and status to locate specific customers. Pagination uses
cursor-based approach with the starting_after (last item ID) and limit (max 100) parameters.

## Retrieve a customer

 - [GET /customers/{customer_id}](https://dinie.redocly.app/apis/openapi/customers/getcustomer.md): Returns the complete customer object, including registration data, current status,
and the kyc array with the progress of each verification requirement. Use this endpoint
to check the customer state at any time or after receiving a
customer.kyc_updated webhook.

## Update customer data

 - [PATCH /customers/{customer_id}](https://dinie.redocly.app/apis/openapi/customers/updatecustomer.md): Updates customer data fields. The main use case is correcting information
rejected during KYC verification (items with pending_correction status), such as
email, phone, or registration data. The cpf and external_id fields cannot be
updated after creation. After correction, the KYC analysis resumes
automatically and you will receive customer.kyc_updated webhooks with the progress.

## Upload a KYC document

 - [POST /customers/{customer_id}/documents](https://dinie.redocly.app/apis/openapi/customers/uploaddocument.md): Uploads a KYC document for the customer via file upload (multipart/form-data).
The document type must match one of the types listed in the customer's kyc array
(e.g., ccmei, selfie, cnh). After upload, the document undergoes asynchronous review.
Track the result via the customer.kyc_updated webhook or by retrieving the customer
with GET /customers/{customer_id}.

## Generate a biometric capture session

 - [POST /customers/{customer_id}/biometrics](https://dinie.redocly.app/apis/openapi/customers/createbiometricssession.md): Creates a biometrics capture session for the customer and returns a temporary URL.
The partner should redirect the customer to this URL or embed it in a webview
within their application. Biometrics is a KYC requirement of type biometrics and its
progress is tracked in the customer's kyc array. This is an action endpoint that
returns 200 OK (not 201 Created). See the customer.kyc_updated webhook to
track the completion of the capture.

## Customer created

 - [POST customer.created](https://dinie.redocly.app/apis/openapi/customers/oncustomercreated.md): Fires immediately after a new customer is registered via POST /customers.
Includes the customer's full registration data with pending_kyc status.
Use it to confirm registration receipt and start the KYC document collection flow.

## Customer under review

 - [POST customer.under_review](https://dinie.redocly.app/apis/openapi/customers/oncustomerunderreview.md): Fires when all required KYC documents have been submitted and the credit review
is started by Dinie. Includes the customer ID and under_review status.
Use it to update the status in your system and inform the customer that the review is in progress.

## Customer KYC updated

 - [POST customer.kyc_updated](https://dinie.redocly.app/apis/openapi/customers/oncustomerkycupdated.md): Fires when any KYC requirement changes status (approved, rejected, or
pending correction). Includes the full kyc array with the updated status of
each item. Use it to identify rejected documents and request resubmission from the customer
via PATCH /customers/{id} or POST /customers/{id}/documents.

## Customer active

 - [POST customer.active](https://dinie.redocly.app/apis/openapi/customers/oncustomeractive.md): Fires when the customer is fully verified (KYC approved) and eligible to
receive credit offers. Includes the customer ID and active status. This is the
time to query GET /customers/{id}/credit-offers to check for available
pre-approved offers.