> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.deel.wtf/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server. # Retrieve the KYB state of a legal entity GET https://api.letsdeel.com/rest/legal-entities/{legal_entity_id}/kyb 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. Reference: https://docs.deel.wtf/api/reference/endpoints/legal-entities/get-legal-entity-kyb-state-v-2026-09-29 ## Authentication - `Authorization` header (bearer token, required) — ## 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 curl -X GET 'https://api.deel.training/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication) - `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/ ## Servers - `https://api.letsdeel.com/rest` (Production, default) - `https://api-staging.letsdeel.com/rest` (Demo) ## Request ### Path parameters - `legal_entity_id` (string, required) — Public id of the legal entity. The entity must belong to the authenticated organization; any other id answers 404. ## Response ### 200 The KYB state of the legal entity. - `data` (LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaData, required) ## Errors ### 400 Bad Request Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ### 401 Unauthorized Error Unauthorized. The request token is missing or invalid. The API gateway rejects an unauthenticated call before it reaches Deel; a call that reaches Deel without a valid session is rejected by the access middleware, whose error item carries a message and no code. - `errors` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaErrorsItems, required) ### 403 Forbidden Error Forbidden. The token lacks the `legal-entity:read` scope or the actor cannot view entities of this organization. - `errors` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaErrorsItems, required) ### 404 Not Found Error Not found. The legal entity does not exist or does not belong to the authenticated organization. The two cases are deliberately indistinguishable. - `errors` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaErrorsItems, required) ### 500 Internal Server Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ## Types ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaData - `status` (enum, required) — The mapped lifecycle status of the legal entity, the same vocabulary as `status` on `GET /rest/legal-entities/{legal_entity_id}`. - Allowed values: `archived`, `active`, `draft`, `processing`, `processing_draft`, `pending_verification`, `awaiting_review`, `unknown` - `persons` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataPersonsItems, required, nullable) — Declared persons of significant control: directors, controlling officers, owners and the submitter. Identity documents are reported by presence only. Null when `is_detail_available` is false. - `documents` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataDocumentsItems, required, nullable) — Presence of every company-level document type. Null when `is_detail_available` is false. - `rejection` (LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataRejection, required, nullable) — Present only when the entity was rejected; null otherwise. - `approved_at` (string, required, nullable) — When the entity was approved; null otherwise. - `rejected_at` (string, required, nullable) — When the entity was last rejected; null otherwise. - `requirements` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataRequirementsItems, required, nullable) — Everything the verification service currently requires for this entity, with whether each item is already satisfied. Empty when verification is not required. Null when `is_detail_available` is false. - `submitted_at` (string, required, nullable) — When the verification record was created; null before the first submission. - `legal_entity_id` (string, required) — Public id of the legal entity. - `verification_type` (enum, required, nullable) — Depth of verification the entity is subject to, when known. - Allowed values: `NONE`, `LIGHT`, `FULL` - `is_action_required` (boolean, required) — True while the entity is waiting on the client: `PENDING`, `DRAFT`, or `EDD` (enhanced due diligence — Ops needs something further from the client). False while Deel is reviewing or once the entity is approved, rejected or exempt. - `is_detail_available` (boolean, required) — False when the verification service could not be read. Every detail block (`requirements`, `documents`, `proof_of_authority`, `persons`, `rejection`) is then null. Retry later; the status fields are still authoritative. ### ApiErrorRequest - `method` (string, optional) — The HTTP method of the failed request - `url` (string, optional) — The relative URL of the failed request - `status` (double, optional) — The status code of the response - `api_req_id` (string, optional) — The request ID of the failed request - `docs` (string, optional) — A link to the official documentation for the requested endpoint resource - `source` (string, optional) — The source handler which produced the returned error - `code` (double, optional) — The code of the source handler which produced the returned error ### ApiError - `message` (string, optional) — A description of the returned error - `path` (string, optional) — The JSON path where input validation failed ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaErrorsItems - `code` (string, required) — Machine-readable error code. - `message` (string, required) — Human-readable explanation of the error. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataPersonsItems - `id` (string, required, nullable) — Public id of the declared person, when the verification service has assigned one. - `last_name` (string, required) — Last name as declared. - `first_name` (string, required) — First name as declared. - `responsibilities` (list of enum, required) — Roles the person holds in the entity. - Allowed values: `submitter`, `controllingOfficer`, `owner`, `director` - `ownership_percentage` (double, required, nullable) — Declared ownership percentage for owners; null otherwise. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataDocumentsItems - `type` (enum, required) — Company-level document type. - Allowed values: `PROOF_OF_AUTHORITY`, `ARTICLES_OF_INCORPORATION`, `COMPANY_BANK_STATEMENT`, `LIST_OF_DIRECTORS`, `CERTIFICATE_OF_GOOD_STANDING`, `ULTIMATE_BENEFICIAL_OWNER_FORM` - `meta_type` (enum, required, nullable) — Kind of Proof of Authority document, when this entry's type is PROOF_OF_AUTHORITY. Null for every other document type. - Allowed values: `POWER_OF_ATTORNEY`, `RESOLUTION_OR_MINUTES`, `OTHER` - `is_provided` (boolean, required) — Whether a file for this document has been submitted. File contents and URLs are never returned. - `is_required` (boolean, required) — Whether the verification service currently requires this document. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataRejection Present only when the entity was rejected; null otherwise. - `rejected_at` (string, required, nullable) — When the rejection was recorded. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataRequirementsItems - `key` (string, required) — Requirement key as published by the verification service, e.g. `FORMATION_DATE`, `ARTICLES_OF_INCORPORATION`, `PROOF_OF_AUTHORITY`, `UBO_NAME`, `DIRECTOR_KYC_DOCUMENT`. Person-level keys are prefixed with the role they constrain: `DIRECTOR_`, `CONTROLLING_OFFICER_`, `UBO_` or `SUBMITTER_`. - `category` (enum, required) — What kind of input satisfies the requirement: a company field, a company document, or an attribute of a declared person. - Allowed values: `FIELD`, `DOCUMENT`, `PERSON` - `is_satisfied` (boolean, required) — Whether the current submission already satisfies the requirement. ## Examples **Response** ```json { "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 } } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```