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

# Create customer

> Create a new [customer](/customers/overview), who you can send money to and receive money from.



## OpenAPI

````yaml customer.2024-07-30.product.live POST /customers
openapi: 3.0.0
info:
  title: Customers
  description: Manage customers and contacts
  version: '0.1'
servers:
  - url: https://dev.seqhq.io/api
    description: DEV
  - url: https://sandbox.sequencehq.com/api
    description: SANDBOX
  - url: https://eu.sequencehq.com/api
    description: PRODUCTION
security: []
tags: []
paths:
  /customers:
    servers: []
    parameters: []
    post:
      tags:
        - Customers
      summary: Create customer
      description: >-
        Create a new [customer](/customers/overview), who you can send money to
        and receive money from.
      operationId: postCustomers
      parameters:
        - name: Authorization
          in: header
          description: >-
            Your [API credentials](/reference/authentication). Eg. `Basic
            {credentials}`.
          required: true
          schema:
            type: string
        - name: Sequence-Version
          in: header
          description: Use this header to select an API version
          required: false
          schema:
            type: string
            enum:
              - '2024-07-30'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateCustomerRequest'
              example:
                legalName: John Doe
                address:
                  line1: Flat 1
                  line2: 123 Fake Street
                  town: New York
                  state: NY
                  postcode: AB1 2EF
                  country: US
                url: https://example.com/
                label: Example customer
                taxStatus: TAXED
                customerAliases:
                  - b1c87177-088a-40ec-8917-9809343f3f9c
                integrationIds:
                  - service: Xero
                    id: '123456789'
                  - service: Stripe
                    id: cus_OCtCxqQDgu1uX9
                  - service: HubSpot
                    id: '123456789'
                parentId: 50af5191-05a3-42a5-802a-6b59091157af
                contacts:
                  - name: John Smith
                    email: john.smith@example.com
                    billingPreference: PRIMARY
                  - name: Anna Smith
                    email: anna.smith@example.com
                    billingPreference: STANDARD
                  - name: Penny Smith
                    email: penny.smith@example.com
                    billingPreference: NONE
                pushToIntegrations:
                  - Xero
                status: ACTIVE
            examples:
              CreateOrUpdateCustomerRequest:
                summary: ''
                value:
                  legalName: John Doe
                  address:
                    line1: Flat 1
                    line2: 123 Fake Street
                    town: New York
                    state: NY
                    postcode: AB1 2EF
                    country: US
                  url: https://example.com/
                  label: Example customer
                  taxStatus: TAXED
                  customerAliases:
                    - b1c87177-088a-40ec-8917-9809343f3f9c
                  integrationIds:
                    - service: Xero
                      id: '123456789'
                    - service: Stripe
                      id: cus_OCtCxqQDgu1uX9
                    - service: HubSpot
                      id: '123456789'
                  parentId: 50af5191-05a3-42a5-802a-6b59091157af
                  contacts:
                    - name: John Smith
                      email: john.smith@example.com
                      billingPreference: PRIMARY
                    - name: Anna Smith
                      email: anna.smith@example.com
                      billingPreference: STANDARD
                    - name: Penny Smith
                      email: penny.smith@example.com
                      billingPreference: NONE
                  pushToIntegrations:
                    - Xero
                  status: ACTIVE
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
                example:
                  id: e309e948-088e-4d77-b654-cd85498f1555
                  createdAt: '2021-01-02T10:55:00Z'
                  organizations:
                    - id: c0dc4e79-ec52-4811-8cf5-addb2527915c
                      owner:
                        id: 50af5191-05a3-42a5-802a-6b59091157af
                        name: FinTech Solutions Inc.
                      members:
                        - id: e309e948-088e-4d77-b654-cd85498f1555
                          name: Fintech Payment Processing
                        - id: 50af5191-05a3-42a5-802a-6b59091157af
                          name: Fintech Lending Services
                  legalName: Fintech Payment Processing
                  address:
                    line1: 7500 Bluewater Rd NW
                    town: Albuquerque
                    state: NY
                    postcode: '87121'
                    country: US
                  url: https://example.com/
                  domain: example.com
                  label: Example customer
                  integrationIds:
                    - service: Xero
                      id: 2aaff66f-ef30-4599-b192-c168fd4cd226
                      lastSynced: '2024-03-28T16:47:00Z'
                      isPending: false
                    - service: Stripe
                      id: cus_OCtCxqQDgu1uX9
                      lastSynced: '2024-03-28T16:47:00Z'
                      isPending: false
                  archivedAt: '2025-08-28T12:00:00Z'
                  taxStatus: TAXED
                  contacts:
                    - id: 9a1e38a9-4dc9-776f-f974-4e7ee9f4d6cc
                      name: John Smith
                      email: john.smith@example.com
                      billingPreference: NONE
                      createdAt: '2022-06-28T16:47:00Z'
                      updatedAt: '2022-06-28T16:47:00Z'
                      archivedAt: '2023-06-28T16:47:00Z'
                  status: ACTIVE
              examples:
                Customer:
                  summary: ''
                  value:
                    id: e309e948-088e-4d77-b654-cd85498f1555
                    createdAt: '2021-01-02T10:55:00Z'
                    organizations:
                      - id: c0dc4e79-ec52-4811-8cf5-addb2527915c
                        owner:
                          id: 50af5191-05a3-42a5-802a-6b59091157af
                          name: FinTech Solutions Inc.
                        members:
                          - id: e309e948-088e-4d77-b654-cd85498f1555
                            name: Fintech Payment Processing
                          - id: 50af5191-05a3-42a5-802a-6b59091157af
                            name: Fintech Lending Services
                    legalName: Fintech Payment Processing
                    address:
                      line1: 7500 Bluewater Rd NW
                      town: Albuquerque
                      state: NY
                      postcode: '87121'
                      country: US
                    url: https://example.com/
                    domain: example.com
                    label: Example customer
                    integrationIds:
                      - service: Xero
                        id: 2aaff66f-ef30-4599-b192-c168fd4cd226
                        lastSynced: '2024-03-28T16:47:00Z'
                        isPending: false
                      - service: Stripe
                        id: cus_OCtCxqQDgu1uX9
                        lastSynced: '2024-03-28T16:47:00Z'
                        isPending: false
                    archivedAt: '2025-08-28T12:00:00Z'
                    taxStatus: TAXED
                    contacts:
                      - id: 9a1e38a9-4dc9-776f-f974-4e7ee9f4d6cc
                        name: John Smith
                        email: john.smith@example.com
                        billingPreference: NONE
                        createdAt: '2022-06-28T16:47:00Z'
                        updatedAt: '2022-06-28T16:47:00Z'
                        archivedAt: '2023-06-28T16:47:00Z'
                    status: ACTIVE
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '500':
          description: Internal Server Error
          content: {}
