Ctrl+K

Complete Know Your Customer (KYC) Verification

Overview

The Know Your Customer (KYC) API enables you to programmatically verify the information of users onboarding to your platform and ensure regulatory compliance. KYC verification of your users is required before they can use BitGo products on your platform.

KYC Webhooks

You can set up webhooks to keep you informed throughout the KYC process. See the Create Enterprise Webhooks guide for more information.

Prerequisites

1. Submit KYC

Submit basic KYC information for your user. If necessary, uploading supporting documents occurs in the next step.

Endpoint: Create Identity

  • cURL
  • JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X POST \
  "https://app.bitgo-test.com/api/evs/v1/identity" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "enterpriseId": "string",
    "userId": "string",
    "organizationId": "string",
    "nameFirst": "string",
    "nameLast": "string",
    "nameMiddle": "string",
    "debugStatus": "string",
    "debugFailureReason": "string",
    "phoneNumber": "string",
    "birthdate": "string",
    "occupation": "Agriculture",
    "countryOfCitizenship": "string",
    "countryOfResidence": "string",
    "govIdCountryOfIssuance": "string",
    "politicallyExposedPerson": "string",
    "addressStreet1": "string",
    "addressCity": "string",
    "addressSubdivision": "string",
    "country": "string",
    "identificationNumber": "string",
    "transactionType": "institutionalIndividual",
    "addressStreet2": "string",
    "addressPostalCode": "string",
    "digitalAssetWalletAddress": "string",
    "notionalTradedEachMonth": 0
}'

Step Result

You created an identity for KYC purposes and BitGo returns one of the following statuses:

  • created - BitGo receives the user's KYC information and asynchronously progresses the status to evaluating submission and then awaiting signature.
  • awaiting document upload - BitGo receives the user's KYC information, but requires supporting documents to continue. To proceed, see the next step.
  • JSON
1
2
3
4
{
  "id": "12345678",
  "status": "created"
}

2. Submit Documents

If a user is a United States citizen, you don't need to submit documentation unless BitGo requests it. If a user isn't a United States citizen, you must submit additional documentation.

BitGo recommends submitting all the necessary documents for a user in a single API call. Documents must not exceed 15MB in size and must be minimum 200x200px.

Endpoint: Create Identity Document

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
export INTENTY_ID="<USER_INTENTY_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ID_CLASS="<DOCUMENT_ID_CLASS>"

curl -X POST \
  "https://app.bitgo-test.com/api/evs/v1/identity/$INTENTY_ID/document" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "selectedIdClass": "'"$ID_CLASS"'",
    "frontPhoto": null,
    "backPhoto": null,
    "proofOfResidency": null
}'

Step Result

BitGo receives the supporting documents and validates them to complete KYC verification. The users's KYC status updates to evalutating submission. BitGo asynchronously progresses the status to in review and manually reviews the information. Once approved, the status updates to awaiting signature.

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "id": "string",
  "status": "evalutating submission",
  "selectedIdClass": "cct",
  "fileUploads": [
    {
      "fileName": "string",
      "fileSize": 0,
      "uploadStatus": "string",
      "documentType": "frontPhoto"
    }
  ]
}

4. Sign Completed KYC

Once BitGo approves the user's KYC verification, the user must sign to confirm their verification. You can check the status of KYC verifications using the Get Identity endpoint. To complete this step, the status must be awaiting signature.

Endpoint: Submit KYC Signatures

  • cURL
  • JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
export IDENTITY_ID="<USER_IDENTITY_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X POST \
  "https://app.bitgo-test.com/api/evs/v1/identity/$IDENTITY_ID/signatures" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '[
    {
      "contractSignerNameFull": "John Smith",
      "contractSignedDate": "2025-03-13 13:14:09.767480+00:00",
      "contractSignedIPAddress": "123.123.123.123",
      "contractVersion": "1.0",
      "contractType": "csa",
      "userAgreesToTerms": true
    },
    {
      "contractSignerNameFull": "John Smith",
      "contractSignedDate": "2025-03-13 13:14:09.767480+00:00",
      "contractSignedIPAddress": "123.123.123.123",
      "contractVersion": "1.0",
      "contractType": "mpa",
      "userAgreesToTerms": true
    },
    {
      "contractSignerNameFull": "Jerry Smith",
      "contractSignedDate": "2025-03-13 13:14:09.767480+00:00",
      "contractSignedIPAddress": "123.123.123.123",
      "contractVersion": "1.0",
      "contractType": "mic",
      "userAgreesToTerms": true
    }
  ]'

Step Result

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
{
  "id": "cf5d766d-bef1-4874-8b02-54ded0e8333e",
  "status": "signature submitted",
  "organizationId": "6573806ef79cafdd1aff42fbffc2ab20",
  "enterpriseId": "67d28e40ea178ede86f296ac90032286",
  "userId": "67d28e3dea178ede86f2962e959865a0",
  "updatedAt": "2025-03-13T07:59:52.564Z",
  "createdAt": "2025-03-13T07:54:18.842Z",
  "errorDescription": "",
  "signaturesSubmitted": ["csa", "mpa", "mic"],
  "signaturesRequired": []
}

Next Steps

Create Go Accounts for your users.

See Also