Skip to main content
POST
/
customers
curl --request POST \ --url https://api-sandbox.y.uno/v1/customers \ --header 'Content-Type: application/json' \ --header 'private-secret-key: <api-key>' \ --header 'public-api-key: <api-key>' \ --data ' { "merchant_customer_id": "4321", "merchant_customer_created_at": "2022-05-09T20:46:54.786342Z", "first_name": "John", "last_name": "Doe", "email": "john.doe@email.com", "gender": "M", "date_of_birth": "1990-02-28", "nationality": "US", "country": "US", "document": { "document_type": "SSN", "document_number": "123-45-6789" }, "phone": { "number": "5551234567", "country_code": "1" }, "billing_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 4B", "country": "US", "state": "NY", "city": "New York", "zip_code": "10001", "neighborhood": "Manhattan" }, "shipping_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 4B", "country": "US", "state": "NY", "city": "New York", "zip_code": "10001", "neighborhood": "Manhattan" }, "metadata": [ { "key": "ID", "value": "123456" } ] } '
{ "id": "bf64527c-5531-4ece-bf2c-51a8e775d8e1", "merchant_customer_id": "AAAAAAAAAAAAAA0002", "first_name": "John", "last_name": "Doe", "gender": "M", "date_of_birth": "1990-02-28", "email": "john.doe@email.com", "nationality": "US", "country": "US", "document": { "document_type": "SSN", "document_number": "123-45-6789" }, "phone": { "number": "5551234567", "country_code": "1" }, "billing_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 4B", "country": "US", "state": "NY", "city": "New York", "zip_code": "10001", "neighborhood": "Manhattan" }, "shipping_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 4B", "country": "US", "state": "NY", "city": "New York", "zip_code": "10001", "neighborhood": "Manhattan" }, "metadata": [ { "key": "ID", "value": "123456" } ], "created_at": "2025-04-24T18:54:54.351969Z", "updated_at": "2025-04-24T18:54:54.351971Z", "merchant_customer_created_at": "2022-05-09T20:46:54.786342Z" }
This request creates a customer resource. You need to provide several parameters of the customer in the request body, including the unique identifier of the customer in the external merchant, personal information, as well as billing and shipping addresses. Creating a customer generates a customer id that can be used to initialize the checkout.
ImportantThere are certain objects that are not mandatory when creating a “Customer”. However the more information you provide, the approval, conversion and fraud prevention rates will be positively impacted.

Authorizations

​
public-api-key
string
header
default:<Your public-api-key>
required
​
private-secret-key
string
header
default:<Your private-secret-key>
required

Body

application/json
​
merchant_customer_id
string
required

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

​
merchant_customer_created_at
string<date-time>

Customer's registration date on the merchants platform (MAX 27; MIN 27; ISO 8601)

​
first_name
string

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

​
last_name
string

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

​
gender
string

The customer's gender.

​
date_of_birth
string

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

​
email
string

The customer's e-mail (MAX 255; MIN 3).

​
nationality
enum<string>

The customer's nationality (MAX 2; MIN 2; ISO 3166-1).

Available options:
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
CI,
HR,
CU,
CW,
CY,
CZ,
DK,
DJ,
DM,
DO,
EC,
EG,
SZ,
GQ,
ER,
EE,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MK,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RE,
RO,
RU,
RW,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
US,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW
​
country
enum<string>

The customer's country (MAX 2; MIN 2; ISO 3166-1).

Available options:
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
CI,
HR,
CU,
CW,
CY,
CZ,
DK,
DJ,
DM,
DO,
EC,
EG,
SZ,
GQ,
ER,
EE,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MK,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RE,
RO,
RU,
RW,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
US,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW
​
document
object

Specifies the customer's document object, including its number and type. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
phone
object

Specifies the customer's phone number object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
billing_address
object

Specifies the customer's billing address object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
shipping_address
object

Specifies the customer's shipping address object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
metadata
object[]

Specifies a list of metadata objects. You can add up to 50 metadata objects.

Response

201

​
id
string
Example:

"bf64527c-5531-4ece-bf2c-51a8e775d8e1"

​
merchant_customer_id
string
Example:

"AAAAAAAAAAAAAA0002"

​
first_name
string
Example:

"John"

​
last_name
string
Example:

"Doe"

​
gender
string
Example:

"M"

​
date_of_birth
string
Example:

"1990-02-28"

​
email
string
Example:

"john.doe@email.com"

​
nationality
string
Example:

"US"

​
country
string
Example:

"US"

​
document
object
​
phone
object
​
billing_address
object
​
shipping_address
object
​
metadata
object[]
​
created_at
string
Example:

"2025-04-24T18:54:54.351969Z"

​
updated_at
string
Example:

"2025-04-24T18:54:54.351971Z"

​
merchant_customer_created_at
string
Example:

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