Endorsements represent an approval of a customer to onboard and transact with Bridge.

To onboard a customer and enable them to take actions on Bridge, the customer must provide their KYC information and accept the terms of service for the required endorsement type.

Prerequisites

To obtain any endorsements, you must meet KYC Information and Terms of Service (ToS) requirements.

KYC Information

The first component is providing Bridge with the necessary KYC information from the customer by, either directly through the Customers API, or by asking the customer to follow a developer provided KYC Link.

Customers API

Here is an example for submitting information directly via the Customers 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]",
  "residential_address": {
    "street_line_1": "123 Main St",
    "city": "New York City",
    "subdivision": "New York",
    "postal_code": "10001",
    "country": "USA"
  },
  "birth_date": "2007-01-01",
  "signed_agreement_id": "d536a227-06d3-4de1-acd3-8b5131730480",
  "identifying_information": [
    {
      "type": "ssn",
      "issuing_country": "usa",
      "number": "xxx-xx-xxxx"
    },
    {
      "type": "drivers_license",
      "issuing_country": "usa",
      "number": "xxxxxxxxxxxxx",
      "image_front": "data:image/jpg;base64,...",
      "image_back": "data:image/jpg;base64,..."
    }
  ]
}

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",
  "residential_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
  },
  "birth_date": "2007-01-01",
  "signed_agreement_id": "d536a227-06d3-4de1-acd3-8b5131730480",
  "employment_status": "employed",
  "expected_monthly_payments": "5000_9999",
  "acting_as_intermediary": "no",
  "most_recent_occupation": "291291",
  "account_purpose": "purchase_goods_and_services",
  "account_purpose_other": null,
  "source_of_funds": "salary",
  "identifying_information": [
    {
      "type": "passport",
      "issuing_country": "arg",
      "number": "xxxxxxxxxxxxx",
      "image_front": "data:image/jpg;base64,...",
      "image_back": "data:image/jpg;base64,..."
    }
  ]
}

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]",
  "residential_address": {
    "street_line_1": "80 Queens Road",
    "street_line_2": "Suite 3B",
    "city": "Manchester",
    "subdivision": "MAN", // ISO 3166-2 Subdivision code without the country prefix
    "postal_code": "M1 1AE",
    "country": "GBR" // ISO 3166-1 alpha3 Country code
  },
  "birth_date": "2007-01-01",
  "signed_agreement_id": "d536a227-06d3-4de1-acd3-8b5131730480",
  "identifying_information": [
    {
      "type": "passport",
      "issuing_country": "gbr",
      "number": "xxxxxxxxxxxxx",
      "image_front": "data:image/jpg;base64,...",
    }
  ],
  "documents": [
    {
      "purposes": [
        "proof_of_address"
      ],
      "file": "data:image/jpg;base64,..."
    }
  ]
}

For more details please see the Customers API page.

KYC Link

To create a KYC Link, use the following endpoint:

curl --location --request POST 'https://api.bridge.xyz/v0/kyc_links' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \
--data-raw '{
  "full_name": "John Doe",
  "email": "[email protected]",
  "type": "individual", // or "business",
  "endorsement": "base"
}'

For more details please see the KYC Links page for new customers, or the Additional Requirements page for existing customers.

Terms of Service

The second component is obtaining terms of service acceptance from your customer. This is accomplished by providing your customer with a Terms of Service Link for them to follow.

Use this endpoint to request a URL and reference our ToS Links API.

Endorsement Types

There are a few different endorsements you can obtain for your customer. The type of endorsement you need for your customer depends on the region of residence and which fiat rails they're intending to utilize.

Base Endorsement

The base endorsement represents approval of a customer to onboard and transact with USD payment rails.

SEPA Endorsement

The sepa endorsement represents approval of using SEPA/Euro services offered by Bridge.

SPEI Endorsement

The spei endorsement represents approval of using SPEI/MXN peso services offered by Bridge.

Endorsement requirements

The customer object contains an endorsements attribute, where each endorsement will includes a requirements object. Developers can use it to get a comprehensive view into the status of endorsements, detailing which requirements are:

✅ Complete: Items that are already fulfilled.
⏳ Pending: Items received and are being reviewed internally.
🔍 Missing: Required items that are not yet pending or complete.
❗️ Issues: The required information has been received, but there are outside factors that will not allow us to approve the endorsement.

How It Works
The requirements object will provide a summary of the endorsement’s status, allowing developers to clearly identify which fields require action. For example, developers can now determine missing fields such as Proof of Address or Terms of Service acceptance.

Examples

The following is an example of a customer who requested both Base and SEPA.

{
  "endorsements": [
    {
      "name": "base",
      "status": "incomplete",
      "requirements": {
          "complete": [
            "first_name",
            "last_name",
            "tax_identification_number",
            "email_address",
            "date_of_birth",
            "accepted_risk_region",
            "address_of_residence"
          ],
          "pending": [],
          "missing": {
            "all_of": [
              "terms_of_service_v1",
              "sanctions_screen"
            ]
          },
          "issues": []
      },
    },
    {
      "name": "sepa",
      "status": "incomplete",
      "requirements": {
        "complete": [
          "first_name",
          "last_name",
          "tax_identification_number",
          "email_address",
          "date_of_birth",
          "accepted_risk_region",
          "address_of_residence"
        ],
        "pending": [],
        "missing": {
          "all_of": [
            "terms_of_service_v2",
            "proof_of_address",
            "sanctions_screen"
          ]
        },
        "issues": []
      },
    },
  ]
}

The following is an example of a customer who has fulfilled the requirements for Base, but have outstanding issues on their account preventing them from having the endorsement approved.

{
  "endorsements": [
    {
      "name": "base",
      "status": "incomplete",
      "requirements": {
        "complete": [
          "first_name",
          "last_name",
          "tax_identification_number",
          "email_address",
          "date_of_birth",
          "accepted_risk_region",
          "address_of_residence",
          "terms_of_service_v1",
          "sanctions_screen",
        ],
        "pending": [],
        "missing": nil,
        "issues": ["endorsement_not_available_in_customers_region"]
      }
    },
  ]
}