Crypto-as-a-Service

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. Your users must complete KYC verification before they can use BitGo products on your platform.

Supported Regions

BitGo supports KYC verification for end users under two trust entities. The transactionType you use when submitting KYC determines which trust entity and regulatory framework applies to your end user.

Region Trust Entity Transaction Type
United States BitGo Bank & Trust institutionalIndividual
European Union BitGo Europe GmbH euIndividual

Note

BitGo Europe GmbH is the sole EU legal entity holding all EU licenses and services all EEA (European Economic Area) countries.

Prerequisites

Cookbook

Need just the steps? Expand the cookbook below to get started:

Complete KYC VerificationOpen Cookbook

Steps

Select your region:

KYC Lifecycle

The diagram below provides a high-level overview of the US KYC lifecycle, illustrating the various states an identity can progress through from initial submission to final decision.

Crypto-as-a-Service KYC Crypto-as-a-Service KYC

1. Submit KYC

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

Endpoint: Create KYC Identity

export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export ORGANIZATION_ID="<YOUR_ORGANIZATION_ID>"

curl -X POST \
  https://app.bitgo-test.com/api/evs/v1/identity \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "enterpriseId": "59cd72485007a239fb00282ed480da1f", # newly created child enterprise for end user
    "userId": "67d28e3dea178ede86f2962e959865a0", # primary contact for the end user of the child enterprise
    "organizationId": "'"$ORGANIZATION_ID"'",
    "nameFirst": "John",
    "nameLast": "Doe",
    "nameMiddle": "F",
    "debugStatus": "passed",
    "debugFailureReason": "",
    "phoneNumber": "+442083661173",
    "birthdate": "2025-03-13T00:00:00Z",
    "occupation": "Other - Default",
    "countryOfCitizenship": "USA",
    "countryOfResidence": "USA",
    "govIdCountryOfIssuance": "USA",
    "identificationNumber": "494-14-2205",
    "politicallyExposedPerson": false,
    "addressStreet1": "Street 1",
    "addressStreet2": "Unit 100",
    "addressCity": "San Jose",
    "addressSubdivision": "CA",
    "country": "USA",
    "transactionType": "institutionalIndividual",
    "addressPostalCode": "33604"
}'

Step Result

You create an identity for KYC purposes and BitGo returns the id and status of the created identity. The status is initiating which confirms that BitGo has received the end user's KYC information and is reviewing it.

{
  "id": "993ec85b-ad23-4259-bde5-703a071a0783",
  "status": "initiating"
}

BitGo requires valid tax identification numbers for US individuals (citizens and residents). Populate the identificationNumber field according to these requirements:

Citizenship Requirement
US citizens Must provide a valid Social Security Number (SSN)
US residents (non-citizens) Must provide a valid SSN or Individual Taxpayer Identification Number (ITIN)
Other non-US individuals (under BitGo Bank & Trust) Can optionally submit SSN or ITIN if held (e.g. dual nationals, former US residents, etc.)

2. Check KYC Status

Check the KYC status of your end user to determine next steps.

Endpoint: Get KYC Identity

export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export ORGANIZATION_ID="<YOUR_ORGANIZATION_ID>"
export ENTERPRISE_ID="<CHILD_ENTERPRISE_ID>"
export IDENTITY_ID="<END_USER_IDENTITY_ID>"

curl -X GET \
  "https://app.bitgo-test.com/api/evs/v1/identity?organizationId=$ORGANIZATION_ID&enterpriseId=$ENTERPRISE_ID&identityId=$IDENTITY_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Note

Use both the organization and enterprise IDs to successfully fetch your end user KYC identity.

Step Result

BitGo returns one of the following KYC statuses:

  • initiating - BitGo confirms receipt of the end user's KYC information.
  • evaluating submission - BitGo runs automated checks on the submitted KYC information.
  • input error - The name or birthdate fields contain formatting issues. You must update the identity with properly formatted input fields.
  • taxid error - The tax ID submitted is invalid. You must update the identity with a valid tax ID.
  • awaiting document upload - BitGo requires supporting identity verification documents to continue with the review process.
  • in review - BitGo manually reviews the KYC information.
  • awaiting signature - BitGo completes review of the KYC information and now requires you to confirm verification with a signature.
  • incomplete verifications - BitGo can't complete verification using the provided documents. You must re-upload identity verification documents for the end user. BitGo recommends uploading a different kind of identity verification document.
  • approved - BitGo approves your end user's KYC verification and marks it as complete.
  • declined - BitGo declines your end user's KYC verification.
{
    "identities": [
        {
            "id": "5436ff2e-1129-49f1-8334-1510955ffe00",
            "status": "awaiting document upload",
            "organizationId": "68928b9066417fe09212fe9965c88552",
            "enterpriseId": "690a234346b3252214cdaf72070c549e",
            "userId": "690a234046b3252214cdadfe8600df80",
            "createdAt": "2025-11-04T16:05:15.359Z",
            "updatedAt": "2025-11-04T16:05:17.975Z",
            "signaturesSubmitted": [],
            "signaturesRequired": []
        }
    ]
}

3. Submit Documents

If the end user's KYC status is awaiting document upload, you must submit their identity verification documents. Document submission requirements vary by citizenship:

Citizenship Documentation Required?
US citizens Not required unless BitGo explicitly requests it
Non-US citizens (under BitGo Bank & Trust) Identity verification documents required

BitGo recommends submitting all necessary documents for an end user in a single API call. Document files can't exceed 15MB and must be at least 200x200px.

Note

BitGo limits the number of times you can submit documents for each end user. Ensure document quality before submission to avoid exhausting retry attempts.

3.1 Add Documents

Endpoint: Add KYC Documents

