Retrieve the KYB state of a legal entity | Deel

{
  "data": {
    "status": "pending_verification",
    "persons": [
      {
        "id": "c51e53d2-8a2f-4944-890b-f605a3ab247e",
        "last_name": "Lovelace",
        "first_name": "Ada",
        "responsibilities": [
          "owner",
          "director"
        ],
        "ownership_percentage": 51
      }
    ],
    "documents": [
      {
        "type": "ARTICLES_OF_INCORPORATION",
        "meta_type": "POWER_OF_ATTORNEY",
        "is_provided": false,
        "is_required": true
      }
    ],
    "rejection": {
      "rejected_at": "2026-09-10T09:00:00.000Z"
    },
    "approved_at": "2026-09-12T15:30:00.000Z",
    "rejected_at": "2026-09-10T09:00:00.000Z",
    "requirements": [
      {
        "key": "PROOF_OF_AUTHORITY",
        "category": "DOCUMENT",
        "is_satisfied": false
      }
    ],
    "submitted_at": "2026-09-01T10:00:00.000Z",
    "legal_entity_id": "5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b",
    "verification_type": "FULL",
    "is_action_required": true,
    "is_detail_available": true
  }
}

Returns the Know Your Business (entity verification) state of a legal entity: the verification status, whether the client must act, the outstanding requirements including Proof of Authority, which company documents have been supplied, the declared persons of significant control, and when the entity was rejected. Use it to drive an automated verification flow instead of finishing KYB in the Deel app.

Token scopes: legal-entity:read

Beta: this version requires the X-Beta: true request header and its contract may change before it is promoted to stable. It is scheduled to become stable on 2026-12-29.

Authentication

AuthorizationBearer

Authentication

The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.

curl -X GET 'https://api.deel.training/rest/v2/contracts' \
  -H 'Authorization: Bearer YOUR-TOKEN-HERE'

Learn more about authentication

AuthorizationBearer

Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

Path parameters

legal_entity_idstringRequiredformat: "uuid"

Public id of the legal entity. The entity must belong to the authenticated organization; any other id answers 404.

Response

The KYB state of the legal entity.

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error