> ## Documentation Index > Fetch the complete documentation index at: https://docs.piriod.com/llms.txt > Use this file to discover all available pages before exploring further. # Create customer ## OpenAPI ````yaml POST /customers/ openapi: 3.0.3 info: title: Piriod API version: 1.0.0 description: > Piriod API for billing, payments, procurement and collections. All requests require: - `Authorization: Token ` header. - `x-simple-workspace: ` header (the account/workspace identifier). - Optionally `x-piriod-test-mode: true` to operate against test-mode data. See the Documentation tab for getting started, integration flows, authentication, error handling and pagination/filtering guides. servers: - url: https://api.piriod.com description: Production security: - TokenAuth: [] paths: /customers/: post: tags: - Billing summary: Create customer parameters: - $ref: '#/components/parameters/WorkspaceHeader' - $ref: '#/components/parameters/TestModeHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerWrite' responses: '201': description: Customer created. content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/ValidationFailed' '401': $ref: '#/components/responses/Unauthorized' components: parameters: WorkspaceHeader: name: x-simple-workspace in: header required: true schema: type: string description: Workspace (account) identifier. Required for every request. example: acc_01H8XYZ123ABC TestModeHeader: name: x-piriod-test-mode in: header required: false schema: type: boolean default: false description: Whether to operate against test-mode data. Defaults to `false`. schemas: CustomerWrite: type: object properties: name: type: string maxLength: 100 address: type: string maxLength: 64 country: type: string description: Country ID (e.g. `CL`, `MX`, `CO`). state: type: integer description: State ID. Must belong to the chosen country. currency: type: string description: ISO currency code. Defaults from the country if omitted. email: type: string format: email nullable: true phone: type: string nullable: true maxLength: 16 website: type: string format: uri nullable: true zip_code: type: string nullable: true maxLength: 16 manager: type: string maxLength: 64 nullable: true reference: type: string maxLength: 64 nullable: true tax_id: type: string maxLength: 32 nullable: true tax_settings: type: object metadata: type: object send_invoices: type: boolean default: true send_collections: type: boolean default: true send_vouchers: type: boolean default: true required: - name - address - country - state Customer: type: object properties: id: type: string readOnly: true example: cus_01H8XYZ123ABC name: type: string maxLength: 100 address: type: string maxLength: 64 country: $ref: '#/components/schemas/Country' state: $ref: '#/components/schemas/State' currency: type: string description: ISO currency code (e.g. CLP, USD). example: CLP email: type: string format: email nullable: true phone: type: string nullable: true maxLength: 16 website: type: string format: uri nullable: true zip_code: type: string nullable: true maxLength: 16 manager: type: string nullable: true maxLength: 64 description: Account manager name (free text). reference: type: string nullable: true maxLength: 64 description: External reference for the customer. tax_id: type: string nullable: true maxLength: 32 description: > Tax identifier. Required when the customer's country has tax regulation (e.g. Chile RUT, Mexico RFC, Colombia NIT) and matches the account's country. tax_settings: type: object description: > Country-specific tax configuration. Schema and required keys depend on the tax agency of the customer's country. metadata: type: object description: Arbitrary key/value metadata. Filterable via `?metadata__key=value`. send_invoices: type: boolean default: true description: Whether to email invoices to the customer. send_collections: type: boolean default: true description: Whether to email collection reminders to the customer. send_vouchers: type: boolean default: true description: Whether to email payment receipts to the customer. status: type: string enum: - active - archived - pending default: active contacts: type: array readOnly: true items: $ref: '#/components/schemas/Contact' sources: type: array readOnly: true items: type: string description: IDs of reusable payment sources currently chargeable or pending. aggregations: allOf: - $ref: '#/components/schemas/Aggregations' readOnly: true test_mode: type: boolean readOnly: true created: type: string format: date-time readOnly: true updated: type: string format: date-time readOnly: true required: - name - address - country - state Country: type: object properties: id: type: string example: CL name: type: string example: Chile code: type: string example: '+56' has_regulation: type: boolean currencies: type: array items: type: string example: CLP State: type: object properties: id: type: integer name: type: string country: type: string example: CL Contact: type: object properties: id: type: string readOnly: true example: con_01H8XYZ123ABC customer: type: string nullable: true description: Customer ID this contact belongs to. orgunit: type: string nullable: true description: Organisation unit ID. Optional sub-grouping inside a customer. name: type: string maxLength: 64 email: type: string format: email phone: type: string maxLength: 12 nullable: true invoicing: type: boolean default: true description: Whether this contact receives invoice emails. collections: type: boolean default: true description: Whether this contact receives collection reminders. created: type: string format: date-time readOnly: true updated: type: string format: date-time readOnly: true required: - name - email Aggregations: type: object properties: sales: type: number format: decimal description: Total finalized + paid sales for the customer. sales_current_period: type: number format: decimal description: Sales finalized within the current calendar month. balance: type: number format: decimal description: >- Outstanding balance across non-succeeded payments on finalized/pending invoices. ValidationError: type: object additionalProperties: type: array items: type: string description: | Field-keyed error map. The special key `non_field_errors` carries errors that are not bound to a specific field. example: name: - This field is required. non_field_errors: - x-simple-workspace header is required. Error: type: object properties: detail: type: string description: Human-readable error message. example: detail: Authentication credentials were not provided. responses: ValidationFailed: description: Request body or query parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/ValidationError' Unauthorized: description: Authentication credentials missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: TokenAuth: type: apiKey in: header name: Authorization description: | Use header `Authorization: Token `. API tokens are obtained from the Piriod dashboard. ````