> ## Documentation Index > Fetch the complete documentation index at: https://docs.y.uno/llms.txt > Use this file to discover all available pages before exploring further. # Create Entity Onboarding (Banking Connectivity) Onboard an existing [Entity](/reference/create-entity) with a Banking Connectivity provider. ## Onboarding types * **`ONE_STEP`**: Submit all information, compliance declarations, risk assessment, and documents at once. The provider processes immediately. * **`PREVIOUSLY_ONBOARDED`**: Generate an internal Yuno onboarding ID without contacting the provider. Use when the entity was already onboarded externally. For `ONE_STEP`, include `compliance_declaration`, `risk_assessment`, `source_of_funds`, and `documentation`. See [Documentation types](/reference/banking-connectivity#documentation-types) for the full list of supported document types. Monitor progress via [Get Entity Onboarding Status](/reference/get-entity-onboarding-status) or webhook events. See [Onboarding statuses](/reference/banking-connectivity#onboarding-statuses) for the full status lifecycle. ## OpenAPI ````yaml openapi/banking-connectivity/entity-onboarding-banking-connectivity/create-entity-onboarding.json POST /banking/entities/{entity_id}/onboardings openapi: 3.0.0 info: version: 1.0.0 title: Banking Connectivity servers: - url: https://api-sandbox.y.uno/v1 security: - public-api-key: [] private-secret-key: [] paths: /banking/entities/{entity_id}/onboardings: post: tags: - Entity Onboarding (Banking Connectivity) summary: Create Entity Onboarding (Banking Connectivity) operationId: post_v1-banking-connectivity-entities-entity-id-onboardings parameters: - in: path name: entity_id schema: type: string required: true description: >- The `id` of the entity obtained from [Create Entity](/reference/create-entity). - in: header name: x-idempotency-key schema: type: string description: >- Unique identifier used in HTTP headers to ensure that a request is processed only once, even if it is retried due to network issues or timeouts. See [authentication](/reference/authentication#idempotency) for details (UUID). required: true requestBody: content: application/json: schema: type: object required: - account_id - yuno_connection_id - onboarding_type properties: account_id: type: string description: >- The unique identifier of the merchant's Yuno account (UUID, 36 characters). example: 550e8400-e29b-41d4-a716-446655440000 yuno_connection_id: type: string description: >- The pre-configured Banking Connectivity provider connection identifier. example: conn_550e8400-e29b-41d4-a716-446655440001 onboarding_type: type: string description: >- The onboarding workflow type. `ONE_STEP` submits all information at once for provider processing. `PREVIOUSLY_ONBOARDED` generates an internal Yuno ID without contacting the provider. enum: - ONE_STEP - PREVIOUSLY_ONBOARDED example: ONE_STEP compliance_declaration: type: object description: >- Legal agreements accepted by the entity. Required for `ONE_STEP` onboarding. properties: terms_of_service: type: object description: Terms of service acceptance record. required: - accepted - accepted_at properties: accepted: type: boolean description: Whether the terms of service were accepted. example: true version: type: string description: The version of terms accepted. example: 1.2.0 accepted_at: type: string description: The timestamp when accepted (ISO 8601). example: '2026-02-01T10:00:00Z' accepted_ip: type: string description: The IP address from which the terms were accepted. example: 192.168.1.1 privacy_policy: type: object description: Privacy policy acceptance record. required: - accepted - accepted_at properties: accepted: type: boolean description: Whether the privacy policy was accepted. example: true version: type: string description: The version of the privacy policy accepted. example: 2.1.0 accepted_at: type: string description: The timestamp when accepted (ISO 8601). example: '2026-02-01T10:00:00Z' accepted_ip: type: string description: The IP address from which the policy was accepted. example: 192.168.1.1 risk_assessment: type: object description: >- Pre-existing compliance screening results provided by the merchant. properties: assessed_at: type: string description: >- The timestamp when the assessment was performed (ISO 8601). example: '2026-02-01T10:00:00Z' pep_status: type: object description: Politically Exposed Person (PEP) screening results. properties: is_pep: type: boolean description: Whether the entity is a PEP. example: false pep_level: type: string nullable: true description: The PEP classification level. enum: - DIRECT - CLOSE_ASSOCIATE - FAMILY_MEMBER - null example: null position: type: string nullable: true description: The political role or position, if applicable. example: null country: type: string nullable: true description: The country of PEP status. example: null rca_status: type: object description: Risk Classification Assessment results. properties: risk_level: type: string description: The assessed risk level. enum: - LOW - MEDIUM - HIGH example: LOW classified_at: type: string description: The timestamp when classified (ISO 8601). example: '2026-02-01T10:00:00Z' assessed_by: type: string description: The name of the assessor or team. example: Merchant Compliance Team sanctions_screening: type: object description: Sanctions list screening results. properties: appears_on_sanctions_list: type: boolean description: Whether the entity appears on any sanctions list. example: false sanctions_list_name: type: string nullable: true description: The name of the sanctions list, if matched. example: null screened_at: type: string description: >- The timestamp when the screening was performed (ISO 8601). example: '2026-02-01T09:00:00Z' source_of_funds: type: object description: AML/KYC information about the source of funds. properties: primary_source: type: string description: The primary source of funds. enum: - EMPLOYMENT_SALARY - BUSINESS_INCOME - INVESTMENTS - RENTAL_INCOME - PENSION - GOVERNMENT_BENEFITS - INHERITANCE - FAMILY_SUPPORT - SAVINGS - LOTTERY_GAMBLING - SALE_OF_ASSETS - CRYPTOCURRENCY - FREELANCE_CONSULTING - OTHER example: EMPLOYMENT_SALARY secondary_sources: type: array description: Additional sources of funds. items: type: string example: - INVESTMENTS description: type: string description: A detailed explanation of the source of funds. example: >- Primary income from full-time employment as software engineer, supplemented by stock portfolio dividends estimated_annual_income: type: object description: The estimated annual income. properties: amount: type: number description: The annual income amount. example: 175000 currency: type: string description: >- The currency ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)). example: USD documentation: type: array description: >- KYC/KYB documents. Each item uses a `type` discriminator to determine which sub-object to populate. Supported types: `IDENTITY_DOCUMENT`, `PROOF_OF_ADDRESS`, `BANK_STATEMENT`, `BUSINESS_DOCUMENT`, `TAX_INFORMATION`, `FINANCIAL_DOCUMENT`, `BIOMETRIC_VERIFICATION`, `EMPLOYMENT_INFORMATION`. items: type: object required: - type properties: type: type: string description: The document type discriminator. enum: - IDENTITY_DOCUMENT - PROOF_OF_ADDRESS - BANK_STATEMENT - BUSINESS_DOCUMENT - TAX_INFORMATION - FINANCIAL_DOCUMENT - BIOMETRIC_VERIFICATION - EMPLOYMENT_INFORMATION example: IDENTITY_DOCUMENT identity_document: type: object description: >- Identity document details. Provide when `type` is `IDENTITY_DOCUMENT`. properties: subtype: type: string description: The identity document subtype. enum: - PASSPORT - DRIVERS_LICENSE - NATIONAL_ID - STATE_ID example: DRIVERS_LICENSE document_number: type: string description: The document number. example: D1234567 issuing_country: type: string description: >- The issuing country ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US issuing_state: type: string description: The issuing state or province. example: CA issued_at: type: string description: The issue date (YYYY-MM-DD). example: '2020-01-15' expires_at: type: string description: The expiration date (YYYY-MM-DD). example: '2028-01-15' front_image: type: object description: The front image of the document. properties: file_name: type: string example: license_front.jpg content_type: type: string example: image/jpeg content: type: string description: Base64-encoded file content. example: base64_encoded_content back_image: type: object description: The back image of the document. properties: file_name: type: string example: license_back.jpg content_type: type: string example: image/jpeg content: type: string description: Base64-encoded file content. example: base64_encoded_content proof_of_address: type: object description: >- Proof of address details. Provide when `type` is `PROOF_OF_ADDRESS`. properties: subtype: type: string description: The proof of address subtype. enum: - UTILITY_BILL - BANK_STATEMENT - LEASE_AGREEMENT - MORTGAGE_STATEMENT - TAX_DOCUMENT example: UTILITY_BILL provider_name: type: string description: The utility or service provider name. example: PG&E bill_type: type: string description: The type of bill. example: ELECTRICITY issued_at: type: string description: The bill issue date (YYYY-MM-DD). example: '2026-01-01' account_number: type: string description: The account number with the provider. example: ACC-123456 verified_address: type: object description: The address shown on the document. properties: address_line_1: type: string example: 123 Main St city: type: string example: San Francisco state: type: string example: CA zip_code: type: string example: '94102' country: type: string example: US file: type: object description: The document file. properties: file_name: type: string example: utility_bill.pdf content_type: type: string example: application/pdf content: type: string description: Base64-encoded file content. example: base64_encoded_content bank_statement: type: object description: >- Bank statement details. Provide when `type` is `BANK_STATEMENT`. properties: bank_name: type: string description: The bank name. example: Chase Bank account_number_last_4: type: string description: Last 4 digits of the account number. example: '1234' statement_period_start: type: string description: The statement period start date (YYYY-MM-DD). example: '2025-12-01' statement_period_end: type: string description: The statement period end date (YYYY-MM-DD). example: '2025-12-31' file: type: object properties: file_name: type: string example: bank_statement_dec_2025.pdf content_type: type: string example: application/pdf content: type: string description: Base64-encoded file content. example: base64_encoded_content business_document: type: object description: >- Business document details. Provide when `type` is `BUSINESS_DOCUMENT`. properties: subtype: type: string enum: - ARTICLES_OF_INCORPORATION - BUSINESS_LICENSE - EIN_CONFIRMATION - OPERATING_AGREEMENT - CERTIFICATE_OF_GOOD_STANDING example: ARTICLES_OF_INCORPORATION registration_number: type: string description: The business registration number. example: REG-2020-12345 registered_at: type: string description: The registration date (YYYY-MM-DD). example: '2020-01-15' issuing_state: type: string description: The issuing state. example: CA issuing_authority: type: string description: The issuing authority. example: California Secretary of State file: type: object properties: file_name: type: string example: articles_of_incorporation.pdf content_type: type: string example: application/pdf content: type: string description: Base64-encoded file content. example: base64_encoded_content tax_information: type: object description: >- Tax information details. Provide when `type` is `TAX_INFORMATION`. properties: tax_records: type: array description: Tax identification records. items: type: object properties: country: type: string example: US tax_id: type: string example: 123-45-6789 tax_id_type: type: string enum: - SSN - EIN - ITIN - VAT - ABN - NIF - TIN - OTHER example: SSN is_primary: type: boolean example: true tax_document_type: type: string description: The type of tax document. enum: - W9 - '1099' - TAX_RETURN - SSN_CARD - ITIN_LETTER - EIN_CONFIRMATION - VAT_CERTIFICATE example: W9 tax_year: type: string description: The tax year. example: '2025' issuing_authority: type: string description: The tax authority. example: IRS file: type: object properties: file_name: type: string example: w9_form.pdf content_type: type: string example: application/pdf content: type: string description: Base64-encoded file content. example: base64_encoded_content financial_document: type: object description: >- Financial document details. Provide when `type` is `FINANCIAL_DOCUMENT`. properties: subtype: type: string enum: - BALANCE_SHEET - PROFIT_LOSS_STATEMENT - CASH_FLOW_STATEMENT - FINANCIAL_AUDIT example: BALANCE_SHEET period_start: type: string description: Period start date (YYYY-MM-DD). example: '2025-01-01' period_end: type: string description: Period end date (YYYY-MM-DD). example: '2025-12-31' fiscal_year: type: string example: '2025' audited: type: boolean description: Whether the document has been audited. example: false auditor_name: type: string nullable: true description: The auditor name, if audited. example: null file: type: object properties: file_name: type: string example: balance_sheet_2025.pdf content_type: type: string example: application/pdf content: type: string description: Base64-encoded file content. example: base64_encoded_content biometric_verification: type: object description: >- Biometric verification details. Provide when `type` is `BIOMETRIC_VERIFICATION`. properties: verification_method: type: string enum: - FACIAL_RECOGNITION - FINGERPRINT - VOICE - IRIS_SCAN example: FACIAL_RECOGNITION capture_method: type: string enum: - LIVE_CAPTURE - UPLOADED example: LIVE_CAPTURE capture_timestamp: type: string description: When the biometric was captured (ISO 8601). example: '2026-02-01T10:00:00Z' liveness_check_passed: type: boolean description: Whether the liveness check passed. example: true confidence_score: type: number description: The verification confidence score (0-1). example: 0.98 verification_provider: type: string description: The biometric verification provider. example: Onfido live_image: type: object properties: file_name: type: string example: live_capture.jpg content_type: type: string example: image/jpeg content: type: string description: Base64-encoded file content. example: base64_encoded_content reference_image: type: object properties: file_name: type: string example: id_photo_reference.jpg content_type: type: string example: image/jpeg content: type: string description: Base64-encoded file content. example: base64_encoded_content employment_information: type: object description: >- Employment information details. Provide when `type` is `EMPLOYMENT_INFORMATION`. properties: status: type: string description: The employment status. enum: - EMPLOYED - SELF_EMPLOYED - UNEMPLOYED - RETIRED - STUDENT example: EMPLOYED employer_name: type: string description: The employer name. example: Tech Corp Inc occupation: type: string description: The job title or occupation. example: Senior Software Engineer industry: type: string description: The industry sector. example: TECHNOLOGY started_at: type: string description: The employment start date (YYYY-MM-DD). example: '2020-03-15' annual_income: type: object description: The annual income from this employment. properties: amount: type: number example: 150000 currency: type: string example: USD verification_document: type: object description: Employment verification document. properties: file_name: type: string example: employment_letter.pdf content_type: type: string example: application/pdf content: type: string description: Base64-encoded file content. example: base64_encoded_content examples: Create entity onboarding: summary: Create entity onboarding value: account_id: 550e8400-e29b-41d4-a716-446655440000 yuno_connection_id: conn_550e8400-e29b-41d4-a716-446655440001 onboarding_type: ONE_STEP compliance_declaration: terms_of_service: accepted: true version: 1.2.0 accepted_at: '2026-02-01T10:00:00Z' accepted_ip: 192.168.1.1 privacy_policy: accepted: true version: 2.1.0 accepted_at: '2026-02-01T10:00:00Z' accepted_ip: 192.168.1.1 risk_assessment: assessed_at: '2026-02-01T10:00:00Z' pep_status: is_pep: false pep_level: null position: null country: null rca_status: risk_level: LOW classified_at: '2026-02-01T10:00:00Z' assessed_by: Merchant Compliance Team sanctions_screening: appears_on_sanctions_list: false sanctions_list_name: null screened_at: '2026-02-01T09:00:00Z' source_of_funds: primary_source: EMPLOYMENT_SALARY secondary_sources: - INVESTMENTS description: >- Primary income from full-time employment as software engineer, supplemented by stock portfolio dividends estimated_annual_income: amount: 175000 currency: USD documentation: - type: IDENTITY_DOCUMENT identity_document: subtype: DRIVERS_LICENSE document_number: D1234567 issuing_country: US issuing_state: CA issued_at: '2020-01-15' expires_at: '2028-01-15' front_image: file_name: license_front.jpg content_type: image/jpeg content: base64_encoded_content back_image: file_name: license_back.jpg content_type: image/jpeg content: base64_encoded_content - type: PROOF_OF_ADDRESS proof_of_address: subtype: UTILITY_BILL provider_name: PG&E bill_type: ELECTRICITY issued_at: '2026-01-01' account_number: ACC-123456 verified_address: address_line_1: 123 Main St city: San Francisco state: CA zip_code: '94102' country: US file: file_name: utility_bill.pdf content_type: application/pdf content: base64_encoded_content - type: BANK_STATEMENT bank_statement: bank_name: Chase Bank account_number_last_4: '1234' statement_period_start: '2025-12-01' statement_period_end: '2025-12-31' file: file_name: bank_statement_dec_2025.pdf content_type: application/pdf content: base64_encoded_content - type: TAX_INFORMATION tax_information: tax_records: - country: US tax_id: 123-45-6789 tax_id_type: SSN is_primary: true tax_document_type: W9 tax_year: '2025' issuing_authority: IRS file: file_name: w9_form.pdf content_type: application/pdf content: base64_encoded_content - type: BIOMETRIC_VERIFICATION biometric_verification: verification_method: FACIAL_RECOGNITION capture_method: LIVE_CAPTURE capture_timestamp: '2026-02-01T10:00:00Z' liveness_check_passed: true confidence_score: 0.98 verification_provider: Onfido live_image: file_name: live_capture.jpg content_type: image/jpeg content: base64_encoded_content reference_image: file_name: id_photo_reference.jpg content_type: image/jpeg content: base64_encoded_content - type: EMPLOYMENT_INFORMATION employment_information: status: EMPLOYED employer_name: Tech Corp Inc occupation: Senior Software Engineer industry: TECHNOLOGY started_at: '2020-03-15' annual_income: amount: 150000 currency: USD verification_document: file_name: employment_letter.pdf content_type: application/pdf content: base64_encoded_content Previously onboarded: summary: Previously onboarded value: account_id: 550e8400-e29b-41d4-a716-446655440000 yuno_connection_id: conn_550e8400-e29b-41d4-a716-446655440001 onboarding_type: PREVIOUSLY_ONBOARDED responses: '200': description: '' '201': content: application/json: schema: type: object properties: id: type: string example: onb_990e8400-e29b-41d4-a716-446655440000 entity_id: type: string example: ent_660e8400-e29b-41d4-a716-446655440000 yuno_account_id: type: string example: 550e8400-e29b-41d4-a716-446655440000 provider: type: object properties: entity_id: type: string example: col_entity_onboarded_123 status: type: string example: verification_pending onboarding_type: type: string example: ONE_STEP status: type: string example: PENDING requirements: type: array items: type: object properties: {} created_at: type: string example: '2026-02-01T10:00:00Z' updated_at: type: string example: '2026-02-01T10:00:00Z' expires_at: type: string example: '2026-02-08T10:00:00Z' examples: Created (Entity onboarding): summary: Created (Entity onboarding) value: id: onb_990e8400-e29b-41d4-a716-446655440000 entity_id: ent_660e8400-e29b-41d4-a716-446655440000 yuno_account_id: 550e8400-e29b-41d4-a716-446655440000 provider: entity_id: col_entity_onboarded_123 status: verification_pending onboarding_type: ONE_STEP status: PENDING requirements: [] created_at: '2026-02-01T10:00:00Z' updated_at: '2026-02-01T10:00:00Z' expires_at: '2026-02-08T10:00:00Z' description: Created '400': content: application/json: schema: type: object properties: code: type: string example: VALIDATION_ERROR messages: type: array items: type: string example: >- compliance_declaration is required for ONE_STEP onboarding http_code: type: integer example: 400 default: 0 examples: Bad Request: summary: Bad Request value: code: VALIDATION_ERROR messages: - >- compliance_declaration is required for ONE_STEP onboarding http_code: 400 description: Bad Request '404': content: application/json: schema: type: object properties: code: type: string example: ENTITY_NOT_FOUND messages: type: array items: type: string example: Entity not found http_code: type: integer example: 404 default: 0 examples: Not Found: summary: Not Found value: code: ENTITY_NOT_FOUND messages: - Entity not found http_code: 404 description: Not Found components: securitySchemes: public-api-key: type: apiKey in: header name: public-api-key private-secret-key: type: apiKey in: header name: private-secret-key ````