---
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
  - object
    - `customerType` 'INDIVIDUAL', required — Customer type
    - `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)
    - `platformCustomerId` string — Platform-specific customer identifier
    - `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.
  - object
    - `customerType` 'BUSINESS', required — Customer type
    - `umaAddress` string — Optional UMA address identifier. If not provided, will be generated by the system.
    - `businessInfo` object
      - `legalName` string — Legal name of the business
      - `registrationNumber` string — Business registration number
      - `taxId` string — Tax identification number
    - `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)
    - `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
    - `customerType` 'INDIVIDUAL' | 'BUSINESS', required — Whether the customer is an individual or a business entity
    - `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
    - `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
    - `customerType` 'INDIVIDUAL' | 'BUSINESS', required — Whether the customer is an individual or a business entity
    - `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
    - `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

---

[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/d1490309094a/schema)