KYC / KYB Verification

Yativo provides identity verification for both individuals (KYC) and businesses (KYB). Verified customers unlock virtual accounts and payment rails. You can submit verification data programmatically via API or redirect customers to a hosted verification experience.

Environment base URLs

Environment	Base URL
Production	`https://api.yativo.com/api/v1`
Sandbox	`https://smtp.yativo.com/api/v1`
KYC Platform	`https://kyc.yativo.com`

Access tokens expire after 600 seconds. Include Authorization: Bearer {token} in every authenticated request.

Idempotency

Include an Idempotency-Key header on all POST, PUT, and PATCH requests to prevent duplicate submissions.

Verification approaches

Approach	Description	Best for
API Submission	Programmatically submit all customer data	Full control, native UI
Hosted KYC/KYB Links	Redirect customers to `https://kyc.yativo.com`	Quick integration, iframe embed

Hosted links:

Individual: https://kyc.yativo.com/individual/{customer_id}
Business: https://kyc.yativo.com/business/{customer_id}

Verification flow

Create Customer — POST /customer
Submit KYC or KYB — POST individual-kyc/submit or POST business-kyc/submit
Check Status — GET /customer/kyc/{customer_id}
Customer Approved — Endorsements activated, payment rails available

Individual KYC — Submit via API

The KYC submission endpoint is hosted on the KYC platform at https://kyc.yativo.com, not the main API base URL.

POST https://kyc.yativo.com/api/individual-kyc/submit