export IDENTITY_ID="<END_USER_IDENTITY_ID>"
export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export ID_CLASS="<DOCUMENT_ID_CLASS>"

curl -X POST \
  "https://app.bitgo-test.com/api/evs/v1/identity/$IDENTITY_ID/document" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "selectedIdClass=$ID_CLASS" \
  -F "frontPhoto=@<PATH_TO_FRONT_PHOTO>" \
  -F "backPhoto=@<PATH_TO_BACK_PHOTO>" \
  -F "proofOfResidency=@<PATH_TO_PROOF_OF_RESIDENCY>"

Step Result

BitGo returns the following:

  • The document ID - A unique ID for the document submission. Store this ID for use if you need to update the document submission.
  • The document status - the initial status is pending which confirms that BitGo has received the document. Other possible statuses include:
    • processing - BitGo is validating the document
    • approved - BitGo successfully verified the document
    • rejected - The document failed verification
  • The list of files that you uploaded for the end user including details such as file upload status, document type, and size.
{
  "id": "02f3186c-8589-4lfa-a800-1e5cc169c726",
  "status": "pending",
  "selectedIdClass": "pp",
  "fileUploads": [
      {
          "fileName": "passport-front.jpeg",
          "fileSize": 11275,
          "uploadStatus": "pending",
          "documentType": "frontPhoto"
      }
  ]
}

BitGo processes the documents with the following workflow:

  1. Initial receipt - The end user's KYC status updates to records uploaded.
  2. Automated validation - BitGo runs automated checks on the submitted documents.
  3. Then, one of the following occurs:
    • Validation passed or failed with no retry attempts remaining: - The end user's status updates to in review for manual review by BitGo.
    • Validation failed (with retry attempts remaining): The end user's status updates to incomplete verifications, and you must re-upload improved documentation.

3.2 Get Documents

After submitting documents, you can retrieve the document details to check upload status and verify file information.

Endpoint: Get KYC Document

export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export IDENTITY_ID="<END_USER_IDENTITY_ID>"
export DOCUMENT_ID="<DOCUMENT_ID>"

curl -X GET \
  "https://app.bitgo-test.com/api/evs/v1/identity/document?identityId=$IDENTITY_ID&documentId=$DOCUMENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Note

You can query by either identityId or documentId, or both. At least one parameter is required.

Step Result

{
  "documents": [
    {
      "id": "02f3186c-8589-4lfa-a800-1e5cc169c726",
      "status": "processing",
      "selectedIdClass": "pp",
      "fileUploads": [
        {
          "fileName": "passport-front.jpeg",
          "fileSize": 11275,
          "uploadStatus": "uploaded",
          "documentType": "frontPhoto"
        },
        {
          "fileName": "passport-back.jpeg",
          "fileSize": 10842,
          "uploadStatus": "uploaded",
          "documentType": "backPhoto"
        }
      ]
    }
  ]
}

3.3 Update Documents

You can only update documents when the KYC status is incomplete verifications. Verify the status before proceeding.

Endpoint: Update KYC Document

export IDENTITY_ID="<END_USER_IDENTITY_ID>"
export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export ID_CLASS="<DOCUMENT_ID_CLASS>"
export DOCUMENT_ID="<DOCUMENT_ID>" # The ID of the document initially created

curl -X PUT \
  "https://app.bitgo-test.com/api/evs/v1/identity/$IDENTITY_ID/document/$DOCUMENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "selectedIdClass=$ID_CLASS" \
  -F "frontPhoto=@<PATH_TO_FRONT_PHOTO>" \
  -F "backPhoto=@<PATH_TO_BACK_PHOTO>" \
  -F "proofOfResidency=@<PATH_TO_PROOF_OF_RESIDENCY>"

Step Result

{
  "id": "02f3186c-8589-4lfa-a800-1e5cc169c726",
  "status": "pending",
  "selectedIdClass": "pp",
  "fileUploads": [
      {
          "fileName": "passport-front.jpeg",
          "fileSize": 11275,
          "uploadStatus": "pending",
          "documentType": "frontPhoto"
      }
  ]
}

4. Sign Completed KYC

Once BitGo approves the KYC verification, your end user must sign to confirm. You can repeat step 2, Check KYC Status, to verify when the end user is awaiting signature.

Endpoint: Submit KYC Signatures

export IDENTITY_ID="<END_USER_IDENTITY_ID>"
export ACCESS_TOKEN="<SERVICE_USER_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

{
  "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": ["<CONTRACT_TYPE_1>", "<CONTRACT_TYPE_2>"],
  "signaturesRequired": []
}

Simulating KYC Flows

You can simulate different KYC verification flows to test your integration without manual review from BitGo. The debugStatus field enables you to control the KYC verification flow during testing. It accepts failed and passed as valid values and defaults to passed.

You can also pass debugFailureReason to get more specific errors on the identity errorDescription, this does not impact the KYC flow and is supplementary to debugStatus. Some possible values with specific error message mappings are: expired, cannot_verify_id, portrait_not_found, portrait_not_clear, face_mismatch, etc.

You can set both debugStatus and debugFailureReason when creating an identity and you can only update these fields when the identity status is awaiting document upload or incomplete verifications using the Update KYC Identity endpoint.

Note

The following test paths are only available in the BitGo test environment.

This path simulates the fastest approval scenario where document upload is not required.

Steps

  1. Create an identity for a non-PEP (politically exposed person) US citizen without the debugStatus parameter.
    • Recommendation: Avoid using New York (NY) as the state, as NY-based identities may sometimes require additional documentation.
  2. The identity status automatically progresses to awaiting signature, bypassing document upload.
  3. Submit the required signatures.

Expected Outcome

The identity status updates to approved without requiring document upload.

Next Steps

Create Go Accounts for your users.

See Also