Customers API 2025 Winter Release
Customers API is undergoing changes to support upcoming major launches including same name payouts, programmatic onboarding, and local payouts.
The Customers API schema has been updated in preparation for upcoming improvements to onboarding and payment capabilities. This change primarily affects developers who are using Customers API to pass customer information to Bridge. If you’re exclusively using KYC Links API, you are not required to take action.
The new schema provides you the ability to provide additional information and multiple supplemental documents at the time of onboarding to speed up approvals. In addition, the new schema will unblock future capabilities and features such as local FX/rails, same name payouts and automated compliance remediation.
❗Action Required: Update your Customers API integration to use the latest schema by March 5th. Certain required API field names and list of values have changed. Updating your integration to use the new field names and values is necessary to avoid service disruptions. Estimated effort for required changes is 0 to 2 days based on initial feedback.
FAQ
Is this new API schema released under a new version?
No, this new schema will remain under the existing /v0/customers path and developers can opt-into the new schema dynamically.
Note: This new schema will be enforced on March 5, 2025
How often should I expect breaking changes?
We recognize that breaking changes are disruptive for our developers and we aim to minimize their frequency. We do not anticipate any further Customers API breaking changes in the next six months.
We will continue to release opt-in improvements to the Customers API with the aim of unlocking new product capabilities and streamlining onboarding.
How can I utilize the new API schema?
Developers will be opted into the new API schema when at least one of the newly introduced fields is provided in the API request body. When any new field is detected, the entire request will be validated against the new schema.
Here is a list of new fields for reference:
Shared fields
identifying_information, documents, account_purpose, account_purpose_other, kyc_screen*, ofac_screen*
Individual fields
residential_address, transliterated_residential_address, completed_customer_safety_check_at, verified_selfie_at, nationality, employment_status, most_recent_occupation, acting_as_intermediary, expected_monthly_payments
Business fields
business_legal_name, transliterated_business_legal_name, business_trade_name, transliterated_business_trade_name, registered_address, transliterated_registered_address, physical_address, transliterated_physical_address, business_description, primary_website, other_websites, publicly_traded_listings, conducts_money_services, conducts_money_services_using_bridge, associated_persons, ownership_threshold, has_material_intermediary_ownership, regulated_activity, operates_in_prohibited_countries, high_risk_activities, estimated_annual_revenue_usd, expected_monthly_payments_usd, source_of_funds_description
To see the list of required fields, please refer to the API Reference.
How do I integrate with the new identifying_information attribute?
The identifying_information attribute will capture both tax identification numbers and other non tax related government issued id information.
For an individual based in Malawi (Mwi), if you want to pass us their tax identification number, you could reference this page, to see what type is acceptable for that country, and in the identifying_information array in the request body you would pass the following:
{
"identifying_information": [
{
"type": "tpin",
"issuing_country": "mwi",
"number": "xxxxxxx"
}
]
}
For that same individual, if you want to pass us their passport information as well, as a separate entry to the array in the code snippet above, you would specify it as:
{
"identifying_information": [
{
"type": "tpin",
"issuing_country": "mwi",
"number": "xxxxxxx"
},
{
"type": "passport",
"issuing_country": "mwi",
"number": "xxxxxxxxx",
"image_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAAAAAAAD...",
}
]
}
Note that for non tax identification documents, a minimum of image_front is required, and image_back is optional. These two fields are also welcome for tax identification documents as well.
In the event that you don't see the type specified for the document you want to provide, please submit other and provide a description.
Note: description is always required when other is selected as the type.
How do I integrate with the new documents attribute?
The documents attribute is meant to serve as a means of passing us whatever documents needed either on the initial API request or in response to RFIs (Request for Information) in response to manual reviews.
To provide Proof of Address for an individual or business, you can add the following documents to your API request:
{
"documents": [
{
"purposes": ["proof_of_address"],
"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAAAAAAAD...",
}
]
}
If a document serves multiple purposes, you can add those purposes into the purposes array while only specifying the file once.
The list of valid document purposes can be found here. In the event that you have a different document purpose that we do not officially support, please include other and provide a description.
Note: description is always required when other is included as the purposes array.
Individual (KYC) Changes
residential_address* address
Primary residential address.
transliterated_residential_address address
The individual's residential address transliterated into Latin characters.
Optional. Required if non-Latin residential_address was provided.
nationality string
Country of nationality.
Format: ISO 3166-1. Example: USA
source_of_funds string
The individual's primary source of funds.
Optional. Required for high risk customers.
Accepted Values:
company_funds, ecommerce_reseller, gambling_proceeds, gifts, government_benefits, inheritance, investments_loans, pension_retirement, salary, sale_of_assets_real_estate, savings, someone_elses_funds
Note: removed business_income and added company_funds andecommerce_reseller
account_purpose enum
The primary account purpose.
Accepted Values:
charitable_donations, ecommerce_retail_payments, investment_purposes, operating_a_company, other, payments_to_friends_or_family_abroad, personal_or_living_expenses, protect_wealth, purchase_goods_and_services, receive_payment_for_freelancing, receive_salary
Note: removed business_transactions and added ecommerce_retail_payments and investment_purposes
account_purpose_other string
A detailed description of the primary purpose.
Optional. Required if account_purpose includes other.
acting_as_intermediary boolean
The individual is acting as intermediary by moving funds on behalf of others.
Optional. Required for high risk customers.
employment_status enum
The employment status of the individual.
Optional. Required for high risk customers.
Accepted values:
employed, homemaker, retired, self_employed, student, unemployed
expected_monthly_payments_usd enum
The individual's expected monthly payments.
Optional. Required for high risk customers.
Accepted Values:
0_4999, 5000_9999, 10000_49999, 50000_plus
most_recent_occupation enum
The individual's most recent occupation represented as its Standard Occupational Classification (SOC) code. Reference this page for the full list of SOC codes we support.
Optional. Required for high risk customers.
completed_customer_safety_check_at date
The date when individual successfully passed customer safety check.
verified_selfie_at date
The date when individual's selfie was successfully verified.
identifying_information* identifying_information[]
The official identification details.
documents object
Additional documentation.
Note: This object will now be used to represent documents such as proof_of_address.
Object values:
purposes* enum[]
The relevant purpose(s) of the specified document. The list of valid document purposes can be found here.
file* enum
Base64 encoded string of the provided document.
description string
Relavent document description.
Required when other is included in the purposes.
Business (KYB) Changes
The following fields represent modifications to the API related to the business entity type.
business_legal_name* string
The official registered name of the business as documented with government authorities.
transliterated_business_legal_name string
The business's legal name transliterated into Latin characters.
Optional. Required if non-Latin legal name
business_trade_name* string
The trading name or DBA (Doing Business As) name under which the business operates publicly.
transliterated_business_trade_name string
The business's trade name transliterated into Latin characters.
Optional. Required if non-Latin legal name
registered_address* address
The official registered address of the business.
transliterated_registered_address address
The business's official registered address transliterated into Latin characters.
Optional. Required if non-Latin registered address
physical_address* address
The physical address for the primary place of business.
transliterated_physical_address address
The business's physical address transliterated into Latin characters.
Optional. Required if non-Latin registered address
primary_website string
The business's primary website/web presence.
Required if no nature_of_business` document is included with request
other_websites string[]
The business's other websites and social media handles.
identifying_information* identifying_information[]
The official identification details.
source_of_funds* enum
The business's primary source of funds.
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
Note: removed business_revenue, equity_funding and legal_settlement_tax_refund. Modified business_loans to now represent both business loans and external financing. `
source_of_funds_description string
A detailed description of the business's primary source of funds.
account_purpose* enum
The business's primary purpose for this account.
Acceptable values:
charitable_donations, ecommerce_retail_payments, investment_purposes, other, 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,
Note: removed business_transactions
account_purpose_other string
A detailed description of the primary purpose.
Optional. Required if account_purpose includes other.
has_material_intermediary_ownership* boolean
The business has at least one intermediate legal entity owner with 25% or more ownership.
estimated_annual_revenue_usd enum
The business's estimated annual revenue in US dollars.
Accepted Values:
0_99999, 100000_999999, 1000000_9999999,10000000_49999999 ,50000000_249999999,250000000_plus
expected_monthly_payments_usd integer
The business's expected monthly payments via this account in US dollars.
operates_in_prohibited_countries boolean
The business has customers or operations in Cuba, Iran, Myanmar, North Korea, and/or Syria.
high_risk_activities enum
The high risk activities that the business participates in.
Accepted values:
none_of_the_above, adult_entertainment, gambling, hold_client_funds, investment_services, lending_banking, marijuana_or_related_services, money_services, operate_foreign_exchange_virtual_currencies_brokerage_otc, safe_deposit_box_rentals, third_party_payment_processing, weapons_firearms_and_explosives, precious_metals_precious_stones_jewelry (new), nicotine_tobacco_or_related_services(new)
publicly_traded_listings object[]
The information of the business's primary public traded listing if applicable.
Object values:
market_identifier_code string
The 4-digit Market Identifier Code (MIC) (ISO 10383) for the venue where the business is publicly listed and traded.
stock_number string
The 12-digit International Securities Identification Number (ISIN) of the company without dashes (-).
ticker string
The ticker for the business's publicly traded listing.
regulated_activity object
The information of the business's regulated activity and licensing if applicable.
Object values:
regulated_activities_description string
A detailed description of the regulated activities the business is licensed to conduct.
primary_regulatory_authority_country* string
The country where the primary regulator of the business is located.
primary_regulatory_authority_name* string
The name of the primary regulatory authority that oversees the business's regulated activities.
license_number* string
The license number or registration number assigned by the business's primary regulator.
conducts_money_services boolean
The business offers money services, investment products, and/or other financial services.
conducts_money_services_using_bridge boolean
The business plans to conduct money services, investment products, and/or other financial services using its Bridge account.
Required if conducts_money_services is true.
compliance_screening_explanation string
A detailed description of the business's compliance and anti-money laundering controls and practices.
documents object
Additional documentation.
Note: This object will now be used to represent documents such as proof_of_address.
Object values:
purposes* enum[]
The relevant purpose(s) of the specified document. The list of valid document purposes can be found here.
file* enum
Base64 encoded string of the provided document.
description string
Relavent document description.
Required when other is included in the purposes.
ownership_threshold integer
The applicable beneficial ownership threshold for the submitted UBO information.
Valid values are between 5 to 25. Default value is 25.
associated_persons associated_person[]
The list of persons associated with the business (e.g. ultimate beneficial owners, control persons, directors).
Previously named ultimate_beneficial_owners.
Data Types
Below represents the customer data types mentioned above in more depth.
associated_person object
Represents a person associated with the business (e.g. ultimate beneficial owners, control persons, directors).
Note: associated_person's share all the same fields as individuals. Only the additional fields will be listed here.
Object values:
has_control boolean
Is a control person of the company, having significant responsibility to control, manage or influence the activities of the business entity. At least one control person must be specified.
is_director boolean
Is an appointed director or authorized manager of the company.
is_signer boolean
Able to authorize transactions on behalf of the business. At least one signer must be specified.
has_ownership boolean
Represents whether or not the person has ownership of the company.
relationship_established_at date
When the relationship was established between the business and the associated person.
Format: YYYY-MM-DD
title string
The title of this associated person at the company, e.g. CEO, CFO, etc.
Required if has_control is true.
ownership_percentage integer
The percentage of the company that this associated person owns.
identifying_information object
Official identification details.
Note: This object can represent any official Tax Identification Number such as an SSN for US citizens or Government provided ID document such as a drivers license.
Object values:
issuing_country* string
The country that issued the identity document and/or identification number.
type* enum
Type of identification being provided.
Reference this page for the full list of business tax identification number types grouped by country.
Reference this page for the full list of individual tax identification number types grouped by country.
number string
Identification number.
Required for tax_id and national_id types
expiration date
The date that the identification document expires.
Format: YYYY-MM-DD
image_front string
Base64 encoded string of the front side of the identification document.
Required for Government ID document types.
image_back string
Base64 encoded string of the back side of the identification document.
documents object
Additional documentation.
Note: This object will now be used to represent documents such as proof_of_address.
Object values:
purposes* enum[]
The relevant purpose(s) of the specified document. The list of valid document purposes can be found here.
file* enum
Base64 encoded string of the provided document.
description string
Relavent document description.
Required when other is included in the purposes.
Example Requests
Individuals and UBOs
Current Request Body (Sunset March 5, 2025)
The following JSON is an example payload that you would send to POST /v0/customers to create an individual customer object.
{
"type": "individual",
"first_name": "John",
"last_name": "Doe",
"email": "email@example.com",
"address": {
"street_line_1": "123 Main St",
"city": "New York City",
"state": "New York",
"postal_code": "10001",
"country": "USA"
},
"birth_date": "2007-01-01",
"tax_identification_number": "xxx-xx-xxxx",
"signed_agreement_id": "d536a227-06d3-4de1-acd3-8b5131730480",
"sof_eu_questionnaire": {
"employment_status": "employed",
"expected_monthly_payments": "5000_9999",
"acting_as_intermediary": "no",
"most_recent_occupation": "291291",
"primary_purpose": "purchase_goods_and_services",
"primary_purpose_other": null,
"source_of_funds": "salary"
},
"proof_of_address_document": "data:image/jpg;base64,..."
}
Updated 2025 Request Body
This is an example of how you would create that same individual customer with the new schema changes.
{
"type": "individual",
"first_name": "Frank",
"middle_name": "Legros",
"last_name": "Rogahn",
"birth_date": "1977-11-17",
"email": "example@example.example",
"residential_address": {
"street_line_1": "123 Main Street",
"street_line_2": "Suite 227",
"city": "San Francisco",
"subdivision": "CA",
"postal_code": "xxxxx",
"country": "USA"
},
"identifying_information": [
{
"type": "ssn",
"issuing_country": "US",
"number": "123456789",
"image_front": "data:image/jpg;base64,..."
},
{
"type": "drivers_license",
"issuing_country": "US",
"number": "J123456789",
"image_front": "data:image/jpg;base64,..."
}
],
"documents": [
{
"purposes": [
"proof_of_address"
],
"file": "data:image/jpg;base64,..."
}
],
"signed_agreement_id": "86b63e37-bf73-4011-bde9-104980ce3b02",
}
Businesses
Current Request Body (Sunset March 5, 2025)
The following JSON is an example payload that you would send to POST /v0/customers to create a business customer object.
{
"type": "business",
address: {
street_line_1: "123 Main St",
city: "New York City",
state: "New York",
postal_code: "10001",
country: "USA",
},
"business_type": "corporation",
"business_industry": "1153",
"compliance_screening_explanation": "A business",
"description": "A business",
"email": "team@business.co",
"formation_document": "data:image/jpg;base64,...",
"is_dao": false,
"is_high_risk": false,
"name": "My Business",
"ownership_document": "data:image/jpg;base64,...",
"proof_of_address_document": "data:image/jpg;base64,...",
"service_usage_description": "A business",
"signed_agreement_id": "7262662f-6622-46d1-9ac1-0e840d78598f",
"sof_eu_questionnaire": {
"estimated_annual_revenue_usd": "250000000_plus",
"expected_monthly_payments_usd": 101307,
"operates_in_prohibited_countries": "no",
"primary_purpose": "receive_payments_for_goods_and_services",
"primary_purpose_other": null,
"high_risk_activities": [
"none_of_the_above"
],
"source_of_funds": "business_loans",
"source_of_funds_description": "Minima aperiam cum aut.",
"transmits_customer_funds": "yes",
"transmits_customer_funds_description": "Ut similique dolores quo."
},
"statement_of_funds": "data:image/jpg;base64,...",
"tax_identification_number": "xxx-xx-xxxx",
"ultimate_beneficial_owners": [
{
"first_name": "John",
"middle_name": "Doe",
"last_name": "Smith",
"birth_date": "1990-01-01",
"email": "john.doe@gmail.com",
"phone": "1234567890",
"tax_identification_number": "123456789",
"address": {
"street_line_1": "1482 Brock Walk",
"street_line_2": "Suite 927",
"city": "Lake Shirley",
"state": null,
"postal_code": null,
"country": "BVT"
},
"has_ownership": true,
"has_control": true,
"is_signer": true,
"title": "CEO",
"relationship_established_at": "2015-01-01",
"gov_id_image_front": "data:image/jpg;base64,...",
"gov_id_image_back": "data:image/jpg;base64,...",
"proof_of_address_document": "data:image/jpg;base64,..."
}
],
"website": "http://google.com"
}
Updated 2025 Request Body
This is an example of how you would create that same business customer with the new schema changes.
{
"type": "business",
"business_legal_name": "ACME Inc",
"business_trade_name": "Theaters Inc",
"business_description": "Dolorum quasi sed nobis.",
"email": "jasper_mclaughlin@upton.example",
"business_type": "llc",
"registered_address": {
"street_line_1": "56410 Fritsch Square",
"street_line_2": "Apt. 759",
"city": "Okunevaberg",
"subdivision": "MA",
"postal_code": "35744-6371",
"country": "US"
},
"physical_address": {
"street_line_1": "56410 Fritsch Square",
"street_line_2": "Apt. 759",
"city": "Okunevaberg",
"subdivision": "MA",
"postal_code": "35744-6371",
"country": "US"
},
"business_industry": "111110",
"primary_website": "https://example.com/landing",
"is_dao": true,
"source_of_funds": "treasury_reserves",
"account_purpose": "ecommerce_retail_payments",
"associated_persons": [
{
"first_name": "Frank",
"middle_name": "Legros",
"last_name": "Rogahn",
"birth_date": "1977-11-17",
"email": "example@example.example",
"residential_address": {
"street_line_1": "123 Main Street",
"street_line_2": "Suite 227",
"city": "San Francisco",
"subdivision": "CA",
"postal_code": "xxxxx",
"country": "USA"
},
"has_ownership": false,
"has_control": true,
"is_signer": true,
"is_director": true,
"relationship_established_at": "2025-01-28",
"ownership_percentage": 100,
"identifying_information": [
{
"type": "ssn",
"issuing_country": "US",
"number": "123456789",
"image_front": "data:image/jpg;base64,..."
},
{
"type": "drivers_license",
"issuing_country": "US",
"number": "J123456789",
"image_front": ""data:image/jpg;base64,..."
}
],
"documents": []
}
],
"has_material_intermediary_ownership": true,
"identifying_information": [
{
"type": "ein",
"issuing_country": "us",
"number": "123456789"
}
],
"documents": [
{
"purposes": [
"proof_of_address",
"business_formation",
"ownership_information"
],
"file": "data:image/jpg;base64,..."
}
],
"signed_agreement_id": "86b63e37-bf73-4011-bde9-104980ce3b02",
}
Updated 6 days ago