Create Customer

Create a customer

curl --request POST \
  --url http://sandbox.mintlify.com/organizations/{organizationId}/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "legalName": "Dunder Mifflin",
  "taxId": "ABC101010111",
  "taxSystem": "601",
  "email": "email@example.com",
  "defaultInvoiceUse": "G01",
  "addressStreet": "Blvd. Atardecer",
  "addressExterior": "142",
  "addressNeighborhood": "Centro",
  "addressCity": "Huatabampo",
  "addressMunicipality": "Huatabampo",
  "addressZip": "86500",
  "addressState": "Sonora",
  "phone": "6474010101",
  "addressInterior": "4",
  "addressCountry": "MEX"
}
'

{
  "id": "590ce6c56d04f840aa8438af",
  "organizationId": "org-uuid",
  "legalName": "Dunder Mifflin",
  "taxId": "ABC101010111",
  "taxSystem": "601",
  "email": "email@example.com",
  "defaultInvoiceUse": "G01",
  "address": {
    "street": "Blvd. Atardecer",
    "exterior": "142",
    "neighborhood": "Centro",
    "city": "Huatabampo",
    "municipality": "Huatabampo",
    "zip": "86500",
    "state": "Sonora",
    "country": "MEX",
    "interior": "4"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "phone": "6474010101"
}

POST

organizations

{organizationId}

customers

Create a customer

curl --request POST \
  --url http://sandbox.mintlify.com/organizations/{organizationId}/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "legalName": "Dunder Mifflin",
  "taxId": "ABC101010111",
  "taxSystem": "601",
  "email": "email@example.com",
  "defaultInvoiceUse": "G01",
  "addressStreet": "Blvd. Atardecer",
  "addressExterior": "142",
  "addressNeighborhood": "Centro",
  "addressCity": "Huatabampo",
  "addressMunicipality": "Huatabampo",
  "addressZip": "86500",
  "addressState": "Sonora",
  "phone": "6474010101",
  "addressInterior": "4",
  "addressCountry": "MEX"
}
'

{
  "id": "590ce6c56d04f840aa8438af",
  "organizationId": "org-uuid",
  "legalName": "Dunder Mifflin",
  "taxId": "ABC101010111",
  "taxSystem": "601",
  "email": "email@example.com",
  "defaultInvoiceUse": "G01",
  "address": {
    "street": "Blvd. Atardecer",
    "exterior": "142",
    "neighborhood": "Centro",
    "city": "Huatabampo",
    "municipality": "Huatabampo",
    "zip": "86500",
    "state": "Sonora",
    "country": "MEX",
    "interior": "4"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "phone": "6474010101"
}

Creates a new customer (receptor de facturas) for the organization.

Authentication

Requires a valid Bearer token. The authenticated user must be a member of the organization.

Path Parameters

Parameter	Type	Required	Description
`organizationId`	string (UUID)	Yes	Organization ID

Request Body

Field	Type	Required	Description
`legalName`	string	Yes	Legal name (Razón Social)
`taxId`	string	Yes	RFC del receptor (e.g. `ABC101010111`)
`taxSystem`	string	Yes	SAT tax system code (Régimen Fiscal, e.g. `601`)
`email`	string	Yes	Customer email
`defaultInvoiceUse`	string	Yes	Default CFDI use code (e.g. `G01`)
`addressStreet`	string	Yes	Street name
`addressExterior`	string	Yes	Exterior number
`addressNeighborhood`	string	Yes	Neighborhood (Colonia)
`addressCity`	string	Yes	City
`addressMunicipality`	string	Yes	Municipality
`addressZip`	string	Yes	5-digit ZIP code
`addressState`	string	Yes	State
`phone`	string	No	Phone number
`addressInterior`	string	No	Interior number
`addressCountry`	string	No	Country code (default: `MEX`)

Example Request

curl -X POST http://localhost:3001/api/organizations/550e8400-e29b-41d4-a716-446655440000/customers \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Dunder Mifflin",
    "taxId": "DUM901231AB3",
    "taxSystem": "601",
    "email": "billing@dundermifflin.com",
    "defaultInvoiceUse": "G01",
    "addressStreet": "Blvd. Atardecer",
    "addressExterior": "142",
    "addressNeighborhood": "Centro",
    "addressCity": "Huatabampo",
    "addressMunicipality": "Huatabampo",
    "addressZip": "86500",
    "addressState": "Sonora"
  }'

