> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# The Customer Object

> Describes the customer object and its attributes, including contact, address, and document data

This object represents a customer who will make payments using your service.

## Attributes

**id** `string`

The unique identifier of the customer (MAX 64; MIN 36).

Example: faa89e18-5a11-11ed-9b6a-0242ac120002

**merchant\_customer\_id** `string`

The unique identifier of the customer in the external merchant (MAX 255; MIN 1).

Example: 50ca6f06-5a12-11ed-9b6a-0242ac120002

**merchant\_customer\_created\_at** `timestamp`

Customer's registration date on the merchants platform (MAX 27; MIN 27 [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Example: 2022-05-09T20:46:54.786342Z

**first\_name** `string`

The customer's first name (MAX 255; MIN 1).

Example: John

**last\_name** `string`

The customer's last name (MAX 255; MIN 1).

Example: Doe

**gender** `enum`

The customer's gender (MAX 2; MIN 1).

Possible enum values: `M`, `F` or `NB`

**date\_of\_birth** `string`

The customer's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10).

Example: 1990-02-28

**email** `string`

The customer's email (MAX 255; MIN 3).

Example: [john.doe@email.com](mailto:john.doe@email.com)

**nationality** `enum`

The customer's nationality (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Possible enum values: Check the [Country reference](https://docs.y.uno/reference/country-reference.md).

**country** `enum`

The customer's country (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Possible enum values: Check the [Country reference](https://docs.y.uno/reference/country-reference.md).

**document** `object`

Specifies the customer's document object, including its number and type.

**properties**

**document\_number** `string`

The customer's document number (MAX 40; MIN 3).

Example: 1093333333

**document\_type** `enum`

The customer's document type (MAX 6; MIN 2).

Possible enum values: Check the [Country reference](https://docs.y.uno/reference/country-reference.md).

**phone** `object`

Specifies the customer's phone number object.

**properties**

**country\_code** `string`

The country calling code of the customer's phone (MAX 3; MIN 1). Possible values: Check the [Country reference](https://docs.y.uno/reference/country-reference.md).

Example: 57

**number** `string`

The customer's phone number, without the country code (MAX 32; MIN 1).

Example: 3132450765

**billing\_address** `object`

Specifies the customer's billing address object.

**properties**

**address\_line\_1** `string`

The primary billing address line of the customer (MAX 255; MIN 3).

Example: Calle 34 # 56 - 78

**address\_line\_2** `string`

The secondary billing address line of the customer (MAX 255; MIN 3).

Example: Apartamento 502, Torre I

**city** `string`

The city considered for the billing address (MAX 255; MIN 3).

Example: Bogotá

**country** `enum`

The country considered for the billing address (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Possible enum values: Check the [Country reference](https://docs.y.uno/reference/country-reference.md).

**state** `string`

The state considered for the billing address (MAX 255; MIN 3; [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) ).

Example: Cundinamarca

**zip\_code** `string`

The zipcode considered for the billing address (MAX 11; MIN 4).

Example: 111111

**neighborhood** `string`

The neighborhood of the address line of the customer (MAX 255; MIN 2)

Example: Barrio 11

**shipping\_address** `object`

Specifies the customer's shipping address object.

**properties**

**address\_line\_1** `string`

The primary shipping address line of the customer (MAX 255; MIN 3).

Example: Calle 34 # 56 - 78

**address\_line\_2** `string`

The secondary shipping address line of the customer (MAX 255; MIN 3).

Example: Apartamento 502, Torre I

**city** `string`

The city considered for the shipping address (MAX 255; MIN 3).

Example: Bogotá

**country** `enum`

The country considered for the shipping address (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Possible enum values: Check the [Country reference](https://docs.y.uno/reference/country-reference.md).

**state** `string`

The state considered for the shipping address (MAX 255; MIN 3; [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) ).

Example: Cundinamarca

**zip\_code** `string`

The zipcode considered for the shipping address (MAX 10; MIN 5).

Example: 111111

**neighborhood** `string`

The neighborhood of the address line of the customer (MAX 255; MIN 2)

Example: Barrio 11

**metadata** `array of objects`

Specifies a list of custom key–value pairs associated with the customer (for internal references, segmentation, or workflow tags). You can add up to 50 metadata objects.

**properties**

**metadata object** `object`

Specifies a metadata key and the respective value.

Use to attach merchant-defined context (for example: `crm_id`, `segment`). Avoid sending sensitive or personal data.

**properties**

**key** `string`

Specifies one metadata key.

Example: age

**value** `string`

Specifies the value for the defined metadata key.

Example: 28

**created\_at** `timestamp`

Customer creation date and time (MAX 27; MIN 27; [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Example: 2022-05-09T20:46:54.786342Z

**updated\_at** `timestamp`

Last customer update date and time (MAX 27; MIN 27; [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Example: 2022-05-09T20:46:54.786342Z

## Operations

* [Create a Customer](https://docs.y.uno/reference/customers/create-customer.md)
* [Retrieve a Customer](https://docs.y.uno/reference/customers/retrieve-customer.md)
* [Retrieve by External ID](https://docs.y.uno/reference/customers/retrieve-customer-by-external-id.md)
* [Update a Customer](https://docs.y.uno/reference/customers/update-customer.md)
* [Delete a Customer](https://docs.y.uno/reference/customers/delete-customer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.