> ## Documentation Index > Fetch the complete documentation index at: https://docs.useaira.com/llms.txt > Use this file to discover all available pages before exploring further. # Create customer > Creates a new customer. Handles individual customers, organizations and subsidiaries (filiais) via the `type` field — subsidiaries require `parentCustomerId` pointing to an organization. Optionally accepts a `paymentAccount` payload to create the associated legal entity and payment account in the same transaction. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/customers/ openapi: 3.1.0 info: title: API Reference version: '1.0' description: Aira API Reference x-logo: url: https://static.useaira.com/images/airalogo.svg backgroundColor: '#FFFFFF' altText: Aira Logo servers: - url: https://api.useaira.com description: API base URL security: - ApiKey: [] paths: /v1/customers/: post: tags: - Customers summary: Create customer description: >- Creates a new customer. Handles individual customers, organizations and subsidiaries (filiais) via the `type` field — subsidiaries require `parentCustomerId` pointing to an organization. Optionally accepts a `paymentAccount` payload to create the associated legal entity and payment account in the same transaction. requestBody: content: application/json: schema: type: object properties: externalId: description: >- An optional external identifier of the customer from the external system, used throughout the system to identify the customer. type: string pattern: ^[a-zA-Z0-9_-]+$ example: 705faf65-9c8b-4053-8c0b-2021281ce83f name: description: The name of the customer. type: string example: Acme Inc. parentCustomerId: description: Parent customer ID when customer is a subsidiary. type: - 'null' - string format: uuid customFields: type: object description: >- Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used. additionalProperties: anyOf: - type: string - type: array items: type: string default: {} example: customField1: value1 customField2: - value2 - value3 type: description: Customer type in organizations hierarchy. type: string enum: - individual - organization - subsidiary default: individual example: individual paymentAccount: type: object description: >- Optional payment account to create together with the customer. When provided, a legal entity is created and linked to the customer in the same transaction. properties: legalEntity: type: object description: Schema representing a legal entity. properties: tradeName: type: string nullable: true businessName: type: string emails: type: array items: type: string format: email default: [] taxId: type: string pattern: ^(^\d{14}$|^\d{11}$)$ taxIdType: type: string enum: - cnpj - cpf zipCode: type: string pattern: ^[0-9]{8}$ nullable: true street: type: string nullable: true number: type: string nullable: true neighborhood: type: string nullable: true city: type: string nullable: true state: type: string enum: - AC - AL - AP - AM - BA - CE - DF - ES - GO - MA - MT - MS - MG - PA - PB - PR - PE - PI - RJ - RN - RS - RO - RR - SC - SP - SE - TO nullable: true country: type: string enum: - Brasil nullable: true complement: type: string nullable: true customFields: type: object description: >- Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used. additionalProperties: anyOf: - type: string - type: array items: type: string default: {} example: customField1: value1 customField2: - value2 - value3 required: - businessName - taxId - taxIdType - customFields additionalProperties: false required: - legalEntity additionalProperties: false required: - externalId - name additionalProperties: false required: true description: Schema representing a customer. responses: '201': description: Schema representing a customer. content: application/json: schema: type: object properties: id: description: The unique identifier of the customer in our system. type: string format: uuid externalId: description: >- An optional external identifier of the customer from the external system, used throughout the system to identify the customer. type: string pattern: ^[a-zA-Z0-9_-]+$ example: 705faf65-9c8b-4053-8c0b-2021281ce83f name: description: The name of the customer. type: string example: Acme Inc. invoicePrefix: description: >- The prefix of the customer's invoices. This is generated by the system and cannot be updated. type: string example: ACMEI type: description: Customer type in organizations hierarchy. type: string enum: - individual - organization - subsidiary example: individual parentCustomerId: description: Parent customer ID when customer is a subsidiary. type: - 'null' - string format: uuid archivedAt: description: Archive timestamp for customers that were archived. type: - 'null' - string format: date-time customFields: type: object description: >- Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used. additionalProperties: anyOf: - type: string - type: array items: type: string default: {} example: customField1: value1 customField2: - value2 - value3 required: - id - externalId - name - type additionalProperties: false '400': description: Error object returned to the client. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error code: type: string description: A unique identifier for the type of error details: oneOf: - type: object additionalProperties: true - type: array description: >- Additional context about the error, such as invalid fields or constraints. Each endpoint may include specific error details in their documentation causations: type: array description: >- Optional array of error objects following the same structure as the parent error. Only present when there's a meaningful chain of related errors to expose items: type: object properties: message: type: string description: >- A human-readable description of the underlying error cause code: type: string description: A unique identifier for the type of underlying error details: type: object additionalProperties: true description: Additional context about the underlying error required: - message - code additionalProperties: false required: - code - message additionalProperties: false components: securitySchemes: ApiKey: type: apiKey description: API Key Authentication. name: X-API-KEY in: header ````