Skip to content
API Reference/Customers

Dinie API (2026-03-01)

Embedded credit API for Dinie partners. Enables customer registration, credit offer management, loan origination, and event delivery via webhooks.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://dinie.nexaedge.dev
Dinie API Support
api@dinie.com.br
License
Proprietary
Languages
Servers
Mock server
https://dinie.nexaedge.dev/_mock/apis/openapi
Production
https://api.dinie.com.br/v3
Sandbox
https://sandbox.api.dinie.com.br/v3

Authentication

OAuth2 Client Credentials authentication and API key management.

Each client_id / client_secret pair represents an access credential. Exchange the credentials for a JWT token via POST /auth/token and send the token as Bearer in all requests. The token expires in 1 hour.

You can create multiple credentials for different environments and revoke them individually.

Operations

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
Operations
Webhooks

Lifecycle

pending_kyc → under_review → active
StatusDescriptionNext Step
pending_kycRegistered, awaiting documentsSubmit documents and biometrics
under_reviewDocuments submitted, under reviewWait for customer.active webhook
activeApproved and eligible for creditCheck credit offers

Example: Complete Registration

# 1. Register the customer
customer = client.customers.create(
  cpf: "123.456.789-00",
  cnpj: "12.345.678/0001-90",
  name: "João Silva",
  email: "joao@example.com",
  phone: "+5511999999999",
  trading_name: "Loja do João",
  external_id: "partner-ref-123"
)
# customer.id => "cust_550e8400..."
# customer.status => "pending_kyc"
# customer.kyc => list of pending documents

# 2. Submit each required document
customer.kyc.each do |item|
  next unless item.status == "pending"
  client.customers.upload_document(customer.id,
    type: item.type,
    file: File.open("docs/#{item.type}.pdf")
  )
end

# 3. Start biometric capture
session = client.customers.create_biometrics_session(customer.id)
# Redirect the customer to session.session_url

# 4. Wait for customer.active webhook
# When received, the customer is ready for credit

Registration Idempotency

Creating a customer with the same CPF/CNPJ and external_id returns the existing customer (200 OK). This allows safely retrying the request in case of timeout or network failure. The 409 Conflict error only occurs when the external_id differs.

Search

# By CPF
customers = client.customers.list(cpf: "123.456.789-00")

# By partner ID
customers = client.customers.list(external_id: "partner-ref-123")

Webhooks

EventWhen it fires
customer.createdCustomer registered via API
customer.under_reviewDocuments submitted, KYC review started
customer.kyc_updatedKYC item status updated (approved, rejected, correction)
customer.activeCustomer approved — eligible for credit offers

Register a new customer

Request

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.

Security
bearerAuth
Headers
Idempotency-Keystring

Unique string for idempotent POST requests. Cached for 24 hours.

Bodyapplication/jsonrequired
cpfstringrequired

Customer CPF (required)

Example: "123.456.789-00"
cnpjstring or null

Company CNPJ

Example: "12.345.678/0001-90"
namestring
Example: "Joao Silva"
emailstring(email)
Example: "joao@example.com"
phonestring

E.164 format

Example: "+5511999999999"
trading_namestring
Example: "Loja do Joao"
external_idstring

Partner external reference for this customer

Example: "partner-ref-123"
curl -X POST https://api.dinie.com.br/v3/customers \
  -H "Authorization: Bearer $DINIE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "123.456.789-00",
    "name": "João Silva",
    "email": "joao@example.com",
    "phone": "+5511999999999",
    "external_id": "partner-ref-123"
  }'

Responses

Customer created

Headers
Locationstring
Example: "/v3/customers/cust_550e8400e29b41d4a716446655440000"
Bodyapplication/json
idstring(CustomerId)^cust_[0-9a-f]{32}$required
statusstringrequired
Enum ValueDescription
pending_kyc

Customer registered, but KYC documents/biometrics not yet submitted or under review

under_review

All required KYC items submitted; Dinie's compliance team is reviewing

