> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbrix.mx/llms.txt > Use this file to discover all available pages before exploring further. # Create Customer 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 ```bash theme={null} curl -X POST http://localhost:3001/api/organizations/550e8400-e29b-41d4-a716-446655440000/customers \ -H "Authorization: Bearer " \ -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 ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ## OpenAPI ````yaml POST /organizations/{organizationId}/customers openapi: 3.1.0 info: title: Timbrix API description: >- REST API with OAuth2 server for managing organizations, members, and webhooks version: '1.0' contact: {} servers: - url: http://sandbox.mintlify.com description: Sandbox environment - url: http://localhost:3001/api description: Local development security: [] tags: - name: organizations description: Organization management endpoints - name: oauth description: OAuth2 authentication and authorization - name: webhooks description: Webhook configuration and delivery - name: users description: User information endpoints - name: api-keys description: API Keys management and validation paths: /organizations/{organizationId}/customers: post: tags: - customers summary: Create a customer operationId: CustomersController_create parameters: - name: organizationId required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomerDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/CustomerResponseDto' security: - bearer: [] components: schemas: CreateCustomerDto: type: object properties: legalName: type: string description: Customer legal name (Razón Social) example: Dunder Mifflin taxId: type: string description: Mexican RFC (tax identifier) example: ABC101010111 taxSystem: type: string description: SAT tax system code (Régimen Fiscal) example: '601' email: type: string description: Customer email example: email@example.com phone: type: string description: Customer phone number example: '6474010101' defaultInvoiceUse: type: string description: Default CFDI use code example: G01 addressStreet: type: string description: Street name example: Blvd. Atardecer addressExterior: type: string description: Exterior number example: '142' addressInterior: type: string description: Interior number example: '4' addressNeighborhood: type: string description: Neighborhood (Colonia) example: Centro addressCity: type: string description: City example: Huatabampo addressMunicipality: type: string description: Municipality example: Huatabampo addressZip: type: string description: ZIP code example: '86500' addressState: type: string description: State example: Sonora addressCountry: type: string description: Country code example: MEX default: MEX required: - legalName - taxId - taxSystem - email - defaultInvoiceUse - addressStreet - addressExterior - addressNeighborhood - addressCity - addressMunicipality - addressZip - addressState CustomerResponseDto: type: object properties: id: type: string example: 590ce6c56d04f840aa8438af organizationId: type: string example: org-uuid legalName: type: string example: Dunder Mifflin taxId: type: string example: ABC101010111 taxSystem: type: string example: '601' email: type: string example: email@example.com phone: type: object example: '6474010101' defaultInvoiceUse: type: string example: G01 address: $ref: '#/components/schemas/CustomerAddressDto' createdAt: format: date-time type: string updatedAt: format: date-time type: string required: - id - organizationId - legalName - taxId - taxSystem - email - defaultInvoiceUse - address - createdAt - updatedAt CustomerAddressDto: type: object properties: street: type: string example: Blvd. Atardecer exterior: type: string example: '142' interior: type: object example: '4' neighborhood: type: string example: Centro city: type: string example: Huatabampo municipality: type: string example: Huatabampo zip: type: string example: '86500' state: type: string example: Sonora country: type: string example: MEX required: - street - exterior - neighborhood - city - municipality - zip - state - country securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````