Create Entity Onboarding (Banking Connectivity)

POST

banking

entities

{entity_id}

onboardings

curl --request POST \
  --url https://api-sandbox.y.uno/v1/banking/entities/{entity_id}/onboardings \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "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"
        }
      }
    }
  ]
}
'

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

{
  "code": "VALIDATION_ERROR",
  "messages": [
    "compliance_declaration is required for ONE_STEP onboarding"
  ],
  "http_code": 400
}

{
  "code": "ENTITY_NOT_FOUND",
  "messages": [
    "Entity not found"
  ],
  "http_code": 404
}

Onboard an existing 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 for the full list of supported document types. Monitor progress via Get Entity Onboarding Status or webhook events. See Onboarding statuses for the full status lifecycle.

Authorizations

public-api-key

string

header

required

private-secret-key

string

header

required

Headers

x-idempotency-key

string

required

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 for details (UUID).

Path Parameters

entity_id

string

required

The id of the entity obtained from Create Entity.

Body

application/json

account_id

string

required

The unique identifier of the merchant's Yuno account (UUID, 36 characters).

Example:

"550e8400-e29b-41d4-a716-446655440000"

yuno_connection_id

string

required

The pre-configured Banking Connectivity provider connection identifier.

Example:

"conn_550e8400-e29b-41d4-a716-446655440001"

onboarding_type

enum<string>

required

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.

Available options:

ONE_STEP,

PREVIOUSLY_ONBOARDED

Example:

"ONE_STEP"

compliance_declaration

object

Legal agreements accepted by the entity. Required for ONE_STEP onboarding.

Show child attributes

risk_assessment

object

Pre-existing compliance screening results provided by the merchant.

Show child attributes

source_of_funds

object

AML/KYC information about the source of funds.

Show child attributes

documentation

object[]

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.

Show child attributes

Response

⌘I

curl --request POST \
  --url https://api-sandbox.y.uno/v1/banking/entities/{entity_id}/onboardings \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "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"
        }
      }
    }
  ]
}
'

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

{
  "code": "VALIDATION_ERROR",
  "messages": [
    "compliance_declaration is required for ONE_STEP onboarding"
  ],
  "http_code": 400
}

{
  "code": "ENTITY_NOT_FOUND",
  "messages": [
    "Entity not found"
  ],
  "http_code": 404
}

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

FX Rates

Banking Connectivity

Webhooks

Create Entity Onboarding (Banking Connectivity)

Onboarding types

Authorizations

Headers

Path Parameters

Body

Response

​Onboarding types

Authorizations

Headers

Path Parameters

Body

Response

Onboarding types