active

KYC approved; customer is eligible to receive credit offers

cpfstringrequired
Example: "123.456.789-00"
cnpjstring or nullrequired
Example: "12.345.678/0001-90"
namestringrequired
Example: "Joao Silva"
emailstring(email)required
Example: "joao@example.com"
phonestringrequired
Example: "+5511999999999"
trading_namestring or nullrequired
Example: "Loja do Joao"
external_idstring or nullrequired
Example: "partner-ref-123"
kycArray of objects(KycItem)required
kyc[].​kindstringrequired

document for file uploads, data for data field corrections

Enum"document""data"
kyc[].​typestringrequired

Document type key (e.g., ccmei, selfie, identity_card_front)

Example: "ccmei"
kyc[].​descriptionstringrequired

Human-readable label

Example: "Certificado MEI"
kyc[].​statusstringrequired
Enum ValueDescription
pending

Awaiting submission by the customer

submitted

Document submitted, awaiting review

approved

Document reviewed and approved

pending_resubmission

Document rejected; customer must resubmit

pending_correction

Data field needs correction by the customer

kyc[].​messagestring or nullrequired

Present when rejected — from the review feedback

kyc[].​uploaded_atstring or null(date-time)required
created_atstring(date-time)required
updated_atstring(date-time)required
Response
application/json
{
  "id": "cust_550e8400e29b41d4a716446655440000",
  "status": "pending_kyc",
  "cpf": "123.456.789-00",
  "cnpj": "12.345.678/0001-90",
  "name": "João Silva",
  "email": "joao@example.com",
  "phone": "+5511999999999",
  "trading_name": "Loja do João",
  "external_id": "partner-ref-123",
  "kyc": [
    {
      "kind": "document",
      "type": "ccmei",
      "description": "Certificado MEI",
      "status": "pending",
      "message": null,
      "uploaded_at": null
    },
    {
      "kind": "document",
      "type": "selfie",
      "description": "Selfie",
      "status": "pending",
      "message": null,
      "uploaded_at": null
    }
  ],
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-04T10:00:00Z"
}

List customers

Request

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.

Security
bearerAuth
Query
external_idstring

Filter by partner external reference

cpfstring

Filter by CPF

sortstring
Default "created_at"
Enum"created_at""updated_at""name"
orderstring
Default "desc"
Enum"asc""desc"
starting_afterstring

Prefixed ID of the last item from the previous page.

limitinteger[ 1 .. 100 ]

Number of items to return. Min: 1, Max: 100.

Default 25
# List customers filtered by CPF
curl "https://api.dinie.com.br/v3/customers?cpf=123.456.789-00&limit=10" \
  -H "Authorization: Bearer $DINIE_API_TOKEN"

Responses

List of customers

Bodyapplication/json
dataArray of objects(Customer)required
data[].​idstring(CustomerId)^cust_[0-9a-f]{32}$required
data[].​statusstringrequired
Enum ValueDescription
pending_kyc

Customer registered, but KYC documents/biometrics not yet submitted or under review

under_review

All required KYC items submitted; Dinie's compliance team is reviewing

active

KYC approved; customer is eligible to receive credit offers

data[].​cpfstringrequired
Example: "123.456.789-00"
data[].​cnpjstring or nullrequired
Example: "12.345.678/0001-90"
data[].​namestringrequired
Example: "Joao Silva"
data[].​emailstring(email)required
Example: "joao@example.com"
data[].​phonestringrequired
Example: "+5511999999999"
data[].​trading_namestring or nullrequired
Example: "Loja do Joao"
data[].​external_idstring or nullrequired
Example: "partner-ref-123"
data[].​kycArray of objects(KycItem)required
data[].​kyc[].​kindstringrequired

document for file uploads, data for data field corrections

Enum"document""data"
data[].​kyc[].​typestringrequired

Document type key (e.g., ccmei, selfie, identity_card_front)

Example: "ccmei"
data[].​kyc[].​descriptionstringrequired

Human-readable label

