---
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 — Platform-specific customer identifier. If not provided, one will be generated by the system.
    - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity. This determines the regulatory jurisdiction and KYC requirements for the customer. Required if the customer will use currencies with different KYC requirements across regions. A customer with accounts in multiple regions should be registered as separate customers. This field is immutable after creation.
    - `currencies` string[] — List of currency codes the customer will use (ISO 4217 for fiat, e.g. "USD", "EUR"; tickers for crypto, e.g. "BTC", "USDC"). Required if the customer will use more than one sending currency, since the correct currencies cannot always be inferred. If not provided, currencies will be inferred from the customer's region. Some currency combinations may require separate customers — if so, the request will be rejected with details.
    - `email` string, email — Email address for the customer.
    - `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
    - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYC status of a customer
    - `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 — Platform-specific customer identifier. If not provided, one will be generated by the system.
    - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity. This determines the regulatory jurisdiction and KYC requirements for the customer. Required if the customer will use currencies with different KYC requirements across regions. A customer with accounts in multiple regions should be registered as separate customers. This field is immutable after creation.
    - `currencies` string[] — List of currency codes the customer will use (ISO 4217 for fiat, e.g. "USD", "EUR"; tickers for crypto, e.g. "BTC", "USDC"). Required if the customer will use more than one sending currency, since the correct currencies cannot always be inferred. If not provided, currencies will be inferred from the customer's region. Some currency combinations may require separate customers — if so, the request will be rejected with details.
    - `email` string, email — Email address for the customer.
    - `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
    - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYB status of a business customer
    - `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
      - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name
      - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2)
      - `registrationNumber` string — Business registration number
      - `incorporatedOn` string, date, required — Date of incorporation in ISO 8601 format (YYYY-MM-DD)
      - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'OTHER' — Legal entity type of the business
      - `taxId` string, required — Tax identification number
      - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2)
      - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business
      - `purposeOfAccount` 'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER' — The intended purpose for using the Grid account
      - `sourceOfFunds` string — The primary source of funds for the business
      - `expectedMonthlyTransactionCount` 'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000' — Expected number of transactions per month
      - `expectedMonthlyTransactionVolume` 'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M' — Expected total transaction volume per month in USD equivalent
      - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2)

## Response `201`

Customer created successfully

- union
  - IndividualCustomer
    - `id` string — System-generated unique identifier
    - `platformCustomerId` string, required — Platform-specific customer identifier
    - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
    - `currencies` string[] — List of currency codes enabled for this customer.
    - `email` string, email — Email address for the 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
    - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYC status of a customer
    - `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
    - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
    - `currencies` string[] — List of currency codes enabled for this customer.
    - `email` string, email — Email address for the 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
    - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYB status of a business customer
    - `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 — Business information returned on a customer. `taxId` and `incorporatedOn` are required on creation but may be absent on legacy customers that pre-date the requirement, so both are optional in responses.
      - `legalName` string, required — Legal name of the business
      - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name
      - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2)
      - `registrationNumber` string — Business registration number
      - `incorporatedOn` string, date — Date of incorporation in ISO 8601 format (YYYY-MM-DD)
      - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'OTHER' — Legal entity type of the business
      - `taxId` string — Tax identification number
      - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2)
      - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business
      - `purposeOfAccount` 'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER' — The intended purpose for using the Grid account
      - `sourceOfFunds` string — The primary source of funds for the business
      - `expectedMonthlyTransactionCount` 'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000' — Expected number of transactions per month
      - `expectedMonthlyTransactionVolume` 'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M' — Expected total transaction volume per month in USD equivalent
      - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2)
    - `beneficialOwners` BeneficialOwner[]
      - `id` string, required — Unique identifier for this beneficial owner
      - `customerId` string, required — The ID of the business customer this beneficial owner is associated with
      - `roles` BeneficialOwnerRole[], required — Roles of this person within the business
      - `ownershipPercentage` integer, required — Percentage of ownership in the business (0-100)
      - `personalInfo` BeneficialOwnerPersonalInfo, required
        - `firstName` string, required — First name of the individual
        - `middleName` string — Middle name of the individual
        - `lastName` string, required — Last name of the individual
        - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
        - `nationality` string, required — Country of nationality (ISO 3166-1 alpha-2)
        - `email` string, email — Email address of the individual
        - `phoneNumber` string — Phone number in E.164 format
        - `address` Address, required
          - `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)
        - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID', required — Type of tax identification
        - `identifier` string, required — The identification number or value
        - `countryOfIssuance` string — Country that issued the identification (ISO 3166-1 alpha-2)
      - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED', required — The current KYC status of a customer
      - `createdAt` string, date-time, required — When this beneficial owner was created
      - `updatedAt` string, date-time — When this beneficial owner was last updated

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `405` — Method not allowed. Returned (as JSON, not HTML) when the request uses an HTTP method that is not supported on this path.
- `409` — Conflict. `UMA_ADDRESS_EXISTS` when the requested UMA address is already taken; `CONFLICT` when `platformCustomerId` collides with an existing active customer on the same platform.
- `500` — Internal service error
- `501` — Not implemented

## Changes

- **2026-05-28** `d0bce562bffd` — 2 breaking, 8 warning, 1 info
  - the request property `oneOf[subschema #2: Business Customer Create Request]/allOf[subschema #3]/businessInfo/incorporatedOn` became required
  - the request property `oneOf[subschema #2: Business Customer Create Request]/allOf[subschema #3]/businessInfo/taxId` became required
  - added the new `CONFLICT` enum value to the `code` response property for the response status `409`
  - added the new `EMAIL_OTP_CREDENTIAL_SET_CHANGED` enum value to the `code` response property for the response status `409`
  - …7 more
- **2026-04-27** `5b8a8161eeb3` — 12 warning, 63 info
  - removed the request property `oneOf[subschema #2: Business Customer Create Request]/allOf[#/components/schemas/BusinessCustomerFields]/beneficialOwners`
  - removed the optional property `oneOf[subschema #1: Individual Customer]/allOf[#/components/schemas/Customer]/kycStatus` from the response with the `201` status
  - removed the optional property `oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/BusinessCustomerFields]/beneficialOwners` from the response with the `201` status
  - removed the optional property `oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/Customer]/kycStatus` from the response with the `201` status
  - …71 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/d0bce562bffd/schema)