Skip to content

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.

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 os
from alter_sdk import App
from 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()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.legal_entity_idstringRequired within parentFormat: uuid
headersobjectRequired within parentAdditional keys: not allowed
headers.X-BetastringRequired within parentDefault: true
One of: true
bodyobjectOptional
body.dataModelRequired within parentExpand 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 media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Retrieve the KYB state of a legal entity — 200 response body

Referenced models: Retrieve the KYB state of a legal entity — 200 response body

17 more schemas are linked from the tables above, on the schema pages.

Submit KYB information for a legal entity — request body — body data
FieldTypePresenceDescription and constraints
$objectRoot
documentsModelOptionalExpand 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_datestringOptionalCompany formation date, `YYYY-MM-DD`.
Format: date
is_declaration_confirmedbooleanRequired within parentMust be true: the client confirms the information is accurate and complete.
is_person_with_significant_controlbooleanOptionalDeclares 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_acceptedbooleanRequired within parentMust be true: the client accepts the verification terms and conditions.
personsarrayRequired within parentPersons of significant control: directors, controlling officers, owners and the client-side submitter.
persons[]ModelEach itemExpand Submit KYB information for a legal entity — request body — body data persons item
proof_of_authorityModelOptionalExpand 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`.
questionnaireModelOptionalExpand 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_volumestringOptionalExpected 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
FieldTypePresenceDescription and constraints
$objectRoot
dataModelRequired within parentExpand 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
FieldTypePresenceDescription and constraints
$objectRootCompany documents as handles from the upload endpoint. Supply the ones the KYB state lists as required.
articles_of_incorporationstringOptionalHandle of a document uploaded as `ARTICLES_OF_INCORPORATION`.
Format: uuid
certificate_of_good_standingstringOptionalHandle of a document uploaded as `CERTIFICATE_OF_GOOD_STANDING`.
Format: uuid
company_bank_statementstringOptionalHandle of a document uploaded as `COMPANY_BANK_STATEMENT`.
Format: uuid
ultimate_beneficial_owner_formstringOptionalHandle of a document uploaded as `ULTIMATE_BENEFICIAL_OWNER_FORM`.
Format: uuid
Submit KYB information for a legal entity — request body — body data persons item
FieldTypePresenceDescription and constraints
$objectRoot
addressModelOptionalExpand Submit KYB information for a legal entity — request body — body data persons item address
Residential address.
citizenshipstringOptionalCitizenship as an ISO 3166-1 alpha-2 country code.
date_of_birthstringOptionalDate of birth, `YYYY-MM-DD`.
Format: date
first_namestringRequired within parentFirst name.
Maximum length: 255
identification_document_typestringOptionalType of the identity document supplied in `identity_documents`.
One of: PASSPORT, DRIVERS_LICENSE, ID_DOCUMENT
identity_documentsModelOptionalExpand 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_titleModelOptionalExpand 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_namestringRequired within parentLast name.
Maximum length: 255
middle_namestring or nullOptionalMiddle name, when any.
Maximum length: 255
ownership_percentagenumberOptionalOwnership percentage; required for owners when the verification service asks for it.
Format: double
Maximum: 100
Minimum: 0
responsibilitiesarrayRequired within parentRoles the person holds in the entity. `submitter` marks the person who authorised the submission on the client side.
responsibilities[]stringEach itemOne of: submitter, controllingOfficer, owner, director
tax_idstringOptionalPersonal 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
FieldTypePresenceDescription and constraints
$objectRootProof 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`.
documentstringRequired within parentHandle of a document uploaded as `PROOF_OF_AUTHORITY`.
Format: uuid
meta_typestringRequired within parentWhat 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
FieldTypePresenceDescription and constraints
$objectRootAnswers to the industry questionnaire. Required when the KYB state lists the `INDUSTRY_QUESTIONNAIRE` requirement, refused when no questionnaire applies.
answersarrayRequired within parentOne answer per question that applies. Answers to questions that do not currently apply are ignored.
answers[]ModelEach itemExpand Submit KYB information for a legal entity — request body — body data questionnaire answers item
template_idintegerRequired within parentThe `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
FieldTypePresenceDescription and constraints
$objectRootResidential address.
citystringRequired within parentCity.
Maximum length: 255
countrystringRequired within parentISO 3166-1 alpha-2 country code.
statestring or nullOptionalState or province. Required for US addresses, as a 2-letter ISO 3166-2 code (e.g. `CA`).
Maximum length: 64
streetstringRequired within parentStreet address.
Maximum length: 255
zipstringRequired within parentPostal code.
Maximum length: 32
Submit KYB information for a legal entity — request body — body data persons item identity documents
FieldTypePresenceDescription and constraints
$objectRootIdentity document sides and selfie for the person, as upload handles.
backstringOptionalHandle of a document uploaded as `IDENTITY_DOCUMENT_BACK`. Not needed for passports.
Format: uuid
frontstringOptionalHandle of a document uploaded as `IDENTITY_DOCUMENT_FRONT`.
Format: uuid
selfiestringOptionalHandle of a document uploaded as `SELFIE`.
Format: uuid
Submit KYB information for a legal entity — request body — body data persons item job title
FieldTypePresenceDescription and constraints
$stringRootRole 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

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"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.