# Start biometrics

POST /customers/{customer_id}/biometricsCreate a biometrics capture session

Endpoint: POST /customers/{customer_id}/biometrics
Version: 2026-03-01
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: biometrics:create

## Path parameters:

  - `customer_id` (string, required)
    Customer ID

## Request fields (application/json):

  - `return_url` (string)
    URL the customer-facing app returns the user to when the flow finishes

## Response 201:

  - `201` (unknown)
    Biometrics session created

## Response 201 fields (application/json):

  - `session_url` (string, required)
    URL for the partner to embed in their flow (webview or redirect)
    Example: https://biometrics.dinie.com.br/session/...

  - `expires_at` (integer, required)
    Expiration timestamp (Unix epoch seconds)
    Example: 1772748000

## Response 401:

  - `401` (unknown)
    Authentication failed

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

  - `type` (string, required)
    Enum: "https://docs.dinie.com/errors/authentication-failed"

  - `title` (string, required)
    Enum: "Authentication Failed"

  - `status` (integer, required)
    Enum: "401"

  - `detail` (string, required)

  - `code` (string, required)
    Enum: "missing_token", "invalid_token", "token_expired"

## Response 403:

  - `403` (unknown)
    The credential is not permitted to perform this action

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

  - `type` (string, required)
    Enum: "https://docs.dinie.com/errors/forbidden"

  - `title` (string, required)
    Enum: "Forbidden"

  - `status` (integer, required)
    Enum: "403"

  - `detail` (string, required)

  - `code` (string, required)
    Enum: "forbidden"

## Response 404:

  - `404` (unknown)
    Resource not found

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

  - `type` (string, required)
    Enum: "https://docs.dinie.com/errors/not-found"

  - `title` (string, required)
    Enum: "Not Found"

  - `status` (integer, required)
    Enum: "404"

  - `detail` (string, required)

  - `code` (string, required)
    Enum: "customer_not_found"

## Response 409:

  - `409` (unknown)
    Conflict

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

  - `type` (string, required)
    Enum: "https://docs.dinie.com/errors/conflict"

  - `title` (string, required)
    Enum: "Conflict"

  - `status` (integer, required)
    Enum: "409"

  - `detail` (string, required)

  - `code` (string, required)
    Enum: "session_already_active"

## Response 422:

  - `422` (unknown)
    Validation failed

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

  - `type` (string, required)
    Enum: "https://docs.dinie.com/errors/validation-failed"

  - `title` (string, required)
    Enum: "Validation Failed"

  - `status` (integer, required)
    Enum: "422"

  - `detail` (string, required)

  - `code` (string, required)
    Enum: "biometrics_not_required"

## Response 429:

  - `429` (unknown)
    Rate limit exceeded

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

  - `type` (string, required)
    Enum: "https://docs.dinie.com/errors/rate-limit-exceeded"

  - `title` (string, required)
    Enum: "Rate Limit Exceeded"

  - `status` (integer, required)
    Enum: "429"

  - `detail` (string, required)

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

  - `Retry-After` (integer)
    Seconds until the rate limit resets

## Response 500:

  - `500` (unknown)
    Internal server error

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

  - `type` (string, required)
    Enum: "https://docs.dinie.com/errors/internal"

  - `title` (string, required)
    Enum: "Internal Error"

  - `status` (integer, required)
    Enum: "500"

  - `detail` (string, required)

## Response 401 examples:

  - `Authorization header is missing` (unknown)

  - `Bearer token is invalid or malformed` (unknown)

  - `Bearer token has expired` (unknown)

## Response 403 examples:

  - `The credential is not permitted to perform this action` (unknown)

## Response 404 examples:

  - `Customer ID does not exist or does not belong to this partner` (unknown)

## Response 409 examples:

  - `A biometrics session is already active for this customer` (unknown)

## Response 422 examples:

  - `Customer does not have pending biometrics KYC requirements` (unknown)