Swipelux

Create business customer

Create business customers with complete KYB information

KYB Endpoint: This endpoint creates business customers with complete KYB (Know Your Business) information required for compliance and verification.

Overview

The /v1/customers/business endpoint creates a business customer with comprehensive KYB data including:

  • Personal Information: Representative details (name, birth date, email, phone)
  • Identity Section: Business entity information and registration details
  • Details Section: Business type, description, and contact information
  • Address Section: Physical business address
  • Source of Funds: Financial information and transaction volume
  • Activity Section: Business operations and risk assessment

Interactive Request Builder

Click on any value to edit it. Copy the JSON or cURL command to use in your application.

Business Customer Creation Request

{
// Personal Information
"firstName":"John",
"lastName":"Smith",
"email":"john@acmecorp.com",
// Business Identity
"jurisdiction":"US",
"entityType":"LLC",
"entityName":"Acme Corporation LLC",
// Business Details
"businessDescription":"We provide software development and consulting services for enterprise clients worldwide",
"businessType":"Technology",
// Business Address
"addressCountry":"US",
"streetAddress":"123 Market Street",
"city":"San Francisco",
"state":"CA",
"zip":"94105",
// Financial Information
"sourceOfFunds":"Business Revenue",
"expectedMonthlyVolumeUsd":50000,
"purposeOfFunds":"Business Operations",
"flowOfFundsDescription":"Client payments received via bank transfer, used for operational expenses and vendor payments",
// Compliance
"sanctionedCountryOperations":false,
"highRiskActivities": []
}
Business KYB Customer$50,000/mo

Acme Corporation LLC • Technology • San Francisco, CA

Request Body

Personal Information (Representative)

firstName (required)

Type: string

Description: First name of the business representative

Example: "John"

middleName (optional)

Type: string | null

Description: Middle name of the business representative

Example: "Michael"

lastName (required)

Type: string

Description: Last name of the business representative

Example: "Smith"

birthDate (optional)

Type: string | null

Format: ISO 8601 date (YYYY-MM-DD)

Description: Birth date of the business representative

Example: "1985-03-15"

email (required)

Type: string

Format: Valid email address

Description: Email address of the business representative

Example: "john@acmecorp.com"

phone (optional)

Type: string | null

Description: Phone number of the business representative

Example: "+14155551234"

Identity Section

jurisdiction (required)

Type: string

Description: Country of jurisdiction where the business is registered

Example: "US", "UK", "SG"

Validation: Minimum 2 characters (country code)

entityType (required)

Type: string

Description: Type of business entity

Example: "LLC", "Corporation", "Partnership", "Sole Proprietorship"

entityTypeDescription (optional)

Type: string | null

Description: Custom description when entityType is "Other"

Example: "Non-Profit Organization"

entityName (required)

Type: string

Description: Legal name of the business entity

Example: "Acme Corporation LLC"

tradeName (optional)

Type: string | null

Description: Business trade name or DBA (Doing Business As)

Example: "Acme Tech"

registrationNumber (optional)

Type: string | null

Description: Business registration number

Example: "123456789"

incorporationDate (optional)

Type: string | null

Format: ISO 8601 date (YYYY-MM-DD)

Description: Date when the business was incorporated

Example: "2020-01-15"

taxNumber (optional)

Type: string | null

Description: Tax identification number (EIN, VAT, etc.)

Example: "12-3456789"

Details Section

businessDescription (required)

Type: string

Description: Detailed description of business activities

Validation: Minimum 10 characters

Example: "We provide software development and consulting services for enterprise clients worldwide"

businessType (required)

Type: string

Description: Type or category of business

Example: "Technology", "Retail", "Finance", "Healthcare"

businessTypeDescription (optional)

Type: string | null

Description: Custom description when businessType is "Other"

Example: "Blockchain Technology Services"

websites (optional)

Type: string[] | null

Description: Array of business website URLs

Validation: Each URL must be valid

Example: ["https://acmecorp.com", "https://acmeshop.com"]

phoneNumber (optional)

Type: string | null

Description: Business phone number

Example: "+14155551234"

Address Section

addressCountry (required)

Type: string

Description: Country where the business is located

Example: "US", "UK", "SG"

Validation: Minimum 2 characters (country code)

streetAddress (required)

Type: string

Description: Street address of the business

Example: "123 Market Street"

addressLine2 (optional)

Type: string | null

Description: Additional address information (suite, floor, etc.)

Example: "Suite 500"

city (required)

Type: string

Description: City name

Example: "San Francisco"

state (optional)

