---
title: "Add a new customer"
method: POST
path: "/customers"
tags: ["Customers"]
---

# Add a new customer

`POST /customers`

Register a new customer in the system with an account identifier and bank account information

## Request body

- union
  - IndividualCustomerCreateRequest
    - `platformCustomerId` string, required — Platform-specific customer identifier. If not provided, one will be generated by the system.
    - `umaAddress` string — Optional UMA address identifier. If not provided during customer creation, one will be generated by the system. If provided during customer update, the UMA address will be updated to the provided value. This is an optional identifier to route payments to the customer. This is an optional identifier to route payments to the customer.
    - `customerType` 'INDIVIDUAL', required
    - `fullName` string — Individual's full name
    - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
    - `nationality` string — Country code (ISO 3166-1 alpha-2)
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
  - BusinessCustomerCreateRequest
    - `platformCustomerId` string, required — Platform-specific customer identifier. If not provided, one will be generated by the system.
    - `umaAddress` string — Optional UMA address identifier. If not provided during customer creation, one will be generated by the system. If provided during customer update, the UMA address will be updated to the provided value. This is an optional identifier to route payments to the customer. This is an optional identifier to route payments to the customer.
    - `customerType` 'BUSINESS', required
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
    - `businessInfo` object — Additional information required for business entities
      - `legalName` string, required — Legal name of the business
      - `registrationNumber` string — Business registration number
      - `taxId` string — Tax identification number
    - `beneficialOwners` UltimateBeneficialOwner[]
      - `fullName` string, required — Individual's full name
      - `emailAddress` string, email — Email address of the individual
      - `phoneNumber` string — Phone number of the individual in E.164 format
      - `taxId` string — Tax identification number of the individual. This could be a Social Security Number (SSN) for US individuals, Tax Identification Number (TIN) for non-US individuals, or a Passport Number.
      - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
      - `nationality` string — Country code (ISO 3166-1 alpha-2)
      - `address` Address
        - `line1` string, required — Street address line 1
        - `line2` string — Street address line 2
        - `city` string — City
        - `state` string — State/Province/Region
        - `postalCode` string, required — Postal/ZIP code
        - `country` string, required — Country code (ISO 3166-1 alpha-2)
      - `individualType` 'DIRECTOR' | 'CONTROL_PERSON' | 'BUSINESS_POINT_OF_CONTACT' | 'TRUSTEE' | 'SETTLOR' | 'GENERAL_PARTNER', required — Type of individual in the corporation
      - `percentageOwnership` number — Percent of ownership when individual type is beneficial owner
      - `title` string — Title at company

## Response `201`

Customer created successfully

- union
  - IndividualCustomer
    - `id` string — System-generated unique identifier
    - `platformCustomerId` string, required — Platform-specific customer identifier
    - `kycStatus` 'APPROVED' | 'REJECTED' | 'PENDING_REVIEW' | 'EXPIRED' | 'CANCELED' | 'MANUALLY_APPROVED' | 'MANUALLY_REJECTED' — The current KYC status of a customer
    - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
    - `createdAt` string, date-time — Creation timestamp
    - `updatedAt` string, date-time — Last update timestamp
    - `isDeleted` boolean — Whether the customer is marked as deleted
    - `customerType` 'INDIVIDUAL', required
    - `fullName` string — Individual's full name
    - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
    - `nationality` string — Country code (ISO 3166-1 alpha-2)
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
  - BusinessCustomer
    - `id` string — System-generated unique identifier
    - `platformCustomerId` string, required — Platform-specific customer identifier
    - `kycStatus` 'APPROVED' | 'REJECTED' | 'PENDING_REVIEW' | 'EXPIRED' | 'CANCELED' | 'MANUALLY_APPROVED' | 'MANUALLY_REJECTED' — The current KYC status of a customer
    - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
    - `createdAt` string, date-time — Creation timestamp
    - `updatedAt` string, date-time — Last update timestamp
    - `isDeleted` boolean — Whether the customer is marked as deleted
    - `customerType` 'BUSINESS', required
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
    - `businessInfo` object — Additional information required for business entities
      - `legalName` string, required — Legal name of the business
      - `registrationNumber` string — Business registration number
      - `taxId` string — Tax identification number
    - `beneficialOwners` UltimateBeneficialOwner[]
      - `fullName` string, required — Individual's full name
      - `emailAddress` string, email — Email address of the individual
      - `phoneNumber` string — Phone number of the individual in E.164 format
      - `taxId` string — Tax identification number of the individual. This could be a Social Security Number (SSN) for US individuals, Tax Identification Number (TIN) for non-US individuals, or a Passport Number.
      - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
      - `nationality` string — Country code (ISO 3166-1 alpha-2)
      - `address` Address
        - `line1` string, required — Street address line 1
        - `line2` string — Street address line 2
        - `city` string — City
        - `state` string — State/Province/Region
        - `postalCode` string, required — Postal/ZIP code
        - `country` string, required — Country code (ISO 3166-1 alpha-2)
      - `individualType` 'DIRECTOR' | 'CONTROL_PERSON' | 'BUSINESS_POINT_OF_CONTACT' | 'TRUSTEE' | 'SETTLOR' | 'GENERAL_PARTNER', required — Type of individual in the corporation
      - `percentageOwnership` number — Percent of ownership when individual type is beneficial owner
      - `title` string — Title at company

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `409` — Conflict - Customer with the UMA address already exists
- `500` — Internal service error
- `501` — Not implemented

## Changes

- **2026-02-13** `2055da1ed488` — 5 breaking, 25 info
  - the response's body type/format changed from ``/`` to `object`/`` for status `400`
  - the response's body type/format changed from ``/`` to `object`/`` for status `401`
  - the response's body type/format changed from ``/`` to `object`/`` for status `409`
  - the response's body type/format changed from ``/`` to `object`/`` for status `500`
  - …26 more
- **2026-02-07** `e951665c552d` — 4 breaking, 2 warning, 2 info
  - the request property `oneOf[subschema #1: Individual Customer Create Request]/allOf[#/components/schemas/IndividualCustomerFields]/customerType` became required
  - the request property `oneOf[subschema #2: Business Customer Create Request]/allOf[#/components/schemas/BusinessCustomerFields]/customerType` became required
  - removed the required property `oneOf[subschema #1: Individual Customer]/allOf[#/components/schemas/Customer]/customerType` from the response with the `201` status
  - removed the required property `oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/Customer]/customerType` from the response with the `201` status
  - …4 more
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/customers/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/9ae8cc2fa307/schema)