Ctrl+K

Set Up Child Enterprises

Overview

Within your parent organization, you must create a child enterprise and a BitGo user account for each of your users. To create the user accounts in BitGo, you must submit your users' personal information for know-your-customer (KYC) verification. In addition to onboarding your users, you must also onboard the service user from your organization. However, the service user doesn't require KYC verification when you add them to the child enterprises, because they already completed KYC verification when you initially added them to your enterprise.

Note: You must add the same service user to every child enterprise you create.

Prerequisites

1. Set Up Child Enterprise

In call, you create the child enterprise and the user account, as well as add the service user to the child enterprise.

Endpoint: Create an Enterprise for an Organization

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
export ORGANIZATION_ID="YOUR_ORGANIZATION_ID"
export ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
export EMAIL="YOUR_USER'S_EMAIL"
export IDEMPOTENCY_KEY="UNIQUE_IDENTIFIER_PER_REQUEST"
export ADDITIONAL_ADMIN_1="OSERVICE_USER_ID"
export ADDITIONAL_ADMIN_2="ORGANIZATION_ADMIN_USER_ID"

curl -X POST \
  "https://app.bitgo-test.com/api/v2/organization/$ORGANIZATION_ID/enterprise" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "email": "'"$EMAIL"'",
    "idempotencyKey": "'"$IDEMPOTENCY_KEY"'",
    "additionalAdmins": [
      "'"$ADDITIONAL_ADMIN_1"'", # this is your service user
      "'"$ADDITIONAL_ADMIN_2"'" # this is your organization admin
      ]
}'

Step Result

You did the all of the following:

  • Created a new child enterprise within your parent organization.
  • Created a new user for the child enterprise (this is your end user).
  • Assigned the service user to the child enterprise.
  • Assigned organization admins to the child enterprise.
  • JSON
1
2
3
4
{
  "enterpriseId": "59cd72485007a239fb00282ed480da1f",
  "userId": "59cd72485007a239fb00282ed480da1f"
}

2. Submit KYC

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

Endpoint: Create Identity

  • cURL
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/entity-validation/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 identity for KYC purposes and BitGo returns one of the following statuses:

  • created - BitGo receives the user's KYC information and will asynchronously progress 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"
}

3. (Optional) Submit Supporting Documents

If a user is a United States citizen, you don't need to submit supporting documents for them unless BitGo requests for it. If a user isn't a United States citizen, you must always submit supporting documents for them.

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/entity-validation/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 the their identity to complete KYC verification.

BitGo receives the user's supporting documents and validates the their identity. The users's KYC status updates to evalutating submission. BitGo will asynchronously progress the status to in review, indicating that a BitGo Trust agent must manually review the information. Once approved, the status updates 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: Patch Update Identity

  • 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"

curl -X PATCH \
  "https://app.bitgo-test.com/api/entity-validation/v1/identity/$INTENTY_ID" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "contractSignerNameFull": "string",
    "contractSignedDate": "string",
    "contractSignedIPAddress": "string",
    "contractVersion": "string",
    "userAgreesToTerms": "string",
}'

Step Result

  • JSON
1
2
3
4
5
6
7
8
9
10
{
  "id": "string",
  "status": "string",
  "organizationId": "string",
  "enterpriseId": "string",
  "userId": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "errorDescription": "string"
}

Next Steps

Activate Go Accounts for their child enterprise.

See Also