Create Customer - Timbrix Docs

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"]
}

Fiscal validation error (CFDI 4.0)

When taxId, taxSystem, and defaultInvoiceUse are provided, the API validates that the combination is allowed by SAT CFDI 4.0 rules. RFC length determines persona type: 12 characters = persona moral, 13 characters = persona física. The régimen and uso CFDI must both be valid for that persona type, and the (uso, régimen) pair must exist in the SAT compatibility matrix.

{
  "statusCode": 400,
  "message": "El uso de CFDI \"D01\" no aplica para persona moral (RFC de 12 caracteres)",
  "error": "BAD_REQUEST"
}

Other examples of fiscal validation errors:

"El régimen fiscal \"621\" no aplica para persona moral (RFC de 12 caracteres)"
"El uso de CFDI \"G01\" no es compatible con el régimen fiscal \"605\""

Use GET /sat/regimenes-fiscales and GET /sat/usos-cfdi to look up valid codes and compatible combinations before creating a customer.

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

​Authentication

​Path Parameters

​Request Body

​Example Request

​Example Response

​Common Errors

​400 Bad Request

​Fiscal validation error (CFDI 4.0)

​401 Unauthorized

​403 Forbidden

Authorizations

Path Parameters

Body

Response

Authentication

Path Parameters

Request Body

Example Request

Example Response

Common Errors

400 Bad Request

Fiscal validation error (CFDI 4.0)

401 Unauthorized

403 Forbidden