> ## Documentation Index > Fetch the complete documentation index at: https://telnesstech-a0a16404.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create customer > Create a new customer. ## OpenAPI ````yaml /api-reference/bundled_openapi.json post /customers openapi: 3.1.0 info: title: Telness Tech Connect version: 2.0.0-alpha description: > Telness Tech Connect API provides all you need to own your user's connectivity experience. Go back to [Telnesstech.com](https://telnesstech.com) servers: - url: https://apiv2.example.com description: Connect API URL for your domain security: - apiKey: [] - bearerAuth: [] apiKey: [] tags: - name: Auth description: Authenticate users and obtain access tokens. - name: Users description: Manage users. - name: Customers description: Manage customers. - name: Subscriptions description: Manage subscriptions and subscription. - name: Subscription Addons description: Manage subscription addons. - name: Subscription Usage description: Get subscription usage. - name: Subscribers description: Manage subscribers. - name: Licenses description: Manage licenses. - name: Product Offerings description: Browse product offerings. - name: Product Catalogs description: Browse product catalogs. - name: Product Discounts description: Discounts and promotions. - name: Orders description: Manage orders and line items. - name: Payment Intents description: >- Inspect payment intents, the money collected over card rails for orders and renewals. - name: Payment Links description: Create and manage payment links for orders and invoices. - name: Payment Sessions description: Create and manage payment sessions for orders. - name: Payment Profiles description: Manage customer payment profiles and methods. - name: Payment Profile Sessions description: Create sessions for setting up payment profiles. - name: Signing sessions description: Handle contract signing sessions for postpaid orders. - name: Porting description: Manage number porting for subscriptions. - name: Taxes description: Calculate taxes for products and line items. - name: Invoices description: Manage invoices and invoice items. - name: Tools description: >- Tools for address validation, number porting, device info, and network coverage. - name: Inventory description: Manage phone number inventory, SIM cards, and reservations. - name: Workflows description: Dynamic processing of customer journeys and events. paths: /customers: post: tags: - Customers summary: Create customer description: Create a new customer. operationId: createCustomer parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomerRequest' responses: '201': description: Customer created successfully. content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: parameters: IdempotencyKey: in: header name: X-Idempotency-Key required: false description: > A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. schema: type: string maxLength: 256 schemas: CreateCustomerRequest: type: object description: | Request to create a customer with optional payment profile setup. required: - customerType - name - contact - billing - contactPersonUserId - userIds additionalProperties: false properties: customerType: $ref: '#/components/schemas/CustomerType' name: type: string description: Name of the customer. example: John Doe identity: $ref: '#/components/schemas/Identity' referenceId: type: string description: | Optional reference ID to assign to the customer. Must be unique per tenant. example: crm-customer-12345 maxLength: 255 preferredLocale: type: string description: >- The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). example: en-US default: en-US contact: type: object description: Contact details for the customer. required: - email properties: email: type: string format: email description: The primary contact email for the customer. example: john.doe@example.com msisdn: type: string format: phone description: The primary contact phone number for the customer. example: '+15551234567' billing: type: object description: Billing configuration and payment preferences for the customer. required: - method - currency additionalProperties: false properties: method: $ref: '#/components/schemas/CustomerBillingMethod' description: How invoices should be delivered to the customer. email: type: string format: email description: | The email address to send invoices to. Required if billing method is EMAIL_INVOICE. example: billing@company.com address: $ref: '#/components/schemas/Address' description: > The billing address for the customer. Used for invoicing and tax calculation. currency: $ref: '#/components/schemas/Currency' description: The currency for customer billing and payments. defaultPaymentProfileId: type: string description: > Default payment profile to use for automatic payments and new orders. Must be a payment profile that will be accessible to this customer. example: l47ac10b-58cc-4372-a567-0e02b2c3d479 autoPay: type: boolean description: > Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. example: true default: false userIds: type: array description: > List of user IDs to associate with this customer. Depending on the user's role they will either be a member of the customer or given access to manage it. items: type: string contactPersonUserId: type: string description: > The user ID of the contact person for this customer. This user will be set as the primary contact for the customer and will receive important notifications. shipping: $ref: '#/components/schemas/Shipping' description: > The default shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. metadata: $ref: '#/components/schemas/Metadata' Customer: type: object description: > A customer is a billable entity, the person or organization responsible for paying for services. The customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer. required: - customerId - customerType - name - billingMethod - contact properties: customerId: type: string description: Unique identifier for the customer. customerType: $ref: '#/components/schemas/CustomerType' name: type: string description: Name of the customer. identity: $ref: '#/components/schemas/Identity' preferredLocale: type: string description: >- The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). example: en-US default: en-US humanReadableId: type: string description: > A human-readable identifier for the customer that customers can state in support requests. example: 29A-BY3Z-X78 referenceId: type: string description: > A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation. example: crm-customer-12345 maxLength: 255 contact: type: object description: Contact details for the customer. properties: email: type: string format: email description: The primary contact email for the customer. msisdn: type: string format: phone description: The primary contact phone number for the customer. billing: type: object description: Billing configuration and payment preferences for the customer. required: - method - currency additionalProperties: false properties: method: $ref: '#/components/schemas/CustomerBillingMethod' description: How invoices should be delivered to the customer. email: type: string format: email description: | The email address to send invoices to. Required if billing method is EMAIL_INVOICE. example: billing@company.com address: $ref: '#/components/schemas/Address' description: | The billing address for the customer. Required if billing method is PAPER_INVOICE. currency: $ref: '#/components/schemas/Currency' description: The currency for customer billing and payments. defaultPaymentProfileId: type: string description: > Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills. example: c1d2e3f4-a5b6-7890-1234-901234567890 autoPay: type: boolean description: > Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. example: true default: false users: type: array description: List of users associated with this customer. items: $ref: '#/components/schemas/EmbeddedCustomerUser' contactPerson: $ref: '#/components/schemas/EmbeddedCustomerUser' description: The primary contact person for the customer. shipping: $ref: '#/components/schemas/Shipping' description: > The shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. metadata: $ref: '#/components/schemas/Metadata' CustomerType: type: string description: The type of customer. enum: - CONSUMER - BUSINESS Identity: type: string description: >- The identity of the entity, such as personal number, organization number, etc., depending on the country, entity, and customer type. CustomerBillingMethod: type: string enum: - E_INVOICE - EMAIL_INVOICE - PAPER_INVOICE description: The billing method for the customer. Address: type: object required: - street1 - city - zip - country properties: street1: type: string description: The first line of the address, typically street and house number. example: 500 S Main St street2: type: string description: >- The second line of the address, typically apartment, suite, unit, building, floor, etc. example: Apt 1 city: type: string description: The city or municipality of the address. example: Natick zip: type: string description: > The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). example: '01701' country: type: string description: >- The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). pattern: ^[A-Z]{2}$ example: US state: type: string description: >- For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). example: CA region: type: string description: >- A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). attention: type: string description: >- An optional line for specifying a person, department, or attention to a specific entity within an address. Currency: type: string description: A currency code in ISO 4217 format. example: USD Shipping: type: object description: >- Shipping information for order fulfillment. Only required if the order contains shippable items. required: - name - address additionalProperties: false properties: name: type: string description: Name of the shipping recipient. example: John Doe msisdn: type: string format: phone description: Phone number for delivery contact. example: '+15551234567' address: $ref: '#/components/schemas/Address' instructions: type: string description: Special delivery instructions. example: Leave at front door Metadata: type: object additionalProperties: type: string description: > A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. EmbeddedCustomerUser: type: object description: An embedded representation of a user. required: - userId - name properties: userId: type: string description: Unique identifier for the user name: type: string description: Name of the user role: $ref: '#/components/schemas/UserRole' Error: type: object required: - message - code properties: message: type: string description: A human-readable message providing more details about the error. code: type: string description: A machine-readable code for the error. details: type: array description: Additional details about the error. items: type: object required: - message - code properties: message: type: string description: >- A human-readable message providing more details about the error. code: type: string description: A machine-readable code for the specific detail. property: type: string description: The property or field related to the error. suggestion: $ref: '#/components/schemas/Any' description: > A suggested value for the particular property. For example, this may be set when validating an address with an alias, suggesting the expected value by the operator. hint: type: string description: A hint to help resolve the error. UserRole: type: string description: The role of the user within the customer. enum: - MEMBER - MANAGER - ADMIN Any: oneOf: - type: string - type: number - type: boolean - type: object additionalProperties: true - type: array responses: BadRequest: description: The request was malformed or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required to access this resource. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Access to this resource is forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too many requests have been sent in a given amount of time. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: An unexpected error occurred on the server. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: X-Api-Key description: > An API key that grants access to the Connect API. You can create and manage API keys in the portal. bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Bearer authentication with JWT tokens is used to authenticate users. Do note that a valid API keys is also required to access the Connect API to prove that requests are made by a trusted party. Requests with a JWT token is scoped to the permissions of the user the token belongs to, regardless of the API key used. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.