Create or update the entity under a client-chosen id

Write the entity at this id, creating it if the id is free.

A phone that loses the response to POST cannot tell a request that never arrived from one that did, and retrying it would create a second person. Letting the client choose the id makes the retry land on the same row — and lets a person and their ownership edge go out together, since the edge can name an id the client already knows.

PUT /api/v1/kyb/b2b/kyb/entities/{entity_id}

Create or update the entity under a client-chosen id

cURL

curl --request PUT \
  --url https://api.example.com/api/v1/kyb/b2b/kyb/entities/{entity_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "firstName": "<string>",
  "middleName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "dateOfBirth": "2023-12-25",
  "nationalities": [],
  "title": "<string>",
  "legalName": "<string>",
  "tradeName": "<string>",
  "registrationNumber": "<string>",
  "taxId": "<string>",
  "address": {
    "streetAddress": "<string>",
    "city": "<string>",
    "addressLine2": "<string>",
    "state": "<string>",
    "zip": "<string>"
  },
  "documents": {},
  "identityDocuments": [
    {
      "number": "<string>"
    }
  ],
  "companyDdData": {
    "entityType": "<string>",
    "entityTypeDescription": "<string>",
    "incorporationDate": "2023-12-25",
    "industry": "<string>",
    "websites": [
      "<string>"
    ],
    "operatingCountries": [],
    "expectedMonthlyVolumeUsd": 1,
    "estimatedAnnualRevenue": 1,
    "hasUsBank": true,
    "deniedUsBank": true,
    "hasPep": true,
    "bizAdverse": [
      "<string>"
    ],
    "ownersAdverse": [
      "<string>"
    ],
    "publicListed": true,
    "usesBlockchain": true,
    "institutionalInvestors": true,
    "isRegulated": true
  },
  "usageData": {
    "business": "<string>",
    "businessIndustry": "<string>",
    "businessType": "<string>",
    "businessTypeDetails": "<string>",
    "verifierRole": "<string>",
    "sourceOfFunds": "<string>",
    "sourceOfFundsDetails": "<string>",
    "purposeOfFunds": "<string>",
    "purposeOfFundsDetails": "<string>",
    "flowOfFunds": "<string>",
    "complianceScreening": "<string>",
    "handlesCustomerFunds": true,
    "actingAsIntermediary": true,
    "sanctionedCountryOperations": true,
    "highRiskActivities": [
      "<string>"
    ],
    "depositMethods": [
      "<string>"
    ],
    "contactInfo": "<string>"
  },
  "acceptedTermsAt": "2023-11-07T05:31:56Z"
}
'

200

{
  "creatorUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "corporateAuthorityDocumentIds": {
    "authorizationToActDocumentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "authorityToBindDocumentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "referenceId": "<string>",
  "firstName": "<string>",
  "middleName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "country": "AF",
  "dateOfBirth": "2023-12-25",
  "birthCountry": "AF",
  "nationalities": [
    "AF"
  ],
  "title": "<string>",
  "legalName": "<string>",
  "tradeName": "<string>",
  "registrationNumber": "<string>",
  "taxId": "<string>",
  "address": {
    "streetAddress": "<string>",
    "city": "<string>",
    "country": "AF",
    "addressLine2": "<string>",
    "state": "<string>",
    "zip": "<string>"
  },
  "documents": {},
  "identityDocuments": [
    {
      "type": "passport",
      "issuingCountry": "AF",
      "number": "<string>"
    }
  ],
  "companyDdData": {
    "entityType": "<string>",
    "entityTypeDescription": "<string>",
    "incorporationDate": "2023-12-25",
    "industry": "<string>",
    "websites": [
      "<string>"
    ],
    "operatingCountries": [
      "AF"
    ],
    "expectedMonthlyVolumeUsd": "<string>",
    "estimatedAnnualRevenue": "<string>",
    "hasUsBank": true,
    "deniedUsBank": true,
    "hasPep": true,
    "bizAdverse": [
      "<string>"
    ],
    "ownersAdverse": [
      "<string>"
    ],
    "publicListed": true,
    "txPerMonth": "<10",
    "usesBlockchain": true,
    "revenueCovers": "all_operating_expenses",
    "institutionalInvestors": true,
    "isRegulated": true
  },
  "usageData": {
    "business": "<string>",
    "businessIndustry": "<string>",
    "businessType": "<string>",
    "businessTypeDetails": "<string>",
    "verifierRole": "<string>",
    "sourceOfFunds": "<string>",
    "sourceOfFundsDetails": "<string>",
    "purposeOfFunds": "<string>",
    "purposeOfFundsDetails": "<string>",
    "flowOfFunds": "<string>",
    "complianceScreening": "<string>",
    "handlesCustomerFunds": true,
    "actingAsIntermediary": true,
    "sanctionedCountryOperations": true,
    "highRiskActivities": [
      "<string>"
    ],
    "depositMethods": [
      "<string>"
    ],
    "contactInfo": "<string>"
  },
  "acceptedTermsAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-api-key · string | null

Path Parameters

entity_id · string<uuid> · required

Body

application/json

Create or partially update an entity from the KYB draft editor.

id · string<uuid> | null

firstName · string | null

middleName · string | null

lastName · string | null

email · string | null

phone · string | null

country · enum<string> | null

ISO 3166-1 alpha-2 country codes.

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

dateOfBirth · string<date> | null

birthCountry · enum<string> | null

ISO 3166-1 alpha-2 country codes.

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

nationalities · enum<string>[] | null

ISO 3166-1 alpha-2 country codes.

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

title · string | null · deprecated

legalName · string | null

tradeName · string | null

registrationNumber · string | null

taxId · string | null

As the registry issues it. No shape is imposed — the per-country pattern the provider sends in the requirement constraints is the only one that applies. The bound is a size guard, not a format.

Maximum string length: 64

address · EntityAddress · object | null

Show child attributes

documents · Documents · object | null

Show child attributes

identityDocuments · EntityIdentityDocument · object[] | null

Show child attributes

companyDdData · CompanyDueDiligenceData · object | null

Show child attributes

usageData · EntityUsageData · object | null

Show child attributes

acceptedTermsAt · string<date-time> | null

Response

200

application/json

Successful Response

creatorUserId · string<uuid> · required

corporateAuthorityDocumentIds · CorporateAuthorityDocumentIds · object · required · read-only

Expose typed authority IDs without creating a second source of truth.

Show child attributes

id · string<uuid> | null

referenceId · string | null

firstName · string | null

middleName · string | null

lastName · string | null

email · string | null

phone · string | null

country · enum<string> | null

ISO 3166-1 alpha-2 country codes.

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

dateOfBirth · string<date> | null

birthCountry · enum<string> | null

ISO 3166-1 alpha-2 country codes.

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

nationalities · enum<string>[]

ISO 3166-1 alpha-2 country codes.

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

title · string | null · deprecated

legalName · string | null

tradeName · string | null

registrationNumber · string | null

taxId · string | null

address · EntityAddress · object | null

Show child attributes

documents · Documents · object

Show child attributes

identityDocuments · EntityIdentityDocument · object[]

Show child attributes

companyDdData · CompanyDueDiligenceData · object

Show child attributes

usageData · EntityUsageData · object

Show child attributes

acceptedTermsAt · string<date-time> | null