Example: "Certificado MEI"
data[].​kyc[].​statusstringrequired
Enum ValueDescription
pending

Awaiting submission by the customer

submitted

Document submitted, awaiting review

approved

Document reviewed and approved

pending_resubmission

Document rejected; customer must resubmit

pending_correction

Data field needs correction by the customer

data[].​kyc[].​messagestring or nullrequired

Present when rejected — from the review feedback

data[].​kyc[].​uploaded_atstring or null(date-time)required
data[].​created_atstring(date-time)required
data[].​updated_atstring(date-time)required
has_morebooleanrequired
Response
application/json
{
  "data": [
    {
      "id": "cust_550e8400e29b41d4a716446655440000",
      "status": "active",
      "cpf": "123.456.789-00",
      "cnpj": "12.345.678/0001-90",
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "+5511999999999",
      "trading_name": "Loja do João",
      "external_id": "partner-ref-123",
      "kyc": [],
      "created_at": "2026-03-04T10:00:00Z",
      "updated_at": "2026-03-04T12:00:00Z"
    },
    {
      "id": "cust_660e8400e29b41d4a716446655440001",
      "status": "pending_kyc",
      "cpf": "987.654.321-00",
      "cnpj": null,
      "name": "Maria Santos",
      "email": "maria@example.com",
      "phone": "+5511988888888",
      "trading_name": null,
      "external_id": "partner-ref-456",
      "kyc": [],
      "created_at": "2026-03-05T08:00:00Z",
      "updated_at": "2026-03-05T08:00:00Z"
    }
  ],
  "has_more": true
}

Retrieve a customer

Request

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.

Security
bearerAuth
Path
customer_idstring(CustomerId)^cust_[0-9a-f]{32}$required
Example: cust_550e8400e29b41d4a716446655440000
curl https://api.dinie.com.br/v3/customers/cust_550e8400e29b41d4a716446655440000 \
  -H "Authorization: Bearer $DINIE_API_TOKEN"

Responses

Customer details

Bodyapplication/json
idstring(CustomerId)^cust_[0-9a-f]{32}$required
statusstringrequired
Enum ValueDescription
pending_kyc

Customer registered, but KYC documents/biometrics not yet submitted or under review

under_review

All required KYC items submitted; Dinie's compliance team is reviewing

active

KYC approved; customer is eligible to receive credit offers

cpfstringrequired
Example: "123.456.789-00"
cnpjstring or nullrequired
Example: "12.345.678/0001-90"
namestringrequired
Example: "Joao Silva"
emailstring(email)required
Example: "joao@example.com"
phonestringrequired
Example: "+5511999999999"
trading_namestring or nullrequired
Example: "Loja do Joao"
external_idstring or nullrequired
Example: "partner-ref-123"
kycArray of objects(KycItem)required
kyc[].​kindstringrequired

document for file uploads, data for data field corrections

Enum"document""data"
kyc[].​typestringrequired

Document type key (e.g., ccmei, selfie, identity_card_front)

Example: "ccmei"
kyc[].​descriptionstringrequired

Human-readable label

Example: "Certificado MEI"
kyc[].​statusstringrequired
Enum ValueDescription
pending

Awaiting submission by the customer

submitted

Document submitted, awaiting review

approved

Document reviewed and approved

pending_resubmission

Document rejected; customer must resubmit

pending_correction

Data field needs correction by the customer

kyc[].​messagestring or nullrequired

Present when rejected — from the review feedback

kyc[].​uploaded_atstring or null(date-time)required
created_atstring(date-time)required
updated_atstring(date-time)required
Response
application/json
{
  "id": "cust_550e8400e29b41d4a716446655440000",
  "status": "active",
  "cpf": "123.456.789-00",
  "cnpj": "12.345.678/0001-90",
  "name": "João Silva",
  "email": "joao@example.com",
  "phone": "+5511999999999",
  "trading_name": "Loja do João",
  "external_id": "partner-ref-123",
  "kyc": [
    {
      "kind": "document",
      "type": "ccmei",
      "description": "Certificado MEI",
      "status": "approved",
      "message": null,
      "uploaded_at": "2026-03-04T11:00:00Z"
    }
  ],
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-04T14:00:00Z"
}

