--- title: "Create a Customer" method: POST path: "/v2/customer" --- # Create a Customer `POST /v2/customer` Create a new customer. ## Request body - union - object - `type` 'individual', required - `email` string, email, required — The customer email address - `phone` string, required — The customer phone number in E.164 format - `address` object, required — The customer's address. - `line1` string, required — The first line of the street address - `line2` string — The second line of the street address (apartment, suite, etc.) - `city` string, required — The city name - `state` string — The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. - `postalCode` string — The postal or ZIP code. Required for countries that use postal codes - `country` string, required — The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). - `firstName` string — The customer's legal first name. - `lastName` string — The customer's legal last name. - `middleName` string — The customer's legal middle name. - `dateOfBirth` string — The date string in YYYY-MM-DD format - `personalInformation` object — 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. - `taxIdentificationNumber` string, required — The tax identification number. Required when providing tax identification information. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "123-45-6789"). - `taxIdentificationNumberType` string, required — 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. - `taxIdentificationNumberCountry` string, required — 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). - `taxIdentificationNumberDescription` string — Description of the tax identification number. Required when type is `other` - `accountPurpose` 'personal_or_living_expenses' | 'payments_to_friends_or_family_abroad' | 'receive_salary' | 'receive_payment_for_freelancing' | 'protect_wealth' | 'purchase_goods_and_services' | 'charitable_donations' | 'ecommerce_retail_payments' | 'investment_purposes' | 'operating_a_company' — The purpose of the account. Required for EEA-resident individuals. - `gender` 'male' | 'female' | 'other' — The gender of the customer. Required by some verification providers. - `countryOfBirth` string — The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). - `nationality` string — The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). - `occupationSocCode` string — The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. - `residencyCountry` string — The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). - `sourceOfFunds` 'salary' | 'business_income' | 'investment_returns' | 'inheritance' | 'gift' | 'savings' | 'other' — The customer's primary source of funds. Required by some verification providers. - `meta` object — Additional metadata associated with the customer - object - `type` 'business', required — The customer type. - `email` string, email, required — The business customer's email address. - `phone` string, required — The business customer's phone number in E.164 format. - `addresses` object[], required — The business customer's addresses which includes a registered address and an operating address. - `line1` string, required — The first line of the street address - `line2` string — The second line of the street address (apartment, suite, etc.) - `city` string, required — The city name - `state` string — The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. - `postalCode` string — The postal or ZIP code. Required for countries that use postal codes - `country` string, required — The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). - `type` 'operating' | 'registered', required - `businessInformation` object, required — Business information including identification number and all other relevant information to onboard the business customer. See [Business Verification Criteria](/concepts/onboarding/verification-profile). - `legalName` string, required — The business legal name. - `tradeName` string, required — The business trade name. - `entityType` 'cooperative' | 'corporation' | 'llc' | 'partnership' | 'sole_proprietorship' | 'trust' | 'other', required — The business entity type. - `entityTypeDescription` string — The business entity type description. This is required when entityType is "other". - `description` string, required — The business description. - `naicsCode` string, required — The business NAICS code. Please refer to NAICS codes for the list of valid codes. - `website` string, uri — The business website URL. Optional - if omitted, a document with documentType `proof_of_nature_of_business_document` must be uploaded instead to satisfy verification. - `incorporatedOn` string, required — The date string in YYYY-MM-DD format - `identificationNumberType` string, required — The business identification number type. Please refer to [identification number types](/concepts/onboarding/verification-profile) for the list of valid types. - `identificationNumber` string, required — The business tax or primary identification number (e.g. EIN). Distinct from `registrationNumber`. Only alphanumeric characters (letters and numbers) are accepted - omit separators such as dashes or spaces (e.g. send "123456789", not "12-3456789"). - `registrationNumber` string — Company registration number (state registry, Companies House, etc.), separate from the tax identifier in `identificationNumber`. - `identificationNumberDescription` string — The business identification number description. This is required when identificationNumberType is "other". - `estimatedAnnualRevenueInUsd` '0_99999' | '100000_999999' | '1000000_9999999' | '10000000_49999999' | '50000000_249999999' | '250000000_plus', required — 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. - `totalAssetsUsd` string — Total business assets in USD as a decimal string (e.g. "2500000.00"). When this value is at or above the audited-financials threshold, `hasAuditedFinancialStatementsAttested` must be true. - `hasAuditedFinancialStatementsAttested` boolean — Must be true when `totalAssetsUsd` is at or above the audited-financials threshold (PD-16), confirming readiness to supply audited financial statements during verification. - `regulatoryAuthorityCountry` string — ISO-3166 alpha-3 country of the primary regulatory authority. Required together with `regulatoryAuthorityName` and `licenseNumber` when `regulatedActivities` includes `money_services`. - `regulatoryAuthorityName` string — Name of the primary regulatory authority. Required together with the other regulator fields when `regulatedActivities` includes `money_services`. - `licenseNumber` string — License or registration number issued by the regulatory authority. Required together with the other regulator fields when `regulatedActivities` includes `money_services`. - `expectedMonthlyPaymentsInUsd` string, required — 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. - `accountPurpose` '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', required — The business account purpose - `accountPurposeDescription` string — The business account purpose description. This is required when accountPurpose is "other". - `primarySourceOfFunds` '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', required — The business primary source of funds - `primarySourceOfFundsDescription` string, required — The business primary source of funds description. - `isDao` boolean, required — Whether the business is a decentralized autonomous organization (DAO). - `regulatedActivities` string[], required — The business regulated activities. - `regulatedActivitiesDescription` string — The business regulated activities description. This is required when regulatedActivities contains any value other than "none_of_the_above". - `participatesInRegulatedFinancialActivity` boolean, required - `regulatedFinancialActivityDescription` string — The business regulated financial activity description. This is required when participatesInRegulatedFinancialActivity is true. - `moneyServicesDescription` string — The business money services description. This is required when regulatedActivities contains "money_services". - `complianceScreeningExplanation` string — The business compliance screening explanation. This is required when regulatedActivities contains "money_services". - `operatesInProhibitedCountries` boolean, required — Whether the business operates in prohibited countries. - `meta` object — Additional metadata associated with the customer ## Response `201` - union - object — Response containing information about an individual customer. - `id` string, required — Customer ID - `email` string — Customer email address - `phone` string — Customer phone number - `verificationProfiles` object[], required — 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. - `name` 'kyc_profile_a' | 'kyb_profile_a' | 'ubo_kyc_profile_a' | 'kyc_profile_b' | 'kyb_profile_b' | 'kyb_profile_c' | 'kyc_profile_c' | 'ubo_kyc_profile_c', required — The name of the verification profile. - `status` 'incomplete' | 'pending' | 'approved' | 'rejected' | 'resubmission_required', required — The status of the verification profile. - `criteria` object — The criteria for the verification profile. - `complete` string[], required — Completed fields. - `pending` string[], required — Pending fields. These fields are currently being verified. - `required` string[], required — Required fields. These fields are required to be completed before the verification profile can be approved. - `errors` object[], required — The errors that occurred while verifying the fields. - `name` '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' | 'registration_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' | 'incorporation_articles_document' | 'shareholder_registry_document' | 'proof_of_nature_of_business_document' | 'proof_of_address_document' | 'liveness_report_document' | 'ownership_percentage' | 'is_control_person' | 'is_signer' | 'relationship_established_at' | 'title' | 'sex' | 'country_of_birth' | 'nationality' | 'middle_name' | 'occupation_soc_code' | 'w8_ben_document' | 'w9_document' | 'w8_ben_e_document' | 'corporate_resolution_document' | 'source_of_funds_document' | 'financial_statements_document' | 'bank_statement_document' | 'regulated_activity_document' | 'flow_of_funds_document' | 'kyc_b_approval' | 'kyb_b_approval', required - `detail` string - `meta` object - `tosStatus` 'incomplete' | 'pending' | 'approved', required — Customer Terms of Service acceptance status (incomplete | pending | approved). - `createdAt` string, required — ISO 8601 formatted customer creation timestamp - `updatedAt` string, required — ISO 8601 formatted customer update timestamp - `type` 'individual', required — Customer type - `firstName` string — Customer first name (individual customers only) - `lastName` string — Customer last name (individual customers only) - `dateOfBirth` string — The customer's date of birth in YYYY-MM-DD format (individual customers only). - `personalInformation` object — Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy. - `taxIdentificationNumberType` string — 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. - `taxIdentificationNumberCountry` string — 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). - `taxIdentificationNumberDescription` string — Description of the tax identification number. Required when type is `other` - `accountPurpose` 'personal_or_living_expenses' | 'payments_to_friends_or_family_abroad' | 'receive_salary' | 'receive_payment_for_freelancing' | 'protect_wealth' | 'purchase_goods_and_services' | 'charitable_donations' | 'ecommerce_retail_payments' | 'investment_purposes' | 'operating_a_company' — The purpose of the account. Required for EEA-resident individuals. - `gender` 'male' | 'female' | 'other' — The gender of the customer. Required by some verification providers. - `countryOfBirth` string — The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). - `nationality` string — The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). - `middleName` string — The customer's middle name. Required for some verification flows. - `occupationSocCode` string — The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. - `residencyCountry` string — The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). - `sourceOfFunds` 'salary' | 'business_income' | 'investment_returns' | 'inheritance' | 'gift' | 'savings' | 'other' — The customer's primary source of funds. Required by some verification providers. - object — Response containing information about a business customer. - `id` string, required — Customer ID - `email` string — Customer email address - `phone` string — Customer phone number - `verificationProfiles` object[], required — 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. - `name` 'kyc_profile_a' | 'kyb_profile_a' | 'ubo_kyc_profile_a' | 'kyc_profile_b' | 'kyb_profile_b' | 'kyb_profile_c' | 'kyc_profile_c' | 'ubo_kyc_profile_c', required — The name of the verification profile. - `status` 'incomplete' | 'pending' | 'approved' | 'rejected' | 'resubmission_required', required — The status of the verification profile. - `criteria` object — The criteria for the verification profile. - `complete` string[], required — Completed fields. - `pending` string[], required — Pending fields. These fields are currently being verified. - `required` string[], required — Required fields. These fields are required to be completed before the verification profile can be approved. - `errors` object[], required — The errors that occurred while verifying the fields. - `name` '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' | 'registration_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' | 'incorporation_articles_document' | 'shareholder_registry_document' | 'proof_of_nature_of_business_document' | 'proof_of_address_document' | 'liveness_report_document' | 'ownership_percentage' | 'is_control_person' | 'is_signer' | 'relationship_established_at' | 'title' | 'sex' | 'country_of_birth' | 'nationality' | 'middle_name' | 'occupation_soc_code' | 'w8_ben_document' | 'w9_document' | 'w8_ben_e_document' | 'corporate_resolution_document' | 'source_of_funds_document' | 'financial_statements_document' | 'bank_statement_document' | 'regulated_activity_document' | 'flow_of_funds_document' | 'kyc_b_approval' | 'kyb_b_approval', required - `detail` string - `meta` object - `tosStatus` 'incomplete' | 'pending' | 'approved', required — Customer Terms of Service acceptance status (incomplete | pending | approved). - `createdAt` string, required — ISO 8601 formatted customer creation timestamp - `updatedAt` string, required — ISO 8601 formatted customer update timestamp - `type` 'business', required — Customer type - `businessLegalName` string — Customer business legal name (business customers only) - `businessTradeName` string — Customer business trade name (business customers only) ## Other responses - `400` — Bad Request - `404` — Not Found - `422` — Unprocessable Entity - Validation Error --- [API](https://skmtc.net/spherepay/apis/docs-spherepay-co.md) · [All operations](https://skmtc.net/spherepay/apis/docs-spherepay-co/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/spherepay/docs-spherepay-co/versions/4f3f5484aed3/schema)