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:

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

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 )

Country codeCountrySubdivision codeSubdivisionPassport extractionPassport verificationDriver License extractionDriver License verificationNational ID extractionNational ID verificationOther extractionOther verification(Requires backside: *)
ADAndorrayyyy
AEUnited Arab Emiratesyyyyy*yResidency permit*Residency permit
AFAfghanistanyy
AGAntigua and Barbudayy
AIAnguillayy
ALAlbaniayyyyy*y
AMArmeniayyyyy*y
AOAngolayyyyy*y
ARArgentinayyyyyy
ASAmerican Samoayyyyyy
ATAustriayyyyyyResidency permit*Residency permit
AUAustraliayyy*yy*yKeypass ID, Residency permit*Keypass ID, Residency permit
AZAzerbaijanyyy*yy*yResidency permit*Residency permit
BABosnia and Herzegovinayyyyy*y
BBBarbadosyyyy
BDBangladeshyyyyy*y
BEBelgiumyyyyy*yResidency permit*Residency permit
BFBurkina Fasoyy
BGBulgariayyyyyyResidency permit*Residency permit
BHBahrainyyy*y
BIBurundiyy
BJBeninyyyyyy
BMBermudayyyyVoter IDVoter ID
BNBrunei Darussalamyyyyy*yResidency permit*Residency permit
BOBolivia (Plurinational State of)yyyyy*y
BRBrazilyyy*yy*yResidency permit*Residency permit
BSBahamasyyyyWork permit*Work permit
BTBhutanyy
BWBotswanayyyyy*y
BYBelarusyyyyyy
BZBelizeyy
CACanadayy13131212Citizen certificate, Healthcare Insurance card, Passport card, Permanent resident card*, Tribal IDCitizen certificate, Healthcare Insurance card, Passport card, Permanent resident card, Tribal ID
CACanadaCA-ABAlbertayyyy
CACanadaCA-BCBritish Columbiayyyy
CACanadaCA-MBManitobayyyy
CACanadaCA-NBNew Brunswickyyyy
CACanadaCA-NLNewfoundland and Labradoryyyy
CACanadaCA-NSNova Scotiayyyy
CACanadaCA-ONOntarioyyyy
CACanadaCA-PEPrince Edward Islandyyyy
CACanadaCA-QCQuebecyy
CACanadaCA-SKSaskatchewanyyyy
CACanadaCA-NTNorthwest Territoriesyyyy
CACanadaCA-NUNunavutyyyy
CACanadaCA-YTYukonyyyy
CDCongo (Democratic Republic of the)yyVoter IDVoter ID
CFCentral African Republicyy
CGCongoyyy*yy*y
CHSwitzerlandyyyyy*yResidency permit*Residency permit
CICôte d'Ivoireyyy*yy*y
CLChileyyyyyy
CMCameroonyyyyy*y
CNChinayyyyy*y
COColombiayyy*yy*yForeigner IDForeigner ID
CRCosta Ricayyyyy*y
CUCubayyy*y
CVCabo Verdeyy
CWCuraçaoyyyyyy
CYCyprusyyyyy*yResidency permit*Residency permit
CZCzech Republicyyyyy*yResidency permit*Residency permit
DEGermanyyyyyy*yResidency permit*Residency permit
DJDjiboutiyy
DKDenmarkyyyyResidency permit*Residency permit
DMDominicayy
DODominican Republicyyy*yy*y
DZAlgeriayyy*y
ECEcuadoryyyyy*yConsular IDConsular ID
EEEstoniayyyyy*yResidency permit*Residency permit
EGEgyptyyyyy*y
EREritreayy
ESSpainyyyyy*yResidency permit*Residency permit
ETEthiopiayyyyyyResidency permit*Residency permit
FIFinlandyyyyy*yResidency permit*Residency permit
FJFijiyyyy
FMMicronesia (Federated States of)yy
FOFaroe Islandsyyyy
FRFranceyyyyy*yResidency permit*Residency permit
GAGabonyy
GBUnited Kingdom of Great Britain and Northern IrelandyyyyyyResidency permit*, Voter IDResidency permit, Voter ID
GDGrenadayy
GEGeorgiayyyyy*y
GGGuernseyyyyyyy
GHGhanayyyyy*yVoter IDVoter ID
GIGibraltaryyyyy*y
GLGreenlandyy
GMGambiayy
GNGuineayy
GQEquatorial Guineayy
GRGreeceyyyyy*yResidency permit*Residency permit
GTGuatemalayyy*yy*yConsular ID*Consular ID
GUGuamyyyyyy
GWGuinea-Bissauyy
GYGuyanayy
HKHong Kongyyyy
HNHondurasyyy*yyyConsular IDConsular ID
HRCroatiayyy*yy*yResidency permit*Residency permit
HTHaitiyy
HUHungaryyyyyy*yResidency permit*Residency permit
IDIndonesiayyyyyy
IEIrelandyyyyy*yPassport card, Residency permitPassport card, Residency permit
ILIsraelyyyyy*y
IMIsle of Manyyyy
INIndiayyy*yyyPermanent Account Number (PAN) card, Voter ID*Permanent Account Number (PAN) card, Voter ID
IQIraqyyy*y
ISIcelandyyyyResidency permit*Residency permit
ITItalyyyyyy*yResidency permit*Residency permit
JEJerseyyyyy
JMJamaicayyyyyyVoter IDVoter ID
JOJordanyyyyy*y
JPJapanyyyyMy Number card, Residency permit*, VisaMy Number card, Residency permit, Visa
KEKenyayyyyy*yResidency permit*Residency permit
KGKyrgyzstanyyyyy*y
KHCambodiayyyy
KIKiribatiyy
KMComorosyy
KNSaint Kitts and Nevisyy
KRKorea (Republic of)yyyyyyResidency permit*Residency permit
KWKuwaityyy*yyy
KYCayman Islandsyyyy
KZKazakhstanyyyyy*y
LALao People's Democratic Republicyyyy
LBLebanonyyyyyy
LCSaint Luciayy
LILiechtensteinyyyyy*yResidency permit*Residency permit
LKSri Lankayyyyy*y
LRLiberiayy
LSLesothoyy
LTLithuaniayyyyy*yResidency permit*Residency permit
LULuxembourgyyyyy*yResidency permit*Residency permit
LVLatviayyyyy*yResidency permit*Residency permit
LYLibyayy
MAMoroccoyyy*yy*y
MCMonacoyyy*yResidency permit*Residency permit
MDMoldova (Republic of)yyyyy*yResidency permit*Residency permit
MEMontenegroyyyyy*y
MFSaint Martin (French part)yyyy
MGMadagascaryy
MHMarshall Islandsyy
MKNorth Macedoniayyyyy*yResidency permit*Residency permit
MLMaliyy
MMMyanmaryyyyy*y
MNMongoliayyy*yy*y
MOMacaoyyResidency permit*Residency permit
MRMauritaniayy
MSMontserratyy
MTMaltayyyyy*yResidency permit*Residency permit
MUMauritiusyyy*y
MVMaldivesyy
MWMalawiyyyy
MXMexicoyy3232Consular ID, Residency permit, Voter ID*Consular ID, Residency permit, Voter ID
MXMexicoMX-AGyy
MXMexicoMX-BCyy
MXMexicoMX-BSyy
MXMexicoMX-CMyy
MXMexicoMX-CSyy
MXMexicoMX-CHyy
MXMexicoMX-COyy
MXMexicoMX-CLyy
MXMexicoMX-DFyy
MXMexicoMX-DGyy
MXMexicoMX-GTyy
MXMexicoMX-GRyy
MXMexicoMX-HGyy
MXMexicoMX-JAyy
MXMexicoMX-EMyy
MXMexicoMX-MIyy
MXMexicoMX-MOyy
MXMexicoMX-NAyy
MXMexicoMX-NLyy
MXMexicoMX-OAyy
MXMexicoMX-PUyy
MXMexicoMX-QTyy
MXMexicoMX-QRyy
MXMexicoMX-SLyy
MXMexicoMX-SIyy
MXMexicoMX-SOyy
MXMexicoMX-TByy
MXMexicoMX-TMyy
MXMexicoMX-TLyy
MXMexicoMX-VEyy
MXMexicoMX-YUyy
MXMexicoMX-ZAyy
MYMalaysiayyyyy*y
MZMozambiqueyyy*y
NANamibiayyy*y
NENigeryy
NGNigeriayyyyy*yVoter IDVoter ID
NINicaraguayyyyVoter IDVoter ID
NLNetherlandsyyy*yy*yResidency permit*Residency permit
NONorwayyyyyy*yResidency permit*Residency permit
NPNepalyyyyyyCitizen certificateCitizen certificate
NRNauruyy
NZNew Zealandyyyyyy
OMOmanyyy*yy*yResidency permit*Residency permit
PAPanamayyyyyyPermanent resident cardPermanent resident card
PEPeruyyy*yy*yResidency permit*Residency permit
PGPapua New Guineayy
PHPhilippinesyyyyy*yHealthcare Insurance card, NBI Clearance, Overseas Foreign Worker card (OFW), Postal ID, Social Security System card, United Multi Purpose ID (UMID), Voter IDHealthcare Insurance card, NBI Clearance, Overseas Foreign Worker card (OFW), Postal ID, Social Security System card, United Multi Purpose ID (UMID), Voter ID
PKPakistanyyy*y
PLPolandyyyyy*yResidency permit*Residency permit
PRPuerto Ricoyyyyyy
PSPalestine, State ofyy
PTPortugalyyyyy*yResidency permit*Residency permit
PWPalauyy
PYParaguayyyyyy*y
QAQataryyyyyyResidency permit*Residency permit
RORomaniayyyyyyResidency permit*Residency permit
RSSerbiayyyyy*y
RURussian FederationyyyyInternal passportInternal passport
RWRwandayyyyyy
SASaudi ArabiayyyyyyResidency permit*Residency permit
SBSolomon Islandsyy
SCSeychellesyyyy
SDSudanyy
SESwedenyyyyy*yResidency permit*Residency permit
SGSingaporeyyyyy*yLong-Term pass card, Work permitLong-Term pass card, Work permit
SISloveniayyyyy*yResidency permit*Residency permit
SKSlovakiayyyyy*yResidency permit*Residency permit
SLSierra Leoneyy
SMSan Marinoyyy*y
SNSenegalyyyyyy
SOSomaliayy
SRSurinameyy
SSSouth Sudanyy
STSao Tome and Principeyy
SVEl Salvadoryyy*yy*y
SZeSwatiniyy
TCTurks and Caicos Islandsyy
TDChadyy
TGTogoyy
THThailandyyyyy*y
TJTajikistanyy
TLTimor-Lesteyy
TMTurkmenistanyy
TNTunisiayyyyy*y
TOTongayy
TRTurkeyyyy*yy*yResidency permit*Residency permit
TTTrinidad and Tobagoyyyyy*y
TVTuvaluyy
TWTaiwanyyyyy*yHealthcare Insurance card, Residency permit*Healthcare Insurance card, Residency permit
TZTanzania, United Republic ofyyyyyyVoter IDVoter ID
UAUkraineyyyyPassport card, Residency permitPassport card, Residency permit
UGUgandayyyyyy
USUnited States of Americayy51515151Passport card, Permanent resident card, Travel Document, Visa, Work permit*Passport card, Permanent resident card, Travel Document, Visa, Work permit
USUnited States of AmericaUS-ALAlabamayyyy
USUnited States of AmericaUS-AKAlaskayyyy
USUnited States of AmericaUS-AZArizonayyyy
USUnited States of AmericaUS-ARArkansasyyyy
USUnited States of AmericaUS-CACaliforniayyyy
USUnited States of AmericaUS-COColoradoyyyy
USUnited States of AmericaUS-CTConnecticutyyyy
USUnited States of AmericaUS-DCDistrict of Columbiayyyy
USUnited States of AmericaUS-DEDelawareyyyy
USUnited States of AmericaUS-FLFloridayyyy
USUnited States of AmericaUS-GAGeorgiayyyy
USUnited States of AmericaUS-HIHawaiiyyyy
USUnited States of AmericaUS-IDIdahoyyyy
USUnited States of AmericaUS-ILIllinoisyyyy
USUnited States of AmericaUS-INIndianayyyy
USUnited States of AmericaUS-IAIowayyyy
USUnited States of AmericaUS-KSKansasyyyy
USUnited States of AmericaUS-KYKentuckyyyyy
USUnited States of AmericaUS-LALouisianayyyy
USUnited States of AmericaUS-MEMaineyyyy
USUnited States of AmericaUS-MDMarylandyyyy
USUnited States of AmericaUS-MAMassachusettsyyyy
USUnited States of AmericaUS-MIMichiganyyyy
USUnited States of AmericaUS-MNMinnesotayyyy
USUnited States of AmericaUS-MSMississippiyyyy
USUnited States of AmericaUS-MOMissouriyyyy
USUnited States of AmericaUS-MTMontanayyyy
USUnited States of AmericaUS-NENebraskayyyy
USUnited States of AmericaUS-NVNevadayyyy
USUnited States of AmericaUS-NHNew Hampshireyyyy
USUnited States of AmericaUS-NJNew Jerseyyyyy
USUnited States of AmericaUS-NMNew Mexicoyyyy
USUnited States of AmericaUS-NYNew Yorkyyyy
USUnited States of AmericaUS-NCNorth Carolinayyyy
USUnited States of AmericaUS-NDNorth Dakotayyyy
USUnited States of AmericaUS-OHOhioyyyy
USUnited States of AmericaUS-OKOklahomayyyy
USUnited States of AmericaUS-OROregonyyyy
USUnited States of AmericaUS-PAPennsylvaniayyyy
USUnited States of AmericaUS-RIRhode Islandyyyy
USUnited States of AmericaUS-SCSouth Carolinayyyy
USUnited States of AmericaUS-SDSouth Dakotayyyy
USUnited States of AmericaUS-TNTennesseeyyyy
USUnited States of AmericaUS-TXTexasyyyy
USUnited States of AmericaUS-UTUtahyyyy
USUnited States of AmericaUS-VTVermontyyyy
USUnited States of AmericaUS-VAVirginiayyyy
USUnited States of AmericaUS-WAWashingtonyyyy
USUnited States of AmericaUS-WVWest Virginiayyyy
USUnited States of AmericaUS-WIWisconsinyyyy
USUnited States of AmericaUS-WYWyomingyyyy
UYUruguayyyyyy*y
UZUzbekistanyyyyyy
VCSaint Vincent and the Grenadinesyy
VEVenezuela (Bolivarian Republic of)yyyyyy
VIVirgin Islands (U.S.)yyyyyy
VNViet Namyyyyyy
VUVanuatuyy
WSSamoayy
XKKosovoyyyyy*yResidency permit*Residency permit
YEYemenyyyy
ZASouth Africayyyyyy
ZMZambiayy
ZWZimbabweyyyyyy