> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create customers

> Creates up to 100 customers in one request. Each item creates a customer without matching it to another customer record.

The API validates the entire request before creating any customers. If any item fails validation, the entire request fails and no customers are created. After validation succeeds, the API processes each item independently and returns one result for each item in the request order. A creation error for one item does not prevent the other items from being created.

Customers that share an email address are merged. For more information, see [Customer identities and merged customers](/api/customer-data-platform#customer-identities-and-merged-customers).

**Required scopes:** `customers:rw`


## OpenAPI

````yaml /api/customer-data-platform/openapi.json post /v1/create_customers
openapi: 3.0.0
info:
  title: Customer Data Platform API
  description: A service for collecting, storing, and managing end-user data.
  version: 0.0.1
servers:
  - url: https://api.text.com/cdp
    description: Main production server URL
security:
  - PersonalAccessToken: []
  - OAuth2BearerToken:
      - customers:ro
paths:
  /v1/create_customers:
    post:
      tags:
        - Customers
      summary: Create customers
      description: >-
        Creates up to 100 customers in one request. Each item creates a customer
        without matching it to another customer record.


        The API validates the entire request before creating any customers. If
        any item fails validation, the entire request fails and no customers are
        created. After validation succeeds, the API processes each item
        independently and returns one result for each item in the request order.
        A creation error for one item does not prevent the other items from
        being created.


        Customers that share an email address are merged. For more information,
        see [Customer identities and merged
        customers](/api/customer-data-platform#customer-identities-and-merged-customers).
      operationId: createCustomers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomersRequest'
            example:
              updated_at: '2026-09-01T10:00:00Z'
              customers:
                - name: Thomas Anderson
                  email: t.anderson@example.com
                  phone_number: '+15550000001'
                  address:
                    address: 1600 Pennsylvania Avenue NW
                    city: Washington
                    country: United States
                    state: DC
                    postal_code: '20500'
                  relationship_level: vip
                  properties:
                    9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11: 42
                  omnichannel:
                    fbmessenger:
                      id: 4f0ad8d8-1b7e-4519-8400-fa955eb11d12
                      name: Thomas Anderson
                      first_name: Thomas
                      last_name: Anderson
                      profile_pic: https://example.com/avatars/facebook.png
                      gender: male
                      locale: en-US
                      is_verified_user: true
                    twilio:
                      phone_number: '+15550000001'
                    whatsapp:
                      id: '15550000001'
                      name: Thomas Anderson
                      phone_number: '+15550000001'
                    instagram:
                      ig_user_id: '17841405793187218'
                      username: thomas.anderson
                      name: Thomas Anderson
                      profile_pic: https://example.com/avatars/instagram.png
                      follower_count: 120
                      is_verified_user: true
                      is_user_follow_business: true
                      is_business_follow_user: false
                    telegram:
                      telegram_user_id: 123456789
                      first_name: Thomas
                      last_name: Anderson
                      username: thomas_anderson
                      language_code: en
                      display_name: Thomas Anderson
                      is_premium: true
                    sms:
                      phone_number: '+15550000002'
                - email: trinity@example.com
      responses:
        '200':
          description: >-
            The request passed validation. Each result shows the outcome for the
            item at the same position in the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomersResponse'
              example:
                results:
                  - customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786
                  - error:
                      type: internal
                      message: Failed to create the customer.
        '401':
          description: Invalid access token.
        '403':
          description: Insufficient scopes.
        '422':
          description: >-
            Invalid request body, such as an unknown field, an empty `customers`
            array, more than 100 customers, a future `updated_at` value, missing
            contact data, an invalid email address or phone number, an unknown
            or archived property ID, or a property value that does not match its
            property type. The error message identifies the invalid item, for
            example, `customers[3].email`.
        '500':
          description: Internal error.
      security:
        - PersonalAccessToken: []
        - OAuth2BearerToken:
            - customers:rw
components:
  schemas:
    CreateCustomersRequest:
      type: object
      required:
        - customers
      additionalProperties: false
      properties:
        updated_at:
          type: string
          format: date-time
          default: '1970-01-01T00:00:00Z'
          description: >-
            The date and time when the data was last updated in the source
            system. The value cannot be in the future. Imported data does not
            replace more recent data on the merged customer record.
        customers:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/CreateCustomerItem'
          description: Customers to create.
    CreateCustomersResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          description: Results in the order of the request items.
          items:
            type: object
            properties:
              customer_id:
                type: string
                format: uuid
                description: >-
                  The ID of the created customer. Present when the item
                  succeeds.
              error:
                type: object
                description: >-
                  The error returned when the item fails. You can retry a failed
                  item.
                required:
                  - type
                  - message
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
    CreateCustomerItem:
      type: object
      additionalProperties: false
      description: >-
        A customer to create. Each item requires at least one of `email`,
        `phone_number`, or `omnichannel`.
      anyOf:
        - required:
            - email
        - required:
            - phone_number
        - required:
            - omnichannel
          properties:
            omnichannel:
              type: object
              minProperties: 1
      properties:
        name:
          type: string
          maxLength: 255
          description: The customer's name.
        email:
          type: string
          format: email
          maxLength: 255
          description: The customer's email address.
        phone_number:
          type: string
          description: >-
            The customer's phone number in E.164 format. The number must be
            valid for its country code.
        address:
          $ref: '#/components/schemas/CreateCustomerAddress'
        relationship_level:
          type: string
          enum:
            - vip
          nullable: true
          description: >-
            The customer's relationship level. Set this field to `null` or omit
            it if the customer has no relationship level.
        properties:
          type: object
          maxProperties: 100
          additionalProperties:
            description: >-
              A property value keyed by property definition ID. The value must
              match the property's type, as in [Set customer properties
              values](/api/customer-data-platform/customer-properties/set-customer-properties-values).
              The API ignores a `null` value.
          description: >-
            A map of customer property definition IDs to their values. The API
            rejects archived property IDs.
        omnichannel:
          $ref: '#/components/schemas/CreateCustomerOmnichannel'
    CreateCustomerAddress:
      type: object
      additionalProperties: false
      description: >-
        The customer's address. The API ignores an address that contains only
        empty fields.
      properties:
        address:
          type: string
          maxLength: 255
          description: The street address.
        city:
          type: string
          maxLength: 255
          description: The city name.
        country:
          type: string
          maxLength: 255
          description: The country name.
        state:
          type: string
          maxLength: 255
          description: The state or region name.
        postal_code:
          type: string
          maxLength: 255
          description: The postal code.
    CreateCustomerOmnichannel:
      type: object
      additionalProperties: false
      description: >-
        The customer's identities on supported messaging channels. Each channel
        accepts one identity object. Any provided channel counts as contact
        data.
      properties:
        fbmessenger:
          type: object
          required:
            - id
          properties:
            id:
              type: string
              maxLength: 512
              description: The Facebook Messenger ID.
            name:
              type: string
              maxLength: 512
              description: The Facebook Messenger display name.
            first_name:
              type: string
              maxLength: 256
              description: The customer's first name.
            last_name:
              type: string
              maxLength: 256
              description: The customer's last name.
            profile_pic:
              type: string
              format: url
              maxLength: 1024
              description: The HTTPS URL of the customer's profile picture.
            gender:
              type: string
              maxLength: 128
              description: The customer's gender.
            locale:
              type: string
              maxLength: 128
              description: The customer's locale as an IETF BCP 47 language tag.
            is_verified_user:
              type: boolean
              description: Set to `true` if the customer is a verified Facebook user.
        twilio:
          type: object
          required:
            - phone_number
          properties:
            phone_number:
              type: string
              description: The Twilio phone number in E.164 format.
        whatsapp:
          type: object
          required:
            - id
            - phone_number
          properties:
            id:
              type: string
              maxLength: 512
              description: The WhatsApp ID.
            name:
              type: string
              maxLength: 512
              description: The WhatsApp display name.
            phone_number:
              type: string
              description: The WhatsApp phone number in E.164 format.
        instagram:
          type: object
          required:
            - ig_user_id
          properties:
            ig_user_id:
              type: string
              maxLength: 512
              description: The Instagram user ID.
            username:
              type: string
              maxLength: 512
              description: The Instagram username.
            name:
              type: string
              maxLength: 512
              description: The Instagram display name.
            profile_pic:
              type: string
              format: url
              maxLength: 2048
              description: The HTTPS URL of the Instagram profile picture.
            follower_count:
              type: integer
              format: int64
              minimum: 0
              description: The number of the account's followers.
            is_verified_user:
              type: boolean
              description: Set to `true` if the Instagram account is verified.
            is_user_follow_business:
              type: boolean
              description: Set to `true` if the customer follows the business account.
            is_business_follow_user:
              type: boolean
              description: Set to `true` if the business account follows the customer.
        telegram:
          type: object
          required:
            - telegram_user_id
          properties:
            telegram_user_id:
              type: integer
              format: int64
              description: The Telegram user ID.
            first_name:
              type: string
              maxLength: 256
              description: The customer's first name.
            last_name:
              type: string
              maxLength: 256
              description: The customer's last name.
            username:
              type: string
              maxLength: 512
              description: The Telegram username.
            language_code:
              type: string
              maxLength: 128
              description: The language configured in the customer's Telegram client.
            display_name:
              type: string
              maxLength: 512
              description: The Telegram display name.
            is_premium:
              type: boolean
              description: >-
                Set to `true` if the customer has a Telegram Premium
                subscription.
        sms:
          type: object
          required:
            - phone_number
          properties:
            phone_number:
              type: string
              description: The SMS phone number in E.164 format.
  securitySchemes:
    PersonalAccessToken:
      description: >-
        Use your `account ID` as the username and your personal access token
        (PAT) as the password, or pass a Base64-encoded value directly in the
        Authorization header. For more information, see the <a
        href="/authentication/personal-access-tokens">personal access tokens
        guide</a>.
      type: http
      scheme: basic
    OAuth2BearerToken:
      description: >-
        This API uses OAuth2 with the implicit grant flow. <a
        href="/authentication/oauth-authorization/implicit-grant">Learn about
        the implicit grant flow.</a>
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.livechat.com
          scopes: {}
        authorizationCode:
          authorizationUrl: https://accounts.livechat.com
          tokenUrl: https://accounts.livechat.com/token
          scopes: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.