Sign in

v1

latestOpenAPI 3.0.02026-07-261733191.1 MB
Customers

Create customer

Create a new customer, who you can send money to and receive money from.

post/customers

Headers

Authorizationstring required

Your API credentials. Eg. Basic {credentials}.

sequence-version'2024-07-30'

Use this header to select an API version

Request body

legalNamestring required

Legal name

urlstring

URL

labelstring

Label

taxStatus'TAXED' | 'TAX_EXEMPT' | 'REVERSE_CHARGED' required
customerAliasesstring[]

Customer aliases

parentIdstring

ID of a parent customer. Populate this field to create a new customeras a child customer of another, existing customer.

pushToIntegrationsCreateOrUpdateCustomerRequestIntegration[]

Automatically create customer in these linked integrations

status'DRAFT' | 'ACTIVE'

Example request

{
  "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"
}

Response

Created

idstring required

Unique ID

createdAtstring required

Time at which the customer was initially created, in ISO 8601 format

legalNamestring required

Legal name

urlstring

URL

domainstring

Customer's primary domain name

labelstring

Label

archivedAtstring

Time at which the customer was archived, in ISO 8601 format

taxStatus'TAXED' | 'TAX_EXEMPT' | 'REVERSE_CHARGED' required
status'DRAFT' | 'ACTIVE' required
customPropertiesobject required

Custom key-value properties for this customer

Example response

{
  "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",
  "customProperties": {
    "region": "EU",
    "tier": "gold"
  }
}