> ## Documentation Index > Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt > Use this file to discover all available pages before exploring further. # Create an Individual or Business Customer > Create a new customer. Before you can initiate any transfer, you must create a customer record in SpherePay. This endpoint registers either an individual or a business customer and returns a customer object with a unique ID and a `verificationProfiles` array that tracks KYC/KYB completion status. You must specify `type` upfront — it cannot be changed after creation. ## OpenAPI ````yaml openapi/spherepay.yaml POST /v2/customer openapi: 3.0.0 info: title: '' description: '' version: 1.0.0 contact: {} servers: - url: https://api.spherepay.co description: Production security: - bearer: [] tags: [] paths: /v2/customer: post: summary: Create a Customer description: Create a new customer. parameters: [] requestBody: required: true content: application/json: schema: oneOf: - title: Individual Customer Create type: object properties: type: type: string enum: - individual email: description: The customer email address example: jane.smith@example.com type: string format: email maxLength: 254 phone: description: The customer phone number in E.164 format example: '+14155550123' type: string pattern: ^\+(?:[0-9]){6,14}[0-9]$ address: description: The customer's address. type: object properties: line1: description: The first line of the street address example: 233 South Wacker Drive type: string minLength: 1 maxLength: 255 line2: description: >- The second line of the street address (apartment, suite, etc.) example: Suite 4700 type: string maxLength: 255 city: description: The city name example: Chicago type: string minLength: 1 maxLength: 255 state: description: >- The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string postalCode: description: >- The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string country: description: >- The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string required: - line1 - city - country personalInformation: description: >- Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. type: object properties: taxIdentificationNumber: description: >- The tax identification number. Required when providing tax identification information example: '123456789' type: string minLength: 1 taxIdentificationNumberType: description: >- The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn type: string minLength: 1 taxIdentificationNumberCountry: description: >- The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string minLength: 1 taxIdentificationNumberDescription: description: >- Description of the tax identification number. Required when type is `other` type: string required: - taxIdentificationNumber - taxIdentificationNumberType - taxIdentificationNumberCountry meta: description: Additional metadata associated with the customer type: object additionalProperties: type: string required: - type - email - phone - address - title: Business Customer Create type: object properties: type: description: The customer type. example: business type: string enum: - business email: description: The business customer's email address. example: contact@acmecorp.example.com type: string format: email maxLength: 254 phone: description: The business customer's phone number in E.164 format. example: '+14155551234' type: string pattern: ^\+(?:[0-9]){6,14}[0-9]$ addresses: description: >- The business customer's addresses which includes a registered address and an operating address. type: array minItems: 2 maxItems: 2 items: description: The business customer's address. example: type: registered country: USA line1: 123 Main Street line2: Suite 100 city: Chicago state: IL postalCode: '60601' type: object properties: line1: description: The first line of the street address example: 233 South Wacker Drive type: string minLength: 1 maxLength: 255 line2: description: >- The second line of the street address (apartment, suite, etc.) example: Suite 4700 type: string maxLength: 255 city: description: The city name example: Chicago type: string minLength: 1 maxLength: 255 state: description: >- The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string postalCode: description: >- The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string country: description: >- The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string type: type: string enum: - operating - registered required: - line1 - city - country - type businessInformation: description: >- Business information including identification number and all other relevant information to onboard the business customer. See [Business Verification Criteria](/concepts/onboarding/verification-profile). type: object properties: legalName: description: The business legal name. example: Acme Corporation Inc. type: string minLength: 1 tradeName: description: The business trade name. example: Acme Corp type: string minLength: 1 entityType: description: The business entity type. example: corporation type: string enum: - cooperative - corporation - llc - partnership - sole_proprietorship - trust - other entityTypeDescription: description: >- The business entity type description. This is required when entityType is "other". example: Limited Liability Partnership type: string minLength: 1 description: description: The business description. example: >- Acme Corporation provides enterprise software solutions for supply chain management and logistics optimization. type: string minLength: 1 maxLength: 1000 naicsCode: description: >- The business NAICS code. Please refer to NAICS codes for the list of valid codes. example: '511210' type: string minLength: 1 website: description: The business website URL. example: https://acmecorp.example.com type: string format: uri incorporatedOn: description: The date string in YYYY-MM-DD format example: '2026-01-01' type: string identificationNumberType: description: >- The business identification number type. Please refer to [identification number types](/concepts/onboarding/verification-profile) for the list of valid types. example: ein type: string minLength: 1 identificationNumber: description: The business identification number. example: 12-3456789 type: string minLength: 1 maxLength: 100 identificationNumberDescription: description: >- The business identification number description. This is required when identificationNumberType is "other". example: Social Security Number type: string minLength: 1 estimatedAnnualRevenueInUsd: description: >- The business estimated annual revenue in USD. Please refer to [estimated annual revenue in USD](/concepts/onboarding/verification-profile) for the list of valid ranges. example: '1000000_9999999' type: string enum: - 99999 - '100000_999999' - '1000000_9999999' - '10000000_49999999' - '50000000_249999999' - 250000000_plus expectedMonthlyPaymentsInUsd: description: >- The business expected monthly payments in USD. Please refer to [expected monthly payments in USD](/concepts/onboarding/verification-profile) for the list of valid ranges. example: '50000' type: string accountPurpose: description: The business account purpose example: investment_purposes type: string enum: - charitable_donations - ecommerce_retail_payments - investment_purposes - payments_to_friends_or_family_abroad - payroll - personal_or_living_expenses - protect_wealth - purchase_goods_and_services - receive_payments_for_goods_and_services - tax_optimization - third_party_money_transmission - treasury_management - other accountPurposeDescription: description: >- The business account purpose description. This is required when accountPurpose is "other". example: Business checking account type: string minLength: 1 primarySourceOfFunds: description: The business primary source of funds example: sales_of_goods_and_services type: string enum: - business_loans - grants - inter_company_funds - investment_proceeds - legal_settlement - owners_capital - pension_retirement - sale_of_assets - sales_of_goods_and_services - third_party_funds - treasury_reserves primarySourceOfFundsDescription: description: The business primary source of funds description. example: >- Revenue from software licensing and consulting services type: string minLength: 1 isDao: description: >- Whether the business is a decentralized autonomous organization (DAO). example: false type: boolean regulatedActivities: description: The business regulated activities. example: - none_of_the_above type: array minItems: 1 items: description: The business regulated activity example: money_services type: string enum: - adult_entertainment - gambling - hold_client_funds - investment_services - lending_banking - marijuana_or_related_services - money_services - >- operate_foreign_exchange_virtual_currencies_brokerage_otc - pharmaceuticals - precious_metals_precious_stones_jewelry - safe_deposit_box_rentals - third_party_payment_processing - nicotine_tobacco_or_related_services - weapons_firearms_and_explosives - none_of_the_above regulatedActivitiesDescription: description: >- The business regulated activities description. This is required when regulatedActivities contains any value other than "none_of_the_above". example: The business engages in money services type: string minLength: 1 participatesInRegulatedFinancialActivity: type: boolean regulatedFinancialActivityDescription: description: >- The business regulated financial activity description. This is required when participatesInRegulatedFinancialActivity is true. example: The business engages in money services type: string minLength: 1 moneyServicesDescription: description: >- The business money services description. This is required when regulatedActivities contains "money_services". example: The business engages in money services type: string minLength: 1 complianceScreeningExplanation: description: >- The business compliance screening explanation. This is required when regulatedActivities contains "money_services". example: >- The business complies with all applicable regulations type: string minLength: 1 operatesInProhibitedCountries: description: >- Whether the business operates in prohibited countries. example: false type: boolean required: - legalName - tradeName - entityType - description - naicsCode - website - incorporatedOn - identificationNumberType - identificationNumber - estimatedAnnualRevenueInUsd - expectedMonthlyPaymentsInUsd - accountPurpose - primarySourceOfFunds - primarySourceOfFundsDescription - isDao - regulatedActivities - participatesInRegulatedFinancialActivity - operatesInProhibitedCountries meta: description: Additional metadata associated with the customer type: object additionalProperties: type: string required: - type - email - phone - addresses - businessInformation example: type: individual email: jane.smith@example.com phone: '+14155550123' address: line1: 233 South Wacker Drive city: Chicago state: IL postalCode: '60606' country: USA personalInformation: firstName: Jane lastName: Smith dateOfBirth: '1990-04-15' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/AugmentedZodDto' example: id: customer_f31121c389624d3697cbf3ea8830b7a4 type: individual email: jane.smith@example.com phone: '+14155550123' firstName: Jane lastName: Smith verificationProfiles: - name: kyc_profile_a status: incomplete criteria: complete: - email_address - phone_number - residential_address - tax_identification_number pending: [] required: - identity_document - liveness_report_document errors: [] meta: {} createdAt: '2026-03-09T20:46:31.305Z' updatedAt: '2026-03-09T20:46:31.305Z' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Bad Request: summary: Bad Request value: status: 400 detail: Invalid request parameters code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Not Found: summary: Not Found value: status: 404 detail: Resource not found code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c '422': description: Unprocessable Entity - Validation Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Validation Error: summary: Validation Error value: status: 422 detail: Validation failed code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name components: schemas: AugmentedZodDto: oneOf: - title: Individual description: Response containing information about an individual customer. type: object properties: id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string email: description: Customer email address example: jane.smith@example.com type: string phone: description: Customer phone number example: '+14155550123' type: string verificationProfiles: description: >- Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - name: kyc_profile_a status: incomplete criteria: complete: - email_address - phone_number - residential_address - tax_identification_number pending: [] required: - identity_document - liveness_report_document errors: [] type: array items: type: object properties: name: description: The name of the verification profile. example: kyc_profile_a type: string enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c status: description: The status of the verification profile. example: incomplete type: string enum: - incomplete - pending - approved - rejected criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number pending: [] required: - identity_document - liveness_report_document errors: [] type: object properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number type: array items: type: string pending: description: >- Pending fields. These fields are currently being verified. example: [] type: array items: type: string required: description: >- Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document type: array items: type: string errors: description: The errors that occurred while verifying the fields. example: [] type: array items: type: object properties: name: oneOf: - type: string enum: - terms_of_service - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - >- participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - shareholder_registry_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - is_signer - relationship_established_at - title - type: string enum: - kyc_a_approval - kyb_a_approval - kyc_b_approval - kyb_b_approval - kyb_c_approval detail: type: string required: - name required: - complete - pending - required - errors required: - name - status meta: type: object additionalProperties: {} createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string type: description: Customer type example: individual type: string enum: - individual firstName: description: Customer first name (individual customers only) example: Jane type: string lastName: description: Customer last name (individual customers only) example: Smith type: string required: - id - verificationProfiles - createdAt - updatedAt - type - title: Business description: Response containing information about a business customer. type: object properties: id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string email: description: Customer email address example: jane.smith@example.com type: string phone: description: Customer phone number example: '+14155550123' type: string verificationProfiles: description: >- Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - name: kyc_profile_a status: incomplete criteria: complete: - email_address - phone_number - residential_address - tax_identification_number pending: [] required: - identity_document - liveness_report_document errors: [] type: array items: type: object properties: name: description: The name of the verification profile. example: kyc_profile_a type: string enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c status: description: The status of the verification profile. example: incomplete type: string enum: - incomplete - pending - approved - rejected criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number pending: [] required: - identity_document - liveness_report_document errors: [] type: object properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number type: array items: type: string pending: description: >- Pending fields. These fields are currently being verified. example: [] type: array items: type: string required: description: >- Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document type: array items: type: string errors: description: The errors that occurred while verifying the fields. example: [] type: array items: type: object properties: name: oneOf: - type: string enum: - terms_of_service - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - >- participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - shareholder_registry_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - is_signer - relationship_established_at - title - type: string enum: - kyc_a_approval - kyb_a_approval - kyc_b_approval - kyb_b_approval - kyb_c_approval detail: type: string required: - name required: - complete - pending - required - errors required: - name - status meta: type: object additionalProperties: {} createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string type: description: Customer type example: business type: string enum: - business businessLegalName: description: Customer business legal name (business customers only) example: Acme Corporation Inc. type: string businessTradeName: description: Customer business trade name (business customers only) example: Acme Corp type: string required: - id - verificationProfiles - createdAt - updatedAt - type ProblemDetailsDto: type: object properties: title: type: string status: type: integer detail: type: string code: type: string errors: type: array items: type: object properties: detail: type: string pointer: type: string parameter: type: string header: type: string required: - detail correlationId: type: string required: - status - detail securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````