Required headers:

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer {token}`
`Idempotency-Key`	A unique key for this request

Identity fields

customer_id

string

required

The customer UUID from POST /customer.

type

string

required

Must be "individual".

signed_agreement_id

string

Optional agreement UUID. If omitted, it is auto-generated by Yativo.

first_name

string

required

Customer’s first name.

last_name

string

required

Customer’s last name.

middle_name

string

Customer’s middle name (optional).

string

required

Customer’s email address.

phone

string

required

Phone number without country code.

calling_code

string

required

Country calling code, e.g. "+1", "+44".

gender

string

required

One of: "male", "female", "other".

birth_date

string

required

Date of birth in YYYY-MM-DD format.

nationality

string

required

ISO 3166-1 alpha-2 country code (e.g. "US", "BR", "GB").

taxId

string

required

Tax identification number for the customer.

selfie_image

string

required

URL or base64-encoded selfie image of the customer.

Residential address

residential_address

object

required

Customer’s residential address.

Show residential_address fields

street_line_1

string

required

Street address line 1.

street_line_2

string

Street address line 2 (optional).

city

string

required

City.

state

string

required

State or province.

postal_code

string

required

Postal or ZIP code.

country

string

required

ISO 3166-1 alpha-2 country code.

proof_of_address_file

string

required

URL or base64-encoded proof of address document (utility bill, bank statement, etc.).

Identifying information

identifying_information

array

required

At least one government-issued ID document is required.

Show identifying_information item fields

type

string

required

Document type: "passport", "national_id", or "drivers_license".

issuing_country

string

required

ISO 3166-1 alpha-2 country code of the issuing country.

number

string

required

Document number.

date_issued

string

required

Issue date in YYYY-MM-DD format.

expiration_date

string

required

Expiration date in YYYY-MM-DD format.

image_front_file

string

required

URL or base64-encoded front image of the document.

image_back_file

string

URL or base64-encoded back image of the document (required for national_id and drivers_license).

Financial information

employment_status

string

required

One of: "Employed", "self_employed", "unemployed", "retired", "student".

most_recent_occupation_code

string

required

Occupation code from GET /auth/occupation-codes. Example: "132011" (Accountant).

expected_monthly_payments_usd

string

required

Expected monthly payment volume: "LessThan5K", "5KTo50K", or "MoreThan50K".

source_of_funds

string

required

Source of funds: "Salary", "Business", "Investment", "Savings", or other applicable value.

account_purpose

string

required

Purpose for the account, e.g. "ReceiveSalary", "BusinessPayments".

account_purpose_other

string

Required when account_purpose is "other".

acting_as_intermediary

boolean

required

Whether the customer is acting as an intermediary for third parties.

Virtual account preferences

usd_virtual_account

boolean

required

Request a USD virtual account for this customer.

eur_virtual_account

boolean

required

Request a EUR virtual account for this customer.

eurde_virtual_account

boolean

required

Request a EUR/DE virtual account. If true, both usd_virtual_account and eur_virtual_account must be false.

gbp_virtual_account

boolean

Request a GBP virtual account.

Optional fields

uploaded_documents

array

Additional supporting documents.

Show uploaded_documents item fields

type

string

required

Document type identifier.

file

string

required

URL or base64-encoded document file.

sumsub_token

string

Optional Sumsub token for submissions that include liveness checks.

curl -X POST 'https://kyc.yativo.com/api/individual-kyc/submit' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: kyc-alex-smith-2026' \
  -d '{
    "customer_id": "c586066b-0f29-468f-b775-15483871a202",
    "type": "individual",
    "first_name": "Alex",
    "last_name": "Smith",
    "email": "alex.smith@example.com",
    "phone": "5551234567",
    "calling_code": "+1",
    "gender": "male",
    "nationality": "US",
    "birth_date": "1990-01-01",
    "taxId": "998877665",
    "selfie_image": "https://example.com/docs/selfie.jpg",
    "residential_address": {
      "street_line_1": "123 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "90210",
      "country": "US",
      "proof_of_address_file": "https://example.com/docs/proof.jpg"
    },
    "identifying_information": [
      {
        "type": "passport",
        "issuing_country": "US",
        "number": "P00012345",
        "date_issued": "2020-01-01",
        "expiration_date": "2030-01-01",
        "image_front_file": "https://example.com/docs/front.jpg"
      }
    ],
    "employment_status": "Employed",
    "most_recent_occupation_code": "132011",
    "expected_monthly_payments_usd": "LessThan5K",
    "source_of_funds": "Salary",
    "account_purpose": "ReceiveSalary",
    "acting_as_intermediary": false,
    "eur_virtual_account": false,
    "usd_virtual_account": true,
    "eurde_virtual_account": false
  }'

{
  "success": true,
  "message": "KYC submission received successfully",
  "errors": {
    "submission": {
      "id": "sub_8f3b2a1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "type": "individual",
      "status": "submitted",
      "customer_id": "c586066b-0f29-468f-b775-15483871a202",
      "first_name": "Alex",
      "last_name": "Smith",
      "email": "alex.smith@example.com",
      "endorsements": [
        {
          "service": "base",
          "status": "pending",
          "link": "https://kyc.yativo.com/endorsement/base/c586066b-0f29-468f-b775-15483871a202"
        },
        {
          "service": "usd_latam",
          "status": "pending",
          "link": "https://kyc.yativo.com/endorsement/usd_latam/c586066b-0f29-468f-b775-15483871a202"
        }
      ],
      "created_at": "2026-04-02T10:00:00.000000Z"
    }
  }
}

Business KYB — Submit via API

POST https://kyc.yativo.com/api/business-kyc/submit

Business identity fields

customer_id

string

required

The customer UUID from POST /customer.

type

string

required

Must be "business".

signed_agreement_id

string

Optional agreement UUID. If omitted, it is auto-generated by Yativo.

business_legal_name

string

required

The official registered legal name of the business.

business_description

string

required

A description of what the business does.

string

required

Business email address.

business_type

string

required

One of: "cooperative", "corporation", "llc", "partnership", "sole_prop", "trust", "other".

registration_number

string

required

Official government registration or incorporation number.

incorporation_date

string

required

Date of incorporation in ISO 8601 format (e.g. "2015-06-15").

business_trade_name

string

Trade name or DBA (“doing business as”) name (optional).

tax_id

string

Business tax identification number (optional).

statement_descriptor

string

How the business name appears on customer statements (optional).

phone_calling_code

string

Country calling code for business phone (optional).

phone_number

string

Business phone number (optional).

business_industry

string

Industry category of the business (optional).

primary_website

string

Business website URL (optional).

is_dao

boolean

Whether the business is a DAO (Decentralized Autonomous Organization) (optional).

has_material_intermediary_ownership

boolean

Whether there is material intermediary ownership structure (optional).

Business addresses

registered_address

object

required

The official registered address of the business.

Show registered_address fields

street_line_1

string

required

Street address line 1.

street_line_2

string

Street address line 2 (optional).

city

string

required

City.

state

string

State or province (optional).

postal_code

string

Postal or ZIP code (optional).

country

string

required

ISO 3166-1 alpha-2 country code.

proof_of_address_file

string

URL or base64-encoded proof of address document (optional).

physical_address

object

required

The physical operating address of the business.

Show physical_address fields

street_line_1

string

required

Street address line 1.

street_line_2

string

Street address line 2 (optional).

city

string

required

City.

state

string

required

State or province.

postal_code

string

required

Postal or ZIP code.

country

string

required

ISO 3166-1 alpha-2 country code.

proof_of_address_file

string

required

URL or base64-encoded proof of address document.

Associated persons

associated_persons

array

required

At least one associated person (beneficial owner, director, or signer) is required.

Show associated_persons item fields

first_name

string

required

Person’s first name.

last_name

string

required

Person’s last name.

birth_date

string

required

Date of birth in YYYY-MM-DD format.

nationality

string

required

ISO 3166-1 alpha-2 country code.

string

required

Person’s email address.

phone

string

Phone number (optional).

title

string

Job title, e.g. "CEO", "Director" (optional).

ownership_percentage

number

Required if has_ownership is true.

relationship_established_at

string

Relationship start date in YYYY-MM-DD format (optional).

residential_address

object

required

Person’s residential address (same structure as individual).

identifying_information

array

Optional ID documents.

Show identifying_information item fields

type

string

"passport", "national_id", or "drivers_license".

issuing_country

string

ISO 3166-1 alpha-2 country code.

number

string

Document number.

expiration

string

Expiration date in YYYY-MM-DD format.

image_front

string

URL or base64-encoded front image.

image_back

string

URL or base64-encoded back image.

has_ownership

boolean

required

Whether this person has ownership in the business.

has_control

boolean

required

Whether this person has control over the business.

is_signer

boolean

required

Whether this person is an authorized signer.

is_director

boolean

required

Whether this person is a director.

Business financial information

account_purpose

string

required

Purpose of the business account, e.g. "BusinessPayments".

account_purpose_other

string

Required when account_purpose is "other".

source_of_funds

string

required

Source of business funds, e.g. "Business", "Investment".

estimated_annual_revenue_usd

string

Estimated annual revenue in USD (optional).

expected_monthly_payments_usd

number

Expected monthly payment volume in USD (optional).

operates_in_prohibited_countries

string

Optional value: "yes" or "no".

ownership_threshold

number

Ownership percentage threshold used for reporting (optional).

high_risk_activities

array

required

Array of high-risk activity strings the business is involved in (can be empty array).

high_risk_activities_explanation

string

Explanation of any high-risk activities listed above.

conducts_money_services

boolean

Whether the business conducts money services (optional).

conducts_money_services_description

string

Required when conducts_money_services is true.

compliance_screening_explanation

string

Additional compliance context (optional).

regulated_activities_description

string

Description of regulated activities (optional).

primary_regulatory_authority_country

string

Country of the primary regulatory authority (optional).

primary_regulatory_authority_name

string

Name of the primary regulatory authority (optional).

license_number

string

Regulatory license number (optional).

Business documents

documents

array

required

At least one business document is required.

Show documents item fields

purpose

string

required

One of: "business_registration", "tax_documents", "compliance_documents", "financial_statements".

description

string

required

Description of the document.

file

string

URL or base64-encoded document file (optional).

Optional business fields

identifying_information

array

Business-level identifying documents (optional).

extra_documents

array

Additional supporting documents (optional).

Show extra_documents item fields

type

string

required

One of: "articles_of_association", "operating_address_proof", "shareholding_structure", "identity_proof".

description

string

required

Description of the document.

file

string

required

URL or base64-encoded document file.

extra_business_info

object

Additional business information fields (optional).

collections_data

object

Collections configuration data (optional).

payouts_data

object

Payouts configuration data (optional).

curl -X POST 'https://kyc.yativo.com/api/business-kyc/submit' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: kyb-acme-corp-2026' \
  -d '{
    "customer_id": "d47f8a2b-1c3e-4f5a-9b8c-7d6e5f4a3b2c",
    "type": "business",
    "business_legal_name": "Acme Corporation LLC",
    "business_description": "International payment processing and financial services",
    "email": "compliance@acme.com",
    "business_type": "llc",
    "registration_number": "LLC-2015-987654",
    "incorporation_date": "2015-06-15",
    "business_trade_name": "Acme Payments",
    "tax_id": "47-1234567",
    "primary_website": "https://acme.com",
    "registered_address": {
      "street_line_1": "100 Corporate Blvd",
      "city": "Miami",
      "state": "FL",
      "postal_code": "33101",
      "country": "US"
    },
    "physical_address": {
      "street_line_1": "100 Corporate Blvd",
      "city": "Miami",
      "state": "FL",
      "postal_code": "33101",
      "country": "US",
      "proof_of_address_file": "https://example.com/docs/office-lease.pdf"
    },
    "associated_persons": [
      {
        "first_name": "Jane",
        "last_name": "Doe",
        "birth_date": "1975-03-20",
        "nationality": "US",
        "email": "jane.doe@acme.com",
        "title": "CEO",
        "ownership_percentage": 51,
        "residential_address": {
          "street_line_1": "456 Oak Avenue",
          "city": "Miami",
          "state": "FL",
          "postal_code": "33102",
          "country": "US"
        },
        "has_ownership": true,
        "has_control": true,
        "is_signer": true,
        "is_director": true
      }
    ],
    "account_purpose": "BusinessPayments",
    "source_of_funds": "Business",
    "estimated_annual_revenue_usd": "100KTo1M",
    "expected_monthly_payments_usd": "5KTo50K",
    "high_risk_activities": [],
    "documents": [
      {
        "purpose": "business_registration",
        "description": "Articles of Incorporation",
        "file": "https://example.com/docs/articles.pdf"
      }
    ]
  }'

{
  "success": true,
  "message": "Business KYC submission received successfully",
  "business_data": {
    "customer_id": "d47f8a2b-1c3e-4f5a-9b8c-7d6e5f4a3b2c",
    "type": "business",
    "business_legal_name": "Acme Corporation LLC",
    "status": "in_progress",
    "created_at": "2026-04-02T10:00:00.000000Z"
  }
}

Check KYC / KYB status

GET /customer/kyc/{customer_id}

customer_id

string

required

The UUID of the customer whose verification status you want to check.

Status values

Status	Description
`not_started`	No KYC submission has been made yet
`submitted`	Submission received, awaiting review
`manual_review`	Under manual review by compliance team
`approved`	Customer is fully verified
`rejected`	Submission was rejected (see `kyc_rejection_reasons`)
`under_review`	Additional review in progress

When is_va_approved is true, the customer can use payment services including virtual accounts.

curl -X GET 'https://api.yativo.com/api/v1/customer/kyc/c586066b-0f29-468f-b775-15483871a202' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "status_code": 200,
  "data": {
    "first_name": "Alex",
    "last_name": "Smith",
    "status": "approved",
    "kyc_rejection_reasons": [],
    "kyc_requirements_due": [],
    "bio_data": {
      "customer_kyc_status": "approved",
      "kyc_verified_date": "2026-04-02T12:00:00.000000Z"
    },
    "kyc_link": "https://kyc.yativo.com/individual/c586066b-0f29-468f-b775-15483871a202",
    "is_va_approved": true
  }
}

Update KYC submission

To update an existing KYC or KYB submission:

PUT /customer/kyc/update

Send the updated fields using the same schema as the original submission. Both customer_id and type are required.

curl -X PUT 'https://api.yativo.com/api/v1/customer/kyc/update' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: kyc-update-alex-smith-2026' \
  -d '{
    "customer_id": "c586066b-0f29-468f-b775-15483871a202",
    "type": "individual",
    "employment_status": "self_employed",
    "source_of_funds": "Business"
  }'

Service endorsements

After KYC/KYB approval, customers receive endorsements that unlock specific payment services.

Service	Description
`base`	USD base payments
`sepa`	European SEPA transfers
`spei`	Mexico SPEI transfers
`brazil`	Brazilian payment rails
`eurde`	EUR/DE virtual accounts
`usd_latam`	USD Latin America transfers
`eur_latam`	EUR Latin America transfers
`virtual_card`	Virtual card issuance
`asian`	Asian region payments
`native`	Native payment rails
`cobo_pobo`	Collection/Payment-on-behalf-of

Endorsement statuses

Status	Description
`not_started`	Endorsement process not yet initiated
`pending`	Awaiting review
`approved`	Service is active for this customer
`rejected`	Endorsement was rejected
`declined`	Customer declined the endorsement
`under_review`	Additional review in progress

Regenerate endorsement link

If an endorsement verification URL has expired, you can regenerate it:

GET https://kyc.yativo.com/api/kyc/regenerate/{customerId}/{service}

customerId

string

required

The customer UUID.

service

string

required

The service name (e.g. "base", "sepa", "spei", "brazil", "eurde").

curl -X GET 'https://kyc.yativo.com/api/kyc/regenerate/c586066b-0f29-468f-b775-15483871a202/sepa' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Occupation codes

Retrieve the list of valid occupation codes to use in the most_recent_occupation_code field.

GET /auth/occupation-codes

curl -X GET 'https://api.yativo.com/api/v1/auth/occupation-codes' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "status_code": 200,
  "data": [
    { "display_name": "Accountant and auditor", "code": "132011" },
    { "display_name": "Actor", "code": "272011" },
    { "display_name": "Actuary", "code": "152011" },
    { "display_name": "Software developer", "code": "151252" },
    { "display_name": "Financial manager", "code": "113031" }
  ]
}

Verification locations

Retrieve the list of supported countries for customer registration and verification.

GET /auth/verification-locations

curl -X GET 'https://api.yativo.com/api/v1/auth/verification-locations' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "status_code": 200,
  "data": [
    { "country": "United States", "code": "US" },
    { "country": "Brazil", "code": "BR" },
    { "country": "Mexico", "code": "MX" },
    { "country": "Colombia", "code": "CO" },
    { "country": "Chile", "code": "CL" }
  ]
}

Enums and reference values

Business types

cooperative, corporation, llc, partnership, sole_prop, trust, other

Account purpose values

PurchaseGoodsAndServices, personalOrLivingExpenses, PaymentsToFriendsOrFamilyAbroad, ReceiveSalary, personal_use, business, other

Source of funds values

Salary, CompanyFunds, Business, Investment, Savings, GovernmentBenefits, SaleOfAssetsRealEstate

High-risk activities

adult_entertainment, gambling, hold_client_funds, investment_services, lending_banking, marijuana_or_related_services, money_services, operate_foreign_exchange_virtual_currencies_brokerage_otc, pharmaceuticals, precious_metals_precious_stones_jewelry, safe_deposit_box_rentals, weapons_firearms_and_explosives, none_of_the_above

Employment status values

Employed, self_employed, unemployed, retired, student

Expected monthly payment values (individual)

LessThan5K, 5KTo50K, MoreThan50K

Error handling

Standard error response format:

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed",
  "data": {
    "field_name": ["Validation error message"]
  }
}

HTTP status codes

Code	Description
`200`	Success
`201`	Created successfully
`400`	Bad request
`401`	Unauthorized (invalid or expired token)
`404`	Customer not found
`422`	Validation error
`429`	Rate limited
`500`	Internal server error

Common validation errors

customer_id is required
customer_id does not exist
type must be individual or business
birth_date must be before today
identifying_information is required
eurde_virtual_account conflicts

Webhooks

Yativo sends webhook notifications when KYC/KYB status changes. Webhook payload example:

{
  "event": "kyc.status_updated",
  "data": {
    "customer_id": "c586066b-0f29-468f-b775-15483871a202",
    "status": "approved",
    "type": "individual",
    "endorsements": ["base", "sepa", "spei"],
    "rejection_reasons": [],
    "updated_at": "2026-04-02T15:00:26.000000Z"
  }
}

Webhook events

Event	Description
`kyc.status_updated`	KYC/KYB status changed
`kyc.endorsement_updated`	A specific endorsement status changed

Implementation notes

Upload document files as either public URLs or base64-encoded strings.
Base64 payloads should not include line breaks.
Use ISO 3166-1 alpha-2 country codes for KYC platform submissions.
KYC review usually completes within 24 hours.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Developer Tools

​Environment base URLs

​Idempotency

​Verification approaches

​Verification flow

​Individual KYC — Submit via API

​Identity fields

​Residential address

​Identifying information

​Financial information

​Virtual account preferences

​Optional fields

​Business KYB — Submit via API

​Business identity fields

​Business addresses

​Associated persons

​Business financial information

​Business documents

​Optional business fields

​Check KYC / KYB status

​Status values

​Update KYC submission

​Service endorsements

​Endorsement statuses

​Regenerate endorsement link

​Occupation codes

​Verification locations

​Enums and reference values

​Business types

​Account purpose values

​Source of funds values

​High-risk activities

​Employment status values

​Expected monthly payment values (individual)

​Error handling

​HTTP status codes

​Common validation errors

​Webhooks

​Webhook events

​Implementation notes

Environment base URLs

Idempotency

Verification approaches

Verification flow

Individual KYC — Submit via API

Identity fields

Residential address

Identifying information

Financial information

Virtual account preferences

Optional fields

Business KYB — Submit via API

Business identity fields

Business addresses

Associated persons

Business financial information

Business documents

Optional business fields

Check KYC / KYB status

Status values

Update KYC submission

Service endorsements

Endorsement statuses

Regenerate endorsement link

Occupation codes

Verification locations

Enums and reference values

Business types

Account purpose values

Source of funds values

High-risk activities

Employment status values

Expected monthly payment values (individual)

Error handling

HTTP status codes

Common validation errors

Webhooks

Webhook events

Implementation notes