Read the KYB graph

Every entity this user owns — linked and unlinked — with the ownership edges, resolved documents and the flow’s status, in one request.

GET /api/v1/kyb/b2b/kyb/graph

Read the KYB graph

cURL

curl --request GET \
  --url https://api.example.com/api/v1/kyb/b2b/kyb/graph \
  --header 'Authorization: Bearer <token>'

200

{
  "kybStatus": "not_started",
  "updatedAt": "2023-11-07T05:31:56Z",
  "rootEntityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kybStatusByRails": {},
  "entities": [
    {
      "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"
    }
  ],
  "relationships": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "sourceEntityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "targetEntityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "hasControl": true,
      "isDirector": true,
      "isSigner": true,
      "ownershipPercentage": "<string>",
      "title": "<string>",
      "status": "active",
      "verifications": [
        {
          "provider": "swipelux",
          "status": "<string>",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "externalId": "<string>",
          "kycLink": "<string>",
          "kycLinkState": "<string>",
          "kycLinkExpiresAt": "2023-11-07T05:31:56Z"
        }
      ]
    }
  ],
  "pendingShareholders": [
    {
      "relationshipId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "[e-mail]",
      "hasControl": true,
      "isDirector": true,
      "isSigner": true,
      "status": "pending",
      "ownershipPercentage": "<string>"
    }
  ],
  "documents": {},
  "requiredDocuments": [
    "<string>"
  ],
  "requiredShareholderDocuments": [
    "<string>"
  ],
  "corporateAuthorityDocumentsRequired": true,
  "missingFields": [
    "<string>"
  ],
  "isReadyForSubmission": false,
  "uboKycLinks": [
    {
      "name": "<string>",
      "status": "<string>",
      "entityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "provider": "conduit_fiat",
      "email": "<string>",
      "link": "<string>",
      "expiresAt": "2023-11-07T05:31:56Z"
    }
  ],
  "comment": "<string>"
}

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

Response

200

application/json

Successful Response

The customer-facing view of one user's KYB graph.

Everything the KYB flow needs in one read, and nothing shaped like a questionnaire: the client edits entities and edges, so that is what it is given. The admin's richer, projection-shaped view lives in :class:KybDraftResponse and is built by a different service.

kybStatus · enum<string> · required

KYC verification status.

Available options: not_started, requested, incorporating, pending, under_review, approved, rejected

updatedAt · string<date-time> · required

rootEntityId · string<uuid> | null

The entity the KYB application is about.

kybStatusByRails · Kybstatusbyrails · object

Show child attributes

entities · EntityData · object[]

EVERY entity this user owns — the ones the ownership walk reaches and the ones it does not. Splitting them is what made half-linked people invisible to the client that created them; deciding what to show is the client's job, and it needs the whole set to do it.

Show child attributes

relationships · EntityRelationshipDraftData · object[]

Show child attributes

pendingShareholders · KybPendingShareholderData · object[]

Invited owners who have not consented yet. Only their HEVN login email and relationship status are disclosed.

Show child attributes

documents · Documents · object

Resolved documents (name, signed link) keyed by entity id. Each type is the slot the file is filed in, which is what the admin console and the submission gate read; a file filed in two slots is reported once per slot.

Show child attributes

requiredDocuments · string[]

Company document slots the draft flow asks for. Jurisdiction-dependent — a US company is also asked for its IRS EIN letter.

requiredShareholderDocuments · string[]

Document types every shareholder needs. Enforced at submit, so a client that cannot read the list here can only discover it by being refused.

corporateAuthorityDocumentsRequired · boolean · default: true

Whether Authorization to Act and Authority to Bind documents are required. False when the account email belongs to a director.

missingFields · string[]

What submission is still waiting for: the required fields POST /kyb/submit enforces, plus the document slots it asks for but does not block on. Without it here the flow could only discover the gap by being refused.

isReadyForSubmission · boolean · default: false

uboKycLinks · UboKycLink · object[]

Show child attributes

comment · string | null