components:
  schemas:
    CreateOrUpdateCustomerRequest:
      required:
        - address
        - contacts
        - legalName
        - taxStatus
      type: object
      example:
        legalName: John Doe
        address:
          line1: Flat 1
          line2: 123 Fake Street
          town: New York
          state: NY
          postcode: AB1 2EF
          country: US
        url: https://example.com/
        label: Example customer
        taxStatus: TAXED
        customerAliases:
          - b1c87177-088a-40ec-8917-9809343f3f9c
        integrationIds:
          - service: Xero
            id: '123456789'
          - service: Stripe
            id: cus_OCtCxqQDgu1uX9
          - service: HubSpot
            id: '123456789'
        parentId: 50af5191-05a3-42a5-802a-6b59091157af
        contacts:
          - name: John Smith
            email: john.smith@example.com
            billingPreference: PRIMARY
          - name: Anna Smith
            email: anna.smith@example.com
            billingPreference: STANDARD
          - name: Penny Smith
            email: penny.smith@example.com
            billingPreference: NONE
        pushToIntegrations:
          - Xero
        status: ACTIVE
      properties:
        legalName:
          type: string
          description: Legal name
          example: John Doe
        address:
          $ref: '#/components/schemas/Address'
        url:
          type: string
          description: URL
          example: https://example.com/
        label:
          type: string
          description: Label
          example: Example customer
        taxStatus:
          $ref: '#/components/schemas/TaxStatus'
          description: >-
            Tax status applicable to customer. Can be one of TAXED, TAX_EXEMPT
            or REVERSE_CHARGED. The default is TAXED.
        customerAliases:
          type: array
          description: Customer aliases
          example:
            - b1c87177-088a-40ec-8917-9809343f3f9c
          items:
            type: string
        integrationIds:
          type: array
          description: IDs in external integrations
          example:
            - service: Xero
              id: '123456789'
            - service: Stripe
              id: cus_OCtCxqQDgu1uX9
            - service: HubSpot
              id: '123456789'
          items:
            $ref: '#/components/schemas/GenerateIntegrationIdRequest'
        parentId:
          type: string
          description: >-
            ID of a parent customer. Populate this field to create a new
            customeras a child customer of another, existing customer.
          example: 50af5191-05a3-42a5-802a-6b59091157af
        contacts:
          type: array
          description: >-
            Contacts to create for this customer. This will replace all existing
            contacts for this customer. Needs atleast one Contact with a billing
            preference of 'PRIMARY'
          example:
            - name: John Smith
              email: john.smith@example.com
              billingPreference: PRIMARY
            - name: Anna Smith
              email: anna.smith@example.com
              billingPreference: STANDARD
            - name: Penny Smith
              email: penny.smith@example.com
              billingPreference: NONE
          items:
            $ref: '#/components/schemas/ContactRequestModel'
        pushToIntegrations:
          type: array
          description: Automatically create customer in these linked integrations
          example:
            - Xero
          items:
            $ref: '#/components/schemas/CreateOrUpdateCustomerRequestIntegration'
        status:
          $ref: '#/components/schemas/CustomerStatus'
          description: >-
            Customer status:

            - DRAFT means the customer has been extracted from a contract and
            has not yet been approved. It cannot be used while it is in DRAFT.

            - ACTIVE is the default state when a customer is created via API or
            dashboard.
    Customer:
      required:
        - address
        - contacts
        - createdAt
        - id
        - integrationIds
        - legalName
        - organizations
        - status
        - taxStatus
      type: object
      example:
        id: e309e948-088e-4d77-b654-cd85498f1555
        createdAt: '2021-01-02T10:55:00Z'
        organizations:
          - id: c0dc4e79-ec52-4811-8cf5-addb2527915c
            owner:
              id: 50af5191-05a3-42a5-802a-6b59091157af
              name: FinTech Solutions Inc.
            members:
              - id: e309e948-088e-4d77-b654-cd85498f1555
                name: Fintech Payment Processing
              - id: 50af5191-05a3-42a5-802a-6b59091157af
                name: Fintech Lending Services
        legalName: Fintech Payment Processing
        address:
          line1: 7500 Bluewater Rd NW
          town: Albuquerque
          state: NY
          postcode: '87121'
          country: US
        url: https://example.com/
        domain: example.com
        label: Example customer
        integrationIds:
          - service: Xero
            id: 2aaff66f-ef30-4599-b192-c168fd4cd226
            lastSynced: '2024-03-28T16:47:00Z'
            isPending: false
          - service: Stripe
            id: cus_OCtCxqQDgu1uX9
            lastSynced: '2024-03-28T16:47:00Z'
            isPending: false
        archivedAt: '2025-08-28T12:00:00Z'
        taxStatus: TAXED
        contacts:
          - id: 9a1e38a9-4dc9-776f-f974-4e7ee9f4d6cc
            name: John Smith
            email: john.smith@example.com
            billingPreference: NONE
            createdAt: '2022-06-28T16:47:00Z'
            updatedAt: '2022-06-28T16:47:00Z'
            archivedAt: '2023-06-28T16:47:00Z'
        status: ACTIVE
      properties:
        id:
          type: string
          description: Unique ID
          example: e309e948-088e-4d77-b654-cd85498f1555
        createdAt:
          type: string
          description: Time at which the customer was initially created, in ISO 8601 format
          example: '2021-01-02T10:55:00Z'
        organizations:
          type: array
          description: Organizations that this customer is a member of
          example:
            - id: c0dc4e79-ec52-4811-8cf5-addb2527915c
              owner:
                id: 50af5191-05a3-42a5-802a-6b59091157af
                name: FinTech Solutions Inc.
              members:
                - id: e309e948-088e-4d77-b654-cd85498f1555
                  name: Fintech Payment Processing
                - id: 50af5191-05a3-42a5-802a-6b59091157af
                  name: Fintech Lending Services
          items:
            $ref: '#/components/schemas/CustomerOrganization'
        legalName:
          type: string
          description: Legal name
          example: Fintech Payment Processing
        address:
          $ref: '#/components/schemas/Address'
        url:
          type: string
          description: URL
          example: https://example.com/
        domain:
          type: string
          description: Customer's primary domain name
          example: example.com
        label:
          type: string
          description: Label
          example: Example customer
        integrationIds:
          type: array
          description: External services which are linked to this customer
          example:
            - service: Xero
              id: 2aaff66f-ef30-4599-b192-c168fd4cd226
              lastSynced: '2024-03-28T16:47:00Z'
              isPending: false
            - service: Stripe
              id: cus_OCtCxqQDgu1uX9
              lastSynced: '2024-03-28T16:47:00Z'
              isPending: false
          items:
            $ref: '#/components/schemas/IntegrationId'
        archivedAt:
          type: string
          description: Time at which the customer was archived, in ISO 8601 format
          example: '2025-08-28T12:00:00Z'
        taxStatus:
          $ref: '#/components/schemas/TaxStatus'
          description: >-
            Tax status applicable to customer. Can be one of TAXED, TAX_EXEMPT
            or REVERSE_CHARGED. The default is TAXED.
        contacts:
          type: array
          description: Contacts for this customer
          example:
            - id: 9a1e38a9-4dc9-776f-f974-4e7ee9f4d6cc
              name: John Smith
              email: john.smith@example.com
              billingPreference: NONE
              createdAt: '2022-06-28T16:47:00Z'
              updatedAt: '2022-06-28T16:47:00Z'
              archivedAt: '2023-06-28T16:47:00Z'
          items:
            $ref: '#/components/schemas/Contact'
        status:
          $ref: '#/components/schemas/CustomerStatus'
          description: >-
            Customer status:

            - DRAFT means the customer has been extracted from a contract and
            has not yet been approved. It cannot be used while it is in DRAFT.

            - ACTIVE is the default state when a customer is created via API or
            dashboard.
    Address:
      required:
        - country
        - line1
        - postcode
        - town
      type: object
      description: Address
      example:
        line1: 7500 Bluewater Rd NW
        town: Albuquerque
        state: NY
        postcode: '87121'
        country: US
      properties:
        line1:
          type: string
          description: Address line 1
          example: 7500 Bluewater Rd NW
        town:
          type: string
          description: Town or city
          example: Albuquerque
        state:
          $ref: '#/components/schemas/State'
          description: State or province (required for USA and Canada)
        postcode:
          type: string
          description: Postal code
          example: '87121'
        country:
          $ref: '#/components/schemas/CountryCode'
          description: >-
            Country code ([ISO 3166-1
            alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes))
    TaxStatus:
      type: string
      example: TAXED
      enum:
        - TAXED
        - TAX_EXEMPT
        - REVERSE_CHARGED
    GenerateIntegrationIdRequest:
      required:
        - id
        - service
      type: object
      example:
        service: Xero
        id: '123456789'
      properties:
        service:
          $ref: '#/components/schemas/IntegrationService'
        id:
          type: string
          example: '123456789'
    ContactRequestModel:
      required:
        - billingPreference
        - email
        - name
      type: object
      example:
        name: John Smith
        email: john.smith@example.com
        billingPreference: PRIMARY
      properties:
        name:
          type: string
          description: Full name of this contact
          example: John Smith
        email:
          type: string
          description: Email address of this contact
          example: john.smith@example.com
        billingPreference:
          $ref: '#/components/schemas/ContactBillingPreference'
          description: >-
            Billing preference. Whether this contact receives billing
            communications. Options are NONE, STANDARD or PRIMARY. For a given
            customer, if any contacts receive billing communications then at
            least one contact must be designated PRIMARY for billing.
    CreateOrUpdateCustomerRequestIntegration:
      type: string
      example: Xero
      enum:
        - Xero
    CustomerStatus:
      type: string
      example: ACTIVE
      enum:
        - DRAFT
        - ACTIVE
    CustomerOrganization:
      required:
        - id
        - members
        - owner
      type: object
      example:
        id: c0dc4e79-ec52-4811-8cf5-addb2527915c
        owner:
          id: 50af5191-05a3-42a5-802a-6b59091157af
          name: FinTech Solutions Inc.
        members:
          - id: e309e948-088e-4d77-b654-cd85498f1555
            name: Fintech Payment Processing
          - id: 50af5191-05a3-42a5-802a-6b59091157af
            name: Fintech Lending Services
      properties:
        id:
          type: string
          description: Organization ID
          example: c0dc4e79-ec52-4811-8cf5-addb2527915c
        owner:
          $ref: '#/components/schemas/CustomerIdWithName'
        members:
          type: array
          description: >-
            Members of the customer organization, excluding the owner. These are
            the children in a parent-child relationship.
          example:
            - id: e309e948-088e-4d77-b654-cd85498f1555
              name: Fintech Payment Processing
            - id: 50af5191-05a3-42a5-802a-6b59091157af
              name: Fintech Lending Services
          items:
            $ref: '#/components/schemas/CustomerIdWithName'
    IntegrationId:
      required:
        - id
        - isPending
        - service
      type: object
      example:
        service: Xero
        id: 2aaff66f-ef30-4599-b192-c168fd4cd226
        lastSynced: '2024-03-28T16:47:00Z'
        isPending: false
      properties:
        service:
          $ref: '#/components/schemas/IntegrationService'
        id:
          type: string
          example: 2aaff66f-ef30-4599-b192-c168fd4cd226
        lastSynced:
          type: string
          example: '2024-03-28T16:47:00Z'
        isPending:
          type: boolean
          example: false
    Contact:
      required:
        - billingPreference
        - createdAt
        - email
        - id
        - name
        - updatedAt
      type: object
      example:
        id: 9a1e38a9-4dc9-776f-f974-4e7ee9f4d6cc
        name: John Smith
        email: john.smith@example.com
        billingPreference: NONE
        createdAt: '2022-06-28T16:47:00Z'
        updatedAt: '2022-06-28T16:47:00Z'
        archivedAt: '2023-06-28T16:47:00Z'
      properties:
        id:
          type: string
          description: Unique ID
          example: 9a1e38a9-4dc9-776f-f974-4e7ee9f4d6cc
        name:
          type: string
          description: Full name of this contact
          example: John Smith
        email:
          type: string
          description: Email address of this contact
          example: john.smith@example.com
        billingPreference:
          $ref: '#/components/schemas/ContactBillingPreference'
          description: >-
            Billing preference. Whether this contact receives billing
            communications. Options are NONE, STANDARD or PRIMARY. For a given
            customer, if any contacts receive billing communications then at
            least one contact must be designated PRIMARY for billing.
        createdAt:
          type: string
          description: Time of creation. Formatted as an ISO 8601 timestamp.
          example: '2022-06-28T16:47:00Z'
        updatedAt:
          type: string
          description: Time of last update. Formatted as an ISO 8601 timestamp.
          example: '2022-06-28T16:47:00Z'
        archivedAt:
          type: string
          description: Time of archive. Formatted as an ISO 8601 timestamp.
          example: '2023-06-28T16:47:00Z'
    State:
      type: string
      example: NY
      enum:
        - AL
        - AK
        - AZ
        - AR
        - CA
        - CO
        - CT
        - DC
        - DE
        - FL
        - GA
        - HI
        - ID
        - IL
        - IN
        - IA
        - KS
        - KY
        - LA
        - ME
        - MD
        - MA
        - MI
        - MN
        - MS
        - MO
        - MT
        - NE
        - NV
        - NH
        - NJ
        - NM
        - NY
        - NC
        - ND
        - OH
        - OK
        - OR
        - PA
        - RI
        - SC
        - SD
        - TN
        - TX
        - UT
        - VT
        - VA
        - WA
        - WV
        - WI
        - WY
        - AB
        - BC
        - MB
        - NB
        - NL
        - NS
        - NT
        - NU
        - 'ON'
        - PE
        - QC
        - SK
        - YT
    CountryCode:
      type: string
      example: US
      enum:
        - AD
        - AE
        - AF
        - AG
        - AI
        - AL
        - AM
        - AO
        - AQ
        - AR
        - AS
        - AT
        - AU
        - AW
        - AX
        - AZ
        - BA
        - BB
        - BD
        - BE
        - BF
        - BG
        - BH
        - BI
        - BJ
        - BL
        - BM
        - BN
        - BO
        - BQ
        - BR
        - BS
        - BT
        - BV
        - BW
        - BY
        - BZ
        - CA
        - CC
        - CD
        - CF
        - CG
        - CH
        - CI
        - CK
        - CL
        - CM
        - CN
        - CO
        - CR
        - CU
        - CV
        - CW
        - CX
        - CY
        - CZ
        - DE
        - DJ
        - DK
        - DM
        - DO
        - DZ
        - EC
        - EE
        - EG
        - EH
        - ER
        - ES
        - ET
        - FI
        - FJ
        - FK
        - FM
        - FO
        - FR
        - GA
        - GB
        - GD
        - GE
        - GF
        - GG
        - GH
        - GI
        - GL
        - GM
        - GN
        - GP
        - GQ
        - GR
        - GS
        - GT
        - GU
        - GW
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IE
        - IL
        - IM
        - IN
        - IO
        - IQ
        - IR
        - IS
        - IT
        - JE
        - JM
        - JO
        - JP
        - KE
        - KG
        - KH
        - KI
        - KM
        - KN
        - KP
        - KR
        - KW
        - KY
        - KZ
        - LA
        - LB
        - LC
        - LI
        - LK
        - LR
        - LS
        - LT
        - LU
        - LV
        - LY
        - MA
        - MC
        - MD
        - ME
        - MF
        - MG
        - MH
        - MK
        - ML
        - MM
        - MN
        - MO
        - MP
        - MQ
        - MR
        - MS
        - MT
        - MU
        - MV
        - MW
        - MX
        - MY
        - MZ
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NL
        - 'NO'
        - NP
        - NR
        - NU
        - NZ
        - OM
        - PA
        - PE
        - PF
        - PG
        - PH
        - PK
        - PL
        - PM
        - PN
        - PR
        - PS
        - PT
        - PW
        - PY
        - QA
        - RE
        - RO
        - RS
        - RU
        - RW
        - SA
        - SB
        - SC
        - SD
        - SE
        - SG
        - SH
        - SI
        - SJ
        - SK
        - SL
        - SM
        - SN
        - SO
        - SR
        - SS
        - ST
        - SV
        - SX
        - SY
        - SZ
        - TC
        - TD
        - TF
        - TG
        - TH
        - TJ
        - TK
        - TL
        - TM
        - TN
        - TO
        - TR
        - TT
        - TV
        - TW
        - TZ
        - UA
        - UG
        - UM
        - US
        - UY
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - XK
        - YE
        - YT
        - ZA
        - ZM
        - ZW
    IntegrationService:
      type: string
      example: Xero
      enum:
        - Amazon_Redshift
        - GoCardless
        - Google_BigQuery
        - Google_Sheets
        - HubSpot
        - NetSuite
        - QuickBooks_Online
        - Salesforce
        - Slack
        - Snowflake
        - Stripe
        - Xero
        - Avalara
        - Anrok
        - Attio
        - Numeral
        - Rillet
        - Sphere
    ContactBillingPreference:
      type: string
      example: NONE
      enum:
        - PRIMARY
        - STANDARD
        - NONE
    CustomerIdWithName:
      required:
        - id
        - name
      type: object
      description: ID of the customer that will own the organization.
      example:
        id: 50af5191-05a3-42a5-802a-6b59091157af
        name: FinTech Solutions Inc.
      properties:
        id:
          type: string
          description: Customer ID
          example: 50af5191-05a3-42a5-802a-6b59091157af
        name:
          type: string
          description: Customer legal name
          example: FinTech Solutions Inc.

````