Example Response

{
  "id": "590ce6c56d04f840aa8438af",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "legalName": "Dunder Mifflin",
  "taxId": "DUM901231AB3",
  "taxSystem": "601",
  "email": "billing@dundermifflin.com",
  "phone": null,
  "defaultInvoiceUse": "G01",
  "address": {
    "street": "Blvd. Atardecer",
    "exterior": "142",
    "interior": null,
    "neighborhood": "Centro",
    "city": "Huatabampo",
    "municipality": "Huatabampo",
    "zip": "86500",
    "state": "Sonora",
    "country": "MEX"
  },
  "createdAt": "2025-01-26T10:00:00Z",
  "updatedAt": "2025-01-26T10:00:00Z"
}

Common Errors

400 Bad Request

Invalid RFC format, missing required fields, or invalid ZIP code.

{
  "statusCode": 400,
  "message": ["Invalid RFC format", "addressZip must be 5 digits"]
}

401 Unauthorized

Authentication required.

403 Forbidden

User is not a member of this organization.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

organizationId

string

required

Body

application/json

legalName

string

required

Customer legal name (Razón Social)

Example:

"Dunder Mifflin"

taxId

string

required

Mexican RFC (tax identifier)

Example:

"ABC101010111"

taxSystem

string

required

SAT tax system code (Régimen Fiscal)

Example:

"601"

string

required

Customer email

Example:

"email@example.com"

defaultInvoiceUse

string

required

Default CFDI use code

Example:

"G01"

addressStreet

string

required

Street name

Example:

"Blvd. Atardecer"

addressExterior

string

required

Exterior number

Example:

"142"

addressNeighborhood

string

required

Neighborhood (Colonia)

Example:

"Centro"

addressCity

string

required

City

Example:

"Huatabampo"

addressMunicipality

string

required

Municipality

Example:

"Huatabampo"

addressZip

string

required

ZIP code

Example:

"86500"

addressState

string

required

State

Example:

"Sonora"

phone

string

Customer phone number

Example:

"6474010101"

addressInterior

string

Interior number

Example:

"4"

addressCountry

string

default:MEX

Country code

Example:

"MEX"

Response

201 - application/json

string

required

Example:

"590ce6c56d04f840aa8438af"

organizationId

string

required

Example:

"org-uuid"

legalName

string

required

Example:

"Dunder Mifflin"

taxId

string

required

Example:

"ABC101010111"

taxSystem

string

required

Example:

"601"

string

required

Example:

"email@example.com"

defaultInvoiceUse

string

required

Example:

"G01"

address

object

required

Show child attributes

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

phone

object

Example:

"6474010101"

List Customers Get Customer

API documentation

Organizations

Members

Invites

Auth

OAuth

Customers

Products

Users

Webhooks

API Keys

Authentication

Path Parameters

Request Body

Example Request

Example Response

Common Errors

400 Bad Request

401 Unauthorized

403 Forbidden

Authorizations

Path Parameters

Body

Response

API documentation

Organizations

Members

Invites

Auth

OAuth

Customers

Products

Users

Webhooks

API Keys

​Authentication

​Path Parameters

​Request Body

​Example Request

​Example Response

​Common Errors

​400 Bad Request

​401 Unauthorized

​403 Forbidden

Authorizations

Path Parameters

Body

Response

Authentication

Path Parameters

Request Body

Example Request

Example Response

Common Errors

400 Bad Request

401 Unauthorized

403 Forbidden