> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Submit KYB Key People API > Declare the prepared key people of a KYB session and start the KYC verification of each party that needs it. ## OpenAPI ````yaml POST /v3/session/{sessionId}/kyb/parties/submit/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/session/{sessionId}/kyb/parties/submit/: post: tags: - Sessions summary: Submit the KYB party drafts description: >- Declare the stored drafts as the company's key people. This is the hosted Key People step under your API key: Didit decides from the role settings and ownership thresholds of the workflow which parties must be verified, creates one individual KYC session (or a KYB sub-session for a corporate owner) for each of them, sends the emails the workflow asks for, and advances the session. Each child session is billed like in the hosted flow. The drafts are consumed. Repeating the call after a successful submit changes nothing and answers `200` with `already_submitted: true` and the parties that already exist. The session must be on the Key People step. Send each person's `kyc_session_url` to them, or embed it. Requires `write:businesses`. operationId: post_v3_session_kyb_parties_submit parameters: - name: sessionId in: path required: true description: >- UUID of the Business Verification (KYB) session. It must belong to the application of the API key. schema: type: string format: uuid example: 33333333-4444-5555-6666-777777777777 - name: node_id in: query required: false description: >- Workflow node of the KYB step. Only needed when the workflow has more than one KYB node; by default Didit uses the session's own node. schema: type: string requestBody: required: false content: application/json: schema: type: object properties: locale: type: string maxLength: 10 description: >- Locale used to translate the response of the step the session advances to. example: locale: es responses: '200': description: Parties declared (or already declared). content: application/json: schema: type: object properties: valid: type: boolean next_step: type: string nullable: true description: Step the session is on. status: type: string description: Status of the business session. advanced: type: boolean description: >- `true` when this call declared the parties and advanced the session. already_submitted: type: boolean description: >- `true` when the parties had been declared by an earlier call. kyb_key_people_status: type: string parties: type: array items: $ref: '#/components/schemas/KYBKeyPeopleParty' example: valid: true next_step: FINISHED status: In Progress advanced: true already_submitted: false kyb_key_people_status: In Progress parties: [] '401': description: >- The scoped API key has expired. This is the only case that returns `401`: a missing, invalid or revoked key returns `403`. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. examples: Expired key: summary: The key's expiry date has passed value: detail: This API key has expired. '402': description: >- The organization has no credit left for the child verification sessions. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. example: detail: Insufficient credits. '403': description: >- Authentication or authorization failure. Missing, invalid and revoked keys return `403` (not `401`); so do a key of another application, a scoped key without the permission this endpoint needs, and a request from outside the key's IP allowlist. Distinguish them by `detail`. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. examples: Missing or invalid credentials: summary: No x-api-key header, or the key failed validation value: detail: >- Authentication credentials were not provided or are invalid. Other application: summary: >- A valid key that belongs to a different application than the session value: detail: You do not have permission to perform this action. Scoped key without decisions write: summary: 'Scoped key lacks decisions: write' value: detail: This API key has no write access to decisions. IP not allowed: summary: Request from outside the key's IP allowlist value: detail: This API key can't be used from this IP address. '404': description: >- The session does not exist, was deleted, belongs to another application or is outside a scoped key's limits; no detail distinguishes them. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. example: detail: Session not found. '409': description: >- `kyb_no_party_drafts`: there is nothing to submit. `kyb_parties_already_submitted`: drafts were added after the parties were declared. `kyb_step_mismatch`: the session is not on the Key People step (`next_step` names its step). `kyb_session_not_writable`: the session is finished. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. code: type: string next_step: type: string example: detail: There are no draft parties to submit. code: kyb_no_party_drafts '429': description: >- Rate limit exceeded: 300 write (POST, PATCH, DELETE) requests per minute per API key. Wait `Retry-After` seconds before retrying; the `X-RateLimit-*` headers show the budget. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. examples: Rate limited: summary: Budget for the current minute exhausted value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 example: 30 security: - ApiKeyAuth: [] x-codeSamples: - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.submit_kyb_parties( "33333333-4444-5555-6666-777777777777", locale="es", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.sessions.submitKybParties("33333333-4444-5555-6666-777777777777", { locale: "es", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.SubmitKYBParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsSubmitKYBPartiesParams{\n\tLocale: didit.String(\"es\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.SessionsSubmitKybPartiesParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().submitKybParties("33333333-4444-5555-6666-777777777777", SessionsSubmitKybPartiesParams.builder() .locale("es") .build()); System.out.println(result); - lang: php label: PHP source: >- sessions->submitKybParties('33333333-4444-5555-6666-777777777777', [ 'locale' => 'es', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.submit_kyb_parties( "33333333-4444-5555-6666-777777777777", locale: "es" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Sessions.SubmitKybPartiesAsync("33333333-4444-5555-6666-777777777777", new SessionsSubmitKybPartiesParams { Locale = "es", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBKeyPeopleParty: type: object description: >- A Key People party of a Business Verification (KYB) session, with its child verification. The same party appears in `key_people_checks[].submitted.parties[]` of the business session decision. required: - uuid - entity_type - source - name - is_active - is_skipped - requires_verification - roles - kyc_session_deleted - kyb_sub_session_deleted properties: uuid: type: string format: uuid description: Party identifier. entity_type: type: string enum: - person - company description: Whether the party is an individual or a company. source: type: string enum: - REGISTRY - USER description: >- `REGISTRY`: taken from the company registry. `USER`: entered in the Key People screen. name: type: string description: Display name of the party. first_name: type: string nullable: true description: First name (persons). last_name: type: string nullable: true description: Last name (persons). company_name: type: string nullable: true description: Company name (company parties). registration_number: type: string nullable: true description: Company registration number (company parties). email: type: string format: email nullable: true description: Email the verification link is sent to. nationality: type: string nullable: true description: Nationality for persons, country of incorporation for companies. phone_number: type: string nullable: true description: Phone number collected for the party. date_of_birth: type: string format: date nullable: true description: Date of birth (persons). position: type: string nullable: true description: Free-text job title (persons). custom_fields: type: object additionalProperties: true description: >- Workflow-defined custom fields collected for the party, keyed by field key. is_active: type: boolean description: Whether the party is active. is_skipped: type: boolean description: >- Whether the party is exempt from verification. Regenerating clears it. requires_verification: type: boolean description: >- Whether the role and ownership rules require a verification for this party. roles: type: array description: Roles the party holds in the company. items: type: object required: - role - ownership_percent - voting_percent properties: role: type: string enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - settlor - protector - company_officer - investor - other description: Role code. ownership_percent: type: number nullable: true description: Ownership percentage for this role, when known. voting_percent: type: number nullable: true description: Voting-rights percentage for this role, when known. kyc_session_id: type: string format: uuid nullable: true description: Child individual KYC session (persons). kyc_session_status: type: string nullable: true enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User - null description: >- Status of the child KYC session. A deleted session keeps the status it had when it was deleted. kyc_session_url: type: string format: uri nullable: true description: >- Hosted link of the child KYC session. `null` when there is none or it was deleted, and for a scoped API key without `sessions: write`. kyc_session_deleted: type: boolean description: The child KYC session was deleted, so it can never settle. kyb_sub_session_id: type: string format: uuid nullable: true description: Child KYB session (company parties). kyb_sub_session_status: type: string nullable: true enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User - null description: Status of the child KYB session. kyb_sub_session_url: type: string format: uri nullable: true description: >- Hosted link of the child KYB session, with the same `null` rules as `kyc_session_url`. kyb_sub_session_deleted: type: boolean description: Company-party counterpart of `kyc_session_deleted`. verification_workflow_type: type: string nullable: true enum: - kyc - kyb - adaptive_age_verification - biometric_authentication - address_verification - questionnaire_verification - email_verification - phone_verification - null description: Type of the workflow the child session runs. verification_workflow_id: type: string format: uuid nullable: true description: Workflow the child session runs. verification_workflow_label: type: string nullable: true description: Label of that workflow. verification_workflow_features: type: array nullable: true description: Features of the child session's workflow with their current status. items: type: object required: - feature - status properties: feature: type: string description: Feature code, for example `ID_VERIFICATION` or `LIVENESS`. status: type: string description: Feature status, `Not Finished` until it runs. didit_internal_id: type: string format: uuid nullable: true description: Didit's identifier of the verified person, once known. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.