Skip to main content
POST
/
v1
/
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"
}
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.

​
risk_assessment
object

Pre-existing compliance screening results provided by the merchant.

​
source_of_funds
object

AML/KYC information about the source of funds.

​
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.

Response