Update customer data

Request

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.

Security
bearerAuth
Path
customer_idstring(CustomerId)^cust_[0-9a-f]{32}$required
Example: cust_550e8400e29b41d4a716446655440000
Bodyapplication/jsonrequired
emailstring(email)
phonestring
namestring
cnpjstring
trading_namestring
curl -X PATCH https://api.dinie.com.br/v3/customers/cust_550e8400e29b41d4a716446655440000 \
  -H "Authorization: Bearer $DINIE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao.novo@example.com",
    "phone": "+5511988887777"
  }'

Responses

Customer updated

Bodyapplication/json
idstring(CustomerId)^cust_[0-9a-f]{32}$required
statusstringrequired
Enum ValueDescription
pending_kyc

Customer registered, but KYC documents/biometrics not yet submitted or under review

under_review

All required KYC items submitted; Dinie's compliance team is reviewing

active

KYC approved; customer is eligible to receive credit offers

cpfstringrequired
Example: "123.456.789-00"
cnpjstring or nullrequired
Example: "12.345.678/0001-90"
namestringrequired
Example: "Joao Silva"
emailstring(email)required
Example: "joao@example.com"
phonestringrequired
Example: "+5511999999999"
trading_namestring or nullrequired
Example: "Loja do Joao"
external_idstring or nullrequired
Example: "partner-ref-123"
kycArray of objects(KycItem)required
kyc[].​kindstringrequired

document for file uploads, data for data field corrections

Enum"document""data"
kyc[].​typestringrequired

Document type key (e.g., ccmei, selfie, identity_card_front)

Example: "ccmei"
kyc[].​descriptionstringrequired

Human-readable label

Example: "Certificado MEI"
kyc[].​statusstringrequired
Enum ValueDescription
pending

Awaiting submission by the customer

submitted

Document submitted, awaiting review

approved

Document reviewed and approved

pending_resubmission

Document rejected; customer must resubmit

pending_correction

Data field needs correction by the customer

kyc[].​messagestring or nullrequired

Present when rejected — from the review feedback

kyc[].​uploaded_atstring or null(date-time)required
created_atstring(date-time)required
updated_atstring(date-time)required
Response
application/json
{
  "id": "cust_550e8400e29b41d4a716446655440000",
  "status": "active",
  "cpf": "123.456.789-00",
  "cnpj": "12.345.678/0001-90",
  "name": "João Silva",
  "email": "joao.novo@example.com",
  "phone": "+5511988887777",
  "trading_name": "Loja do João",
  "external_id": "partner-ref-123",
  "kyc": [],
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-05T09:00:00Z"
}

Upload a KYC document

Request

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}.

Security
bearerAuth
Path
customer_idstring(CustomerId)^cust_[0-9a-f]{32}$required
Example: cust_550e8400e29b41d4a716446655440000
Headers
Idempotency-Keystring

Unique string for idempotent POST requests. Cached for 24 hours.

Bodymultipart/form-datarequired
typestringrequired

KYC document type (e.g., ccmei, selfie, identity_card_front)

filestring(binary)required

Document file (PDF, JPEG, or PNG)

curl -X POST https://api.dinie.com.br/v3/customers/cust_550e8400e29b41d4a716446655440000/documents \
  -H "Authorization: Bearer $DINIE_API_TOKEN" \
  -F "type=ccmei" \
  -F "file=@certificado-mei.pdf"

Responses

Document uploaded

Headers
Locationstring
Example: "/v3/customers/cust_550e8400e29b41d4a716446655440000/documents/doc_550e8400e29b41d4a716446655440001"
Bodyapplication/json
idstring(DocumentId)^doc_[0-9a-f]{32}$required
typestringrequired

Document type

Example: "ccmei"
statusstringrequired

Document status

Enum"submitted""approved""rejected"
uploaded_atstring(date-time)required
created_atstring(date-time)required
updated_atstring(date-time)required
Response
application/json
{
  "id": "doc_550e8400e29b41d4a716446655440001",
  "type": "ccmei",
  "status": "submitted",
  "uploaded_at": "2026-03-04T11:00:00Z",
  "created_at": "2026-03-04T11:00:00Z",
  "updated_at": "2026-03-04T11:00:00Z"
}

Generate a biometric capture session

Request

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.

Security
bearerAuth
Path
customer_idstring(CustomerId)^cust_[0-9a-f]{32}$required
Example: cust_550e8400e29b41d4a716446655440000
Headers
Idempotency-Keystring

Unique string for idempotent POST requests. Cached for 24 hours.

curl -X POST https://api.dinie.com.br/v3/customers/cust_550e8400e29b41d4a716446655440000/biometrics \
  -H "Authorization: Bearer $DINIE_API_TOKEN"

Responses

Biometrics session created

Bodyapplication/json
session_urlstring(uri)required

URL for the partner to embed in their flow (webview or redirect)

Example: "https://biometrics.dinie.com.br/session/..."
expires_atstring(date-time)required
Example: "2026-03-03T16:00:00Z"
Response
application/json
{
  "session_url": "https://biometrics.dinie.com.br/session/abc123def456",
  "expires_at": "2026-03-04T16:00:00Z"
}

Customer createdWebhook

Request

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.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Value"customer.created"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(CustomerId)^cust_[0-9a-f]{32}$required
data.​statusstringrequired
Value"pending_kyc"
data.​cpfstringrequired
data.​cnpjstring or null
data.​namestringrequired
data.​emailstringrequired
data.​phonestringrequired
data.​trading_namestring or null
data.​external_idstring or nullrequired

Responses

Event received

Customer under reviewWebhook

Request

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.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Enum"customer.under_review""customer.active"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(CustomerId)^cust_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"under_review""active"
data.​external_idstring or nullrequired

Responses

Event received

Customer KYC updatedWebhook

Request

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.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Value"customer.kyc_updated"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(CustomerId)^cust_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"pending_kyc""under_review""active"
data.​external_idstring or nullrequired
data.​kycArray of objects(KycItem)required

Full current state of all KYC requirements

data.​kyc[].​kindstringrequired

document for file uploads, data for data field corrections

Enum"document""data"
data.​kyc[].​typestringrequired

Document type key (e.g., ccmei, selfie, identity_card_front)

Example: "ccmei"
data.​kyc[].​descriptionstringrequired

Human-readable label

Example: "Certificado MEI"
data.​kyc[].​statusstringrequired
Enum ValueDescription
pending

Awaiting submission by the customer

submitted

Document submitted, awaiting review

approved

Document reviewed and approved

pending_resubmission

Document rejected; customer must resubmit

pending_correction

Data field needs correction by the customer

data.​kyc[].​messagestring or nullrequired

Present when rejected — from the review feedback

data.​kyc[].​uploaded_atstring or null(date-time)required

Responses

Event received

Customer activeWebhook

Request

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.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Enum"customer.under_review""customer.active"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(CustomerId)^cust_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"under_review""active"
data.​external_idstring or nullrequired

Responses

Event received

Credit Offers

The CreditOffer resource (co_) represents a pre-approved credit offer for a customer. Offers are automatically generated by Dinie when a Customer reaches the active status. You are notified via the credit_offer.available webhook.

Operations
Webhooks

Loans

The Loan resource (ln_) represents a loan originated from a CreditOffer and its Simulation. After creation, the loan goes through several automated steps until disbursement.

Operations
Webhooks

Webhooks

Manage the endpoints that receive event notifications (we_). Dinie follows the Standard Webhooks specification.

Events for each resource are documented in the Customers, Credit Offers, and Loans sections. This section covers only endpoint management.

Operations