Deel: Submit KYB information for a legal entity
Deel legalEntities.submitLegalEntityKyb: arguments, response, policy and SDK examples.
← Legal entities operations · Get started
Operation deel.legalentities_submitlegalentitykyb_v2026_10_12
Provider route: POST /legal-entities/{legal_entity_id}/kyb. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/deel with npm, or alter-sdk-deel with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { DeelIntegration } from "@alter-ai/deel";
async function execute(input: Parameters<DeelIntegration["legalEntities"]["submitLegalEntityKyb"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new DeelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.legalEntities.submitLegalEntityKyb(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_deel import DeelIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = DeelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.legal_entities.submit_legal_entity_kyb(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.legal_entity_id | string | Required within parent | Format: uuid |
headers | object | Required within parent | Additional keys: not allowed |
headers.X-Beta | string | Required within parent | Default: true One of: true |
body | object | Optional | |
body.data | Model | Required within parent | Expand Submit KYB information for a legal entity — request body — body data |
Referenced models: Submit KYB information for a legal entity — request body — body data
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Retrieve the KYB state of a legal entity — 200 response body |
Referenced models: Retrieve the KYB state of a legal entity — 200 response body
Schemas
Section titled “Schemas”17 more schemas are linked from the tables above, on the schema pages.
Submit KYB information for a legal entity — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
documents | Model | Optional | Expand Submit KYB information for a legal entity — request body — body data documents Company documents as handles from the upload endpoint. Supply the ones the KYB state lists as required. |
formation_date | string | Optional | Company formation date, `YYYY-MM-DD`. Format: date |
is_declaration_confirmed | boolean | Required within parent | Must be true: the client confirms the information is accurate and complete. |
is_person_with_significant_control | boolean | Optional | Declares that the submitter personally holds significant control of the company (an owner, director or controlling officer) — the declared submitter in `persons[]` should hold one of those responsibilities too. An alternative to `proof_of_authority`: when `true`, the verification service waives the Proof of Authority document requirement. Omit or set `false` if the submitter is acting on the company's behalf without significant control themselves. |
is_terms_and_conditions_accepted | boolean | Required within parent | Must be true: the client accepts the verification terms and conditions. |
persons | array | Required within parent | Persons of significant control: directors, controlling officers, owners and the client-side submitter. |
persons[] | Model | Each item | Expand Submit KYB information for a legal entity — request body — body data persons item |
proof_of_authority | Model | Optional | Expand Submit KYB information for a legal entity — request body — body data proof of authority Proof of Authority for the person acting on behalf of the entity. Required when the KYB state lists `PROOF_OF_AUTHORITY` as outstanding, unless `is_person_with_significant_control` is `true`. |
questionnaire | Model | Optional | Expand Submit KYB information for a legal entity — request body — body data questionnaire Answers to the industry questionnaire. Required when the KYB state lists the `INDUSTRY_QUESTIONNAIRE` requirement, refused when no questionnaire applies. |
transaction_monthly_volume | string | Optional | Expected monthly transaction volume range. One of: LESS_THAN_1K, BETWEEN_1K_AND_10K, BETWEEN_10K_AND_100K, BETWEEN_100K_AND_1M, GREATER_THAN_1M |
Referenced models: Submit KYB information for a legal entity — request body — body data documents, Submit KYB information for a legal entity — request body — body data persons item, Submit KYB information for a legal entity — request body — body data proof of authority, Submit KYB information for a legal entity — request body — body data questionnaire
Retrieve the KYB state of a legal entity — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Retrieve the KYB state of a legal entity — 200 response body — data |
Referenced models: Retrieve the KYB state of a legal entity — 200 response body — data
Submit KYB information for a legal entity — request body — body data documents
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Company documents as handles from the upload endpoint. Supply the ones the KYB state lists as required. |
articles_of_incorporation | string | Optional | Handle of a document uploaded as `ARTICLES_OF_INCORPORATION`. Format: uuid |
certificate_of_good_standing | string | Optional | Handle of a document uploaded as `CERTIFICATE_OF_GOOD_STANDING`. Format: uuid |
company_bank_statement | string | Optional | Handle of a document uploaded as `COMPANY_BANK_STATEMENT`. Format: uuid |
ultimate_beneficial_owner_form | string | Optional | Handle of a document uploaded as `ULTIMATE_BENEFICIAL_OWNER_FORM`. Format: uuid |
Submit KYB information for a legal entity — request body — body data persons item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
address | Model | Optional | Expand Submit KYB information for a legal entity — request body — body data persons item address Residential address. |
citizenship | string | Optional | Citizenship as an ISO 3166-1 alpha-2 country code. |
date_of_birth | string | Optional | Date of birth, `YYYY-MM-DD`. Format: date |
first_name | string | Required within parent | First name. Maximum length: 255 |
identification_document_type | string | Optional | Type of the identity document supplied in `identity_documents`. One of: PASSPORT, DRIVERS_LICENSE, ID_DOCUMENT |
identity_documents | Model | Optional | Expand Submit KYB information for a legal entity — request body — body data persons item identity documents Identity document sides and selfie for the person, as upload handles. |
job_title | Model | Optional | Expand Submit KYB information for a legal entity — request body — body data persons item job title Role of the person in the company, from the verification service vocabulary; required for controlling officers when the verification service asks for it. |
last_name | string | Required within parent | Last name. Maximum length: 255 |
middle_name | string or null | Optional | Middle name, when any. Maximum length: 255 |
ownership_percentage | number | Optional | Ownership percentage; required for owners when the verification service asks for it. Format: double Maximum: 100 Minimum: 0 |
responsibilities | array | Required within parent | Roles the person holds in the entity. `submitter` marks the person who authorised the submission on the client side. |
responsibilities[] | string | Each item | One of: submitter, controllingOfficer, owner, director |
tax_id | string | Optional | Personal tax identifier. Maximum length: 64 |
Referenced models: Submit KYB information for a legal entity — request body — body data persons item address, Submit KYB information for a legal entity — request body — body data persons item identity documents, Submit KYB information for a legal entity — request body — body data persons item job title
Submit KYB information for a legal entity — request body — body data proof of authority
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Proof of Authority for the person acting on behalf of the entity. Required when the KYB state lists `PROOF_OF_AUTHORITY` as outstanding, unless `is_person_with_significant_control` is `true`. |
document | string | Required within parent | Handle of a document uploaded as `PROOF_OF_AUTHORITY`. Format: uuid |
meta_type | string | Required within parent | What kind of document evidences the authority: a power of attorney, a board resolution or minutes, or another document. One of: POWER_OF_ATTORNEY, RESOLUTION_OR_MINUTES, OTHER |
Submit KYB information for a legal entity — request body — body data questionnaire
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Answers to the industry questionnaire. Required when the KYB state lists the `INDUSTRY_QUESTIONNAIRE` requirement, refused when no questionnaire applies. |
answers | array | Required within parent | One answer per question that applies. Answers to questions that do not currently apply are ignored. |
answers[] | Model | Each item | Expand Submit KYB information for a legal entity — request body — body data questionnaire answers item |
template_id | integer | Required within parent | The `questionnaire.template_id` from the KYB state. |
Referenced models: Submit KYB information for a legal entity — request body — body data questionnaire answers item
Submit KYB information for a legal entity — request body — body data persons item address
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Residential address. |
city | string | Required within parent | City. Maximum length: 255 |
country | string | Required within parent | ISO 3166-1 alpha-2 country code. |
state | string or null | Optional | State or province. Required for US addresses, as a 2-letter ISO 3166-2 code (e.g. `CA`). Maximum length: 64 |
street | string | Required within parent | Street address. Maximum length: 255 |
zip | string | Required within parent | Postal code. Maximum length: 32 |
Submit KYB information for a legal entity — request body — body data persons item identity documents
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Identity document sides and selfie for the person, as upload handles. |
back | string | Optional | Handle of a document uploaded as `IDENTITY_DOCUMENT_BACK`. Not needed for passports. Format: uuid |
front | string | Optional | Handle of a document uploaded as `IDENTITY_DOCUMENT_FRONT`. Format: uuid |
selfie | string | Optional | Handle of a document uploaded as `SELFIE`. Format: uuid |
Submit KYB information for a legal entity — request body — body data persons item job title
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | Role of the person in the company, from the verification service vocabulary; required for controlling officers when the verification service asks for it. One of: FOUNDER, MAJOR_SHAREHOLDER, MINORITY_SHAREHOLDER, EQUITY_PARTNER, EXECUTIVE_C_LEVEL, MANAGING_DIRECTOR, DIRECTOR, PRESIDENT, VICE_PRESIDENT, SENIOR_MANAGEMENT_OFFICIAL, AUTHORIZED_SIGNATORY, OTHER |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: deel.legalentities_submitlegalentitykyb_v2026_10_12. Catalog operation: legalentities_submitlegalentitykyb_v2026_10_12. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["legal-entity:write"]
Pinned headers: {"X-Version": "2026-10-12"}