Submit KYB information for a legal entity | Deel

curl -X POST https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb \
     -H "X-Beta: true" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "data": {
    "persons": [
      {
        "last_name": "Lovelace",
        "first_name": "Ada",
        "responsibilities": [
          "owner",
          "director"
        ]
      }
    ],
    "is_declaration_confirmed": true,
    "is_terms_and_conditions_accepted": true
  }
}'

{
  "data": {
    "edd": {
      "id": "0b8f3e0a-6c2d-4f0e-9d3b-2a1f5c7e9b41",
      "status": "AWAITING_ANSWERS",
      "questions": [
        {
          "key": "q1",
          "type": "SINGLE_CHOICE",
          "title": "What is the source of the funds used to pay Deel invoices?",
          "options": [
            "Revenue from customers",
            "Investment"
          ],
          "description": "For example revenue from customers, investment, or a loan.",
          "is_required": true,
          "repeat_group": {
            "name": "Director",
            "index": 0,
            "max_repeats": 5
          },
          "revealed_when": [
            {
              "equals": "Yes",
              "question": "q1"
            }
          ]
        }
      ],
      "requested_at": "2026-09-20T09:00:00.000Z",
      "is_answerable_over_api": true
    },
    "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
  }
}

Submits the Know Your Business (entity verification) information for a legal entity — company facts, required declarations, documents, and declared persons of significant control. Only accepted while the entity is PENDING or DRAFT; refused once it is REJECTED, already under review, approved, or when verification isn’t required. Returns the resulting KYB state after submission.

Token scopes: legal-entity:write

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 2027-01-12.

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.letsdeel.com/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.

Request

The verification information for the legal entity.

dataobjectRequired

Response

The submission was accepted. The KYB state after the submission.

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error

Authentication

Authentication

Path parameters

Headers

Request

Response

Errors