> This page is for API, version 2026-01-01 (Stable) (default). > For other versions, use one of these documentation indexes: > - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.deel.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_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, when the entity was rejected, and the open enhanced due diligence (EDD) request with its questions while the entity is in EDD. 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 2027-01-01. Reference: https://developer.deel.com/api/reference/endpoints/legal-entities/get-legal-entity-kyb-state-v-2026-10-01 ## 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.letsdeel.com/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. ### Headers - `X-Beta` (enum, required, default: true) — Opts in to the beta version of this endpoint. Must be `true`. - Allowed values: `true` ## 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 - `edd` (LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEdd, required, nullable) — The open enhanced due diligence (EDD) request while the entity is in EDD: Deel needs further answers from the client before it continues the review. Null otherwise, and null while the entity is in EDD when the questions could not be read (retry later). - `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. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEdd The open enhanced due diligence (EDD) request while the entity is in EDD: Deel needs further answers from the client before it continues the review. Null otherwise, and null while the entity is in EDD when the questions could not be read (retry later). - `id` (string, required) — Public id of the EDD request. Send it as `edd_request_id` when answering. - `status` (enum, required) — `AWAITING_ANSWERS` until the answers are sent; `ANSWERED` once they are, until the entity is back in review. - Allowed values: `AWAITING_ANSWERS`, `ANSWERED` - `questions` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEddQuestionsItems, required) — Every question of the EDD form, in form order. - `requested_at` (string, required, nullable) — When Deel requested the EDD. - `is_answerable_over_api` (boolean, required) — False when the form has a required unsupported question. Contact Deel support to clear such a request. ### 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. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEddQuestionsItems - `key` (string, required) — Key of the question within this EDD request, in form order. Send it as `question_key` when answering. - `type` (enum, required) — What kind of answer the question takes. `COUNTRY` takes an ISO 3166-1 alpha-2 code (e.g. `US`), `CURRENCY` an ISO 4217 code (e.g. `USD`) and `STATE` a state name (e.g. `California`), each as a string, or a list of strings when the form allows several. `DOCUMENT_UPLOAD` questions are answered with a list of document handles from `POST /rest/legal-entities/{legal_entity_id}/kyb/edd/documents`. `UNSUPPORTED` questions cannot be answered over the API; when one of them is required, `is_answerable_over_api` is false. - Allowed values: `TEXT`, `LONG_TEXT`, `NUMBER`, `EMAIL`, `PHONE_NUMBER`, `DATE`, `DATE_RANGE`, `ADDRESS`, `SINGLE_CHOICE`, `MULTIPLE_CHOICE`, `COUNTRY`, `STATE`, `CURRENCY`, `DOCUMENT_UPLOAD`, `UNSUPPORTED` - `title` (string, required) — The question as the reviewer wrote it. - `options` (list of string, required, nullable) — For `SINGLE_CHOICE` and `MULTIPLE_CHOICE` questions, the option titles to answer with. Null for every other type. - `description` (string, required, nullable) — Helper text for the question, when any. - `is_required` (boolean, required) — Whether the question must currently be answered. - `repeat_group` (LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEddQuestionsItemsRepeatGroup, required, nullable) — Set when this question belongs to a repeatable group (e.g. "add another director"); null otherwise. - `revealed_when` (list of LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEddQuestionsItemsRevealedWhenItems, required, nullable) — Conditions under which this question applies, met if any one of them does. Null when the question always applies. Only answer it when a condition is met. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEddQuestionsItemsRepeatGroup Set when this question belongs to a repeatable group (e.g. "add another director"); null otherwise. - `name` (string, required) — Name of the repeatable group this question belongs to. - `index` (integer, required) — Zero-based position of this question within its repeat group instance. - `max_repeats` (integer, required) — Maximum number of instances of this group the form allows. ### LegalEntitiesLegalEntityIdKybGetResponsesContentApplicationJsonSchemaDataEddQuestionsItemsRevealedWhenItems - `equals` (string, required) — Option title `question` must be answered with for this question to apply. - `question` (string, required) — Key of the question whose answer gates this one. ## Examples **Response** ```json { "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 } } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb" headers = { "X-Beta": "true", "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: {'X-Beta': 'true', 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("X-Beta", "true") 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["X-Beta"] = 'true' 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("X-Beta", "true") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.letsdeel.com/rest/legal-entities/5f4a2c0e-6f1c-4a52-9c4e-1c8f1d2e3a4b/kyb', [ 'headers' => [ 'Authorization' => 'Bearer ', 'X-Beta' => 'true', ], ]); 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("X-Beta", "true"); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Beta": "true", "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() ```