Type: string | null

Description: State or province

Example: "CA", "California"

zip (required)

Type: string

Description: ZIP or postal code

Example: "94105"

Source of Funds Section

sourceOfFunds (required)

Type: string

Description: Primary source of business funds

Example: "Business Revenue", "Investment", "Loan", "Third Party Funds"

sourceOfFundDescription (optional)

Type: string | null

Description: Custom description when sourceOfFunds is "Other" or "Third Party Funds"

Example: "Venture capital funding from Series A"

expectedMonthlyVolumeUsd (required)

Type: number

Description: Expected monthly transaction volume in USD

Validation: Must be a positive number (>= 0)

Example: 50000

purposeOfFunds (required)

Type: string

Description: Primary purpose for using the funds

Example: "Business Operations", "Payroll", "Vendor Payments"

purposeOfFundsDescription (optional)

Type: string | null

Description: Custom description when purposeOfFunds is "Other"

Example: "International supplier payments for raw materials"

flowOfFundsDescription (required)

Type: string

Description: Detailed description of how funds flow through the business

Validation: Minimum 10 characters

Example: "Client payments received via bank transfer, used for operational expenses and vendor payments"

Activity Section

sanctionedCountryOperations (required)

Type: boolean

Description: Indicates whether the business operates in sanctioned countries

Example: false

highRiskActivities (required)

Type: string[]

Description: Array of high-risk activities the business engages in (can be empty)

Example: [] or ["Cryptocurrency Trading", "Money Transfer"]

Response

Success Response (200 OK)

Type: Business Customer Object

The response includes all submitted data plus system-generated fields:

  • id: Unique business customer ID (e.g., "bc_abc123def456")
  • customerId: Associated customer ID (e.g., "cus_xyz789")
  • createdAt: Timestamp when the business customer was created
  • updatedAt: Timestamp of the last update

All request fields are returned in the response, with date fields formatted as ISO strings.

Error Responses

409 Conflict

Scenario: A customer with the same email or phone already exists

Response:

{
  "message": "A customer with this email already exists"
}

Response:

{
  "message": "A customer with this phone number already exists"
}

400 Bad Request

Scenario: Invalid request data or validation errors

Response:

{
  "message": "Validation error: businessDescription must be at least 10 characters"
}

401 Unauthorized

Scenario: Missing or invalid API key

Response:

{
  "message": "Unauthorized"
}

500 Internal Server Error

Scenario: Server error during customer creation

Response:

{
  "message": "Failed to create business customer: [error details]"
}

Use Cases

WhenWhatBetter For
B2B onboardingCreate business customers with full KYBPlatforms requiring business verification
Compliance requirementsCollect comprehensive business informationHigh-value transactions and regulated industries
Business verificationSubmit detailed business and representative dataKYB/AML compliance and risk assessment
Corporate walletsCreate business entities for crypto operationsEnterprise crypto payment solutions

Validation Rules

Required Fields

The following fields are required and must be provided:

  • firstName
  • lastName
  • email (must be valid email format)
  • jurisdiction (minimum 2 characters)
  • entityType
  • entityName
  • businessDescription (minimum 10 characters)
  • businessType
  • addressCountry (minimum 2 characters)
  • streetAddress
  • city
  • zip
  • sourceOfFunds
  • expectedMonthlyVolumeUsd (must be >= 0)
  • purposeOfFunds
  • flowOfFundsDescription (minimum 10 characters)
  • sanctionedCountryOperations (boolean)
  • highRiskActivities (array, can be empty)

Optional Fields

All other fields are optional and can be omitted or set to null.

Date Format

Date fields must use ISO 8601 format (YYYY-MM-DD):

  • birthDate
  • incorporationDate

URL Format

Website URLs must be valid URLs:

  • websites (array of URLs)

Best Practices

  1. Provide Complete Information: While some fields are optional, providing complete information improves verification success rates

  2. Accurate Business Description: The businessDescription and flowOfFundsDescription should be detailed and accurate to avoid verification delays

  3. Valid Contact Information: Ensure email and phone numbers are valid and belong to the business representative

  4. Country Codes: Use standard 2-letter (ISO 3166-1 alpha-2) or 3-letter (ISO 3166-1 alpha-3) country codes

  5. Transaction Volume: Be realistic with expectedMonthlyVolumeUsd - significant deviations may trigger additional verification

  6. High-Risk Activities: Accurately disclose any high-risk activities to avoid compliance issues later

  7. Sanctioned Countries: Be truthful about sanctionedCountryOperations - false information can result in account suspension