Customers API

The Customers API enables you to directly pass the KYC information to Bridge. This endpoint enables you to control the UI and handle all of the back and forth with customers, regardless of whether they are individuals or businesses.

For US residents, we offer the option to create restricted customers who do not need to provide a government ID when using the Customers endpoint. However, these restricted customers are limited to transactions of $10,000 each, and a total of $100,000 over a 30-day period. To increase these limits, a hosted URL can be created through our KYC Links API. This allows the customer to further verify their identity with a government ID and increase their limits. On the other hand, international residents are required to provide a government ID at the time of creation and are automatically granted increased limits. All business customers are currently reviewed by the Bridge Compliance team before being allowed to transact.

After obtaining a signed_agreement_id (details here: Terms of Service), you can now use the Customers API to create customers as follows:

🚧

Warning

Starting November 18, 2024, the POST and PUT endpoints for /v0/customers/(:id) will require specific fields to be populated when its corresponding primary field contain any invalid character encodings.

Invalid Character Encodings
Invalid character encodings are defined as any character outside the printable ASCII \x20-\x7E and Latin-1 \xC0-\xD6\xD8-\xDF\xE0-\xF6\xF8-\xFFranges. The following transliterated fields must be provided if their primary counterpart field contain any such invalid characters.

Primary Field	Required Transliteration Field
name	transliterated_business_name
first_name	transliterated_first_name
middle_name	transliterated_middle_name
last_name	transliterated_last_name

Please ensure these fields are appropriately populated to avoid validation errors when submitting or updating customer records.

Example API Error

json

{
  "code": "invalid_parameters",
  "message": "Please resubmit the following parameters that are either missing or invalid",
  "source": {
    "location": "body",
    "key": {
      "transliterated_first_name": "must be specified when first_name contains any non basic latin or latin accented characters.contains any non basic latin or latin accented characters. (A-Z, a-z), numbers (0-9), and standard symbols."
    }
  }
}

Individual customer creation

Create Customer API

curl --location --request POST 'https://api.bridge.xyz/v0/customers' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \
--data-raw '{
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+12223334444",
  "address": {
    "street_line_1": "123 Washington St",
    "street_line_2": "Apt 2F",
    "city": "Chicago",
    "state": "IL",
    "postal_code": "10001",
    "country": "USA"
  },
  "signed_agreement_id": <signed_agreement_id from above>,
  "birth_date": "1989-09-09",
  "tax_identification_number": "111111111",
  "gov_id_country": "USA",
  "gov_id_image_front" <data-uri> (optional),
  "gov_id_image_back" <data-uri> (optional),
  "proof_of_address_document" <data-uri> (optional)
}'

curl --location --request POST 'https://api.bridge.xyz/v0/customers' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \
--data-raw '{
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+12223334444",
  "address": {
    "street_line_1": "Juncal 2091",
    "street_line_2": "B1648",
    "city": "Tigre",
    "state": "B", // ISO 3166-2 Subdivision code without the country prefix
    "postal_code": "B7000",
    "country": "ARG" // ISO 3166-1 alpha3 Country code
  },
  "signed_agreement_id": <signed_agreement_id from above>,
  "birth_date": "1989-09-09",
  "tax_identification_number": "111111111",
  "gov_id_country": "USA",
  "gov_id_image_front" <data-uri>,
  "gov_id_image_back" <data-uri> (optional),
  "proof_of_address_document" <data-uri> (optional)
}'

curl --location --request POST 'https://api.bridge.xyz/v0/customers' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \
--data-raw '{
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+12223334444",
  "address": {
    "street_line_1": "80 Queens Road",
    "street_line_2": "Suite 3B",
    "city": "Manchester",
    "state": "MAN", // ISO 3166-2 Subdivision code without the country prefix
    "postal_code": "M1 1AE",
    "country": "GBR" // ISO 3166-1 alpha3 Country code
  },
  "signed_agreement_id": <signed_agreement_id from above>,
  "birth_date": "1989-09-09",
  "tax_identification_number": "111111111",
  "gov_id_country": "USA",
  "gov_id_image_front" <data-uri>,
  "gov_id_image_back" <data-uri> (optional),
  "proof_of_address_document" <data-uri> 
 }'

Note: proof_of_address_document is required for individual customers from European Economic Area (EEA), or customers who wish to use SEPA/Euro services offered by Bridge. Please refer to SEPA/Euro Transactions page for details.

For international customers, submit an ISO 3166-1 alpha-3 country code and an ISO 3166-2 subdivision code (minus the country prefix) for the state. So for the above example, GB-MAN is the code, but just MAN is submitted.

Business customer creation

curl --location --request POST 'https://api.bridge.xyz/v0/customers' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \
--data-raw '{
  "type": "business",
  "name": "Wonka Industries",
  "description": "You have never had chocolate like this!",
  "business_type": "llc",
  "email": "team@wonka_industries.com",
  "website": "https://wonka_industries.eu",
  "tax_identification_number": "222222222",
  "statement_of_funds": "<data-uri>",
  "is_dao": false,
  "transmits_customer_funds": true,
  "compliance_screening_explanation": "We perform KYB/KYC for any customer we transmit funds for and have standard AML measures in place!",
  "ultimate_beneficial_owners": [{
    "first_name": "Willard",
    "last_name": "Wonka",
    "birth_date": "1942-04-01",
    "email": "willy@wonka_industries.com",
    "phone": "+12223334444",
    "tax_identification_number": "111111111",
    "address": {
      "street_line_1": "123 Chocolate Way",
      "street_line_2": "Apt 1",
      "city": "Itasca",
      "state": "IL",
      "postal_code": "60143",
      "country": "USA"
    },
    "id_front_photo": "<data-uri>",
    "id_back_photo": "<data-uri>",
    "proof_of_address_document": "<data-uri>"
  }],
  "address": {
    "street_line_1": "123 Washington St",
    "street_line_2": "Apt 2F",
    "city": "Chicago",
    "state": "IL",
    "postal_code": "10001",
    "country": "USA"
  },
  "formation_document": "<data-uri>",
  "ownership_document": "<data-uri>",
  "signed_agreement_id": <signed_agreement_id from above>
}'

Kyc status

Upon customer creation, Bridge will review all KYCs for the customer and return a status field that denotes the KYC status (as applicable) for the user (example KYC statuses include not_started, active, or rejected). The average decision time for KYC is typically less than one minute. If a manual review is required for KYC, the decision may take until next business day. KYB reviews typically happen same business day, up to next business day.

A sample response would look like:

// 201 CREATED
{
  "id": "cust_john_uuid",
  "first_name": "John",
  "kyc_status": "not_started",
  // ...
  "requirements_due": [
    "external_account" // Customer needs to register their bank account with Bridge
  ],
  "created_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00",
  "updated_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00"
}

While KYC generally works quickly, there are edge cases that are important to account for. Here are a few examples of how the KYC status of a customer could progress:

• not_started -> active
  • This is our happy path for individual customers. The customer information was submitted, and quickly passed via automated checks within seconds.
• not_started -> under_review -> approved/rejected
  • All business customers and some individual customers may require the Bridge Compliance team to do due diligence of vetting customers manually before the reach a terminal status.
• not_started -> rejected

🚧

Warning

Beginning October 21st, 2024, we will be adding the following two values to the status field that will affect both the API and Webhook customer response objects.

1. paused: the account is temporarily inactive due to compliance or other account-related issues.
2. offboarded: the customer’s Bridge account has been closed

KYC Rejection

Sometimes, your customer could immediately move from not_started to rejected and skip under_review entirely. The primary reason this happens is when the tax identification number is entered incorrectly. Without a valid tax identification number, Bridge is unable to verify any of the other details you have submitted for your customer (birth date, address, name, or business details).

In this scenario, the customer starts off not_started, but after attempting to verify submitted information, there was an issue detected with the submission. It is possible to move directly to rejected and skip under_review entirely. In the rejected scenario, fetching the customer via [GET /customers/:id](https://apidocs.bridge.xyz/reference/get_customers-customerid) would result in something like this:

{
  "id": "d99a4ee8-03a8-48a6-9cbf-7746a3ce1050",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "status": "rejected",
  "type": "individual",
  "created_at": "2024-02-19T17:16:20.561Z",
  "website_url": null,
  "persona_idv_link": "...",
  "tos_link": "...",
  "tos_complete": false,
  "persona_inquiry_type": "gov_id_db",
  "rejection_reasons": [
    {
      "developer_reason": "Identity cannot be verified agains third-party databases",
      "reason": "Your information could not be verified",
      "created_at": "2024-02-19T19:01:59.529Z"
    }
  ]
}

You can see that the customer's KYC status is rejected and that there are two fields shared with rejection reasons:

• developer_reason is meant to be used by developers for internal purposes only. This field can contain sensitive information intended for only the developer and is provided to help with troubleshooting potential issues or protecting against potential abuse.
• reason can be shared by a developer directly with their customers.

For reference, see our page on Rejection Reasons for developer_reason and reason mappings for KYC rejection reasons.

Updating Rejected Customers

If a customer has had their KYC attempt rejected, their information can be updated at PUT /customers/:id . This is not applicable to customers who have already had their KYC approved. This endpoint accepts the same shape of data as the creation endpoint.

Notes:

• Even if information was submitted in the first attempt and has not changed, it must still be submitted in the update.
• Updating the customer object won't clear their rejection reasons from earlier attempts, but that won't prevent them passing KYC.

Supported Government ID's by Country

Y = Yes (Supported) | * (Requires backside )