{
"business": {
"outcome": "VERSION_CREATED",
"resourceId": "business_customer_resource_example_01",
"versionId": "business_customer_version_example_01",
"currentVersionId": "business_customer_version_example_01"
},
"beneficialOwners": [
{
"customer": {
"outcome": "VERSION_CREATED",
"resourceId": "beneficial_owner_customer_01_resource_example_01",
"versionId": "beneficial_owner_customer_01_version_example_01",
"currentVersionId": "beneficial_owner_customer_01_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_01_resource_example_01",
"versionId": "ownership_relationship_01_version_example_02",
"currentVersionId": "ownership_relationship_01_version_example_02"
},
"roles": [
{
"resourceId": "control_relationship_01_resource_example_01",
"versionId": "control_relationship_01_version_example_02",
"currentVersionId": "control_relationship_01_version_example_02",
"role": "CONTROL_PERSON"
}
]
},
{
"customer": {
"outcome": "VERSION_CREATED",
"resourceId": "beneficial_owner_customer_02_resource_example_01",
"versionId": "beneficial_owner_customer_02_version_example_01",
"currentVersionId": "beneficial_owner_customer_02_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_02_resource_example_01",
"versionId": "ownership_relationship_02_version_example_02",
"currentVersionId": "ownership_relationship_02_version_example_02"
},
"roles": [
{
"resourceId": "director_relationship_02_resource_example_01",
"versionId": "director_relationship_02_version_example_02",
"currentVersionId": "director_relationship_02_version_example_02",
"role": "DIRECTOR"
}
]
}
],
"dossier": {
"dossierId": "kyb_dossier_example_01",
"customerVersionId": "customer_version_example_02",
"workflowRunId": "workflow_run_example_01",
"caseId": "case_example_01",
"evaluationStatus": "QUEUED",
"statusUrl": "/api/cases/case_example_01",
"observedAt": "2026-08-21T12:00:01.000Z"
}
}{
"business": {
"outcome": "CREATED",
"resourceId": "business_customer_resource_example_01",
"versionId": "business_customer_version_example_01",
"currentVersionId": "business_customer_version_example_01"
},
"beneficialOwners": [
{
"customer": {
"outcome": "CREATED",
"resourceId": "beneficial_owner_customer_01_resource_example_01",
"versionId": "beneficial_owner_customer_01_version_example_01",
"currentVersionId": "beneficial_owner_customer_01_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_01_resource_example_01",
"versionId": "ownership_relationship_01_version_example_01",
"currentVersionId": "ownership_relationship_01_version_example_01"
},
"roles": [
{
"resourceId": "control_relationship_01_resource_example_01",
"versionId": "control_relationship_01_version_example_01",
"currentVersionId": "control_relationship_01_version_example_01",
"role": "CONTROL_PERSON"
}
]
},
{
"customer": {
"outcome": "CREATED",
"resourceId": "beneficial_owner_customer_02_resource_example_01",
"versionId": "beneficial_owner_customer_02_version_example_01",
"currentVersionId": "beneficial_owner_customer_02_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_02_resource_example_01",
"versionId": "ownership_relationship_02_version_example_01",
"currentVersionId": "ownership_relationship_02_version_example_01"
},
"roles": [
{
"resourceId": "director_relationship_02_resource_example_01",
"versionId": "director_relationship_02_version_example_01",
"currentVersionId": "director_relationship_02_version_example_01",
"role": "DIRECTOR"
}
]
}
],
"dossier": {
"dossierId": "kyb_dossier_example_01",
"customerVersionId": "customer_version_example_01",
"workflowRunId": "workflow_run_example_01",
"caseId": "case_example_01",
"evaluationStatus": "QUEUED",
"statusUrl": "/api/cases/case_example_01",
"observedAt": "2026-08-21T12:00:01.000Z"
}
}{
"type": "https://karsa.app/problems/invalid-request",
"title": "Ingestion Rejected",
"status": 400,
"detail": "The request did not match the ingestion schema",
"code": "INVALID_REQUEST",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/authentication-required",
"title": "Ingestion Rejected",
"status": 401,
"detail": "A source-bound bearer credential is required",
"code": "AUTHENTICATION_REQUIRED",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/resource-not-found",
"title": "Ingestion Rejected",
"status": 404,
"detail": "A referenced source resource was not found",
"code": "RESOURCE_NOT_FOUND",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/source-identity-conflict",
"title": "Ingestion Rejected",
"status": 409,
"detail": "A customer or relationship source identity is already bound differently",
"code": "SOURCE_IDENTITY_CONFLICT",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/future-effective-at",
"title": "Ingestion Rejected",
"status": 422,
"detail": "Future-effective scheduling is not supported",
"code": "FUTURE_EFFECTIVE_AT",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/rate-limited",
"title": "Ingestion Rejected",
"status": 429,
"detail": "The ingestion source exceeded its configured rate",
"code": "RATE_LIMITED",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/ingestion-internal-error",
"title": "Ingestion Unavailable",
"status": 500,
"detail": "The ingestion request could not be completed",
"code": "INGESTION_INTERNAL_ERROR",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/kyb-runtime-unavailable",
"title": "Ingestion Unavailable",
"status": 503,
"detail": "KYB evaluation is not available in this deployment, or KYB is not set up for this workspace",
"code": "KYB_RUNTIME_UNAVAILABLE",
"requestId": "req_example_01"
}Customers
Create a business and its UBO customers
Atomic convenience operation. Creates or versions one business Customer, creates or versions every beneficial owner as a full INDIVIDUAL Customer, records their ownership and role relationships, and submits the KYB dossier.
POST
/
api
/
ingestion
/
business-onboardings
{
"business": {
"outcome": "VERSION_CREATED",
"resourceId": "business_customer_resource_example_01",
"versionId": "business_customer_version_example_01",
"currentVersionId": "business_customer_version_example_01"
},
"beneficialOwners": [
{
"customer": {
"outcome": "VERSION_CREATED",
"resourceId": "beneficial_owner_customer_01_resource_example_01",
"versionId": "beneficial_owner_customer_01_version_example_01",
"currentVersionId": "beneficial_owner_customer_01_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_01_resource_example_01",
"versionId": "ownership_relationship_01_version_example_02",
"currentVersionId": "ownership_relationship_01_version_example_02"
},
"roles": [
{
"resourceId": "control_relationship_01_resource_example_01",
"versionId": "control_relationship_01_version_example_02",
"currentVersionId": "control_relationship_01_version_example_02",
"role": "CONTROL_PERSON"
}
]
},
{
"customer": {
"outcome": "VERSION_CREATED",
"resourceId": "beneficial_owner_customer_02_resource_example_01",
"versionId": "beneficial_owner_customer_02_version_example_01",
"currentVersionId": "beneficial_owner_customer_02_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_02_resource_example_01",
"versionId": "ownership_relationship_02_version_example_02",
"currentVersionId": "ownership_relationship_02_version_example_02"
},
"roles": [
{
"resourceId": "director_relationship_02_resource_example_01",
"versionId": "director_relationship_02_version_example_02",
"currentVersionId": "director_relationship_02_version_example_02",
"role": "DIRECTOR"
}
]
}
],
"dossier": {
"dossierId": "kyb_dossier_example_01",
"customerVersionId": "customer_version_example_02",
"workflowRunId": "workflow_run_example_01",
"caseId": "case_example_01",
"evaluationStatus": "QUEUED",
"statusUrl": "/api/cases/case_example_01",
"observedAt": "2026-08-21T12:00:01.000Z"
}
}{
"business": {
"outcome": "CREATED",
"resourceId": "business_customer_resource_example_01",
"versionId": "business_customer_version_example_01",
"currentVersionId": "business_customer_version_example_01"
},
"beneficialOwners": [
{
"customer": {
"outcome": "CREATED",
"resourceId": "beneficial_owner_customer_01_resource_example_01",
"versionId": "beneficial_owner_customer_01_version_example_01",
"currentVersionId": "beneficial_owner_customer_01_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_01_resource_example_01",
"versionId": "ownership_relationship_01_version_example_01",
"currentVersionId": "ownership_relationship_01_version_example_01"
},
"roles": [
{
"resourceId": "control_relationship_01_resource_example_01",
"versionId": "control_relationship_01_version_example_01",
"currentVersionId": "control_relationship_01_version_example_01",
"role": "CONTROL_PERSON"
}
]
},
{
"customer": {
"outcome": "CREATED",
"resourceId": "beneficial_owner_customer_02_resource_example_01",
"versionId": "beneficial_owner_customer_02_version_example_01",
"currentVersionId": "beneficial_owner_customer_02_version_example_01"
},
"ownership": {
"resourceId": "ownership_relationship_02_resource_example_01",
"versionId": "ownership_relationship_02_version_example_01",
"currentVersionId": "ownership_relationship_02_version_example_01"
},
"roles": [
{
"resourceId": "director_relationship_02_resource_example_01",
"versionId": "director_relationship_02_version_example_01",
"currentVersionId": "director_relationship_02_version_example_01",
"role": "DIRECTOR"
}
]
}
],
"dossier": {
"dossierId": "kyb_dossier_example_01",
"customerVersionId": "customer_version_example_01",
"workflowRunId": "workflow_run_example_01",
"caseId": "case_example_01",
"evaluationStatus": "QUEUED",
"statusUrl": "/api/cases/case_example_01",
"observedAt": "2026-08-21T12:00:01.000Z"
}
}{
"type": "https://karsa.app/problems/invalid-request",
"title": "Ingestion Rejected",
"status": 400,
"detail": "The request did not match the ingestion schema",
"code": "INVALID_REQUEST",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/authentication-required",
"title": "Ingestion Rejected",
"status": 401,
"detail": "A source-bound bearer credential is required",
"code": "AUTHENTICATION_REQUIRED",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/resource-not-found",
"title": "Ingestion Rejected",
"status": 404,
"detail": "A referenced source resource was not found",
"code": "RESOURCE_NOT_FOUND",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/source-identity-conflict",
"title": "Ingestion Rejected",
"status": 409,
"detail": "A customer or relationship source identity is already bound differently",
"code": "SOURCE_IDENTITY_CONFLICT",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/future-effective-at",
"title": "Ingestion Rejected",
"status": 422,
"detail": "Future-effective scheduling is not supported",
"code": "FUTURE_EFFECTIVE_AT",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/rate-limited",
"title": "Ingestion Rejected",
"status": 429,
"detail": "The ingestion source exceeded its configured rate",
"code": "RATE_LIMITED",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/ingestion-internal-error",
"title": "Ingestion Unavailable",
"status": 500,
"detail": "The ingestion request could not be completed",
"code": "INGESTION_INTERNAL_ERROR",
"requestId": "req_example_01"
}{
"type": "https://karsa.app/problems/kyb-runtime-unavailable",
"title": "Ingestion Unavailable",
"status": 503,
"detail": "KYB evaluation is not available in this deployment, or KYB is not set up for this workspace",
"code": "KYB_RUNTIME_UNAVAILABLE",
"requestId": "req_example_01"
}Authorizations
Source-bound WorkOS API key or configured machine OIDC token. OIDC webhook management requires karsa:webhooks:manage.
Headers
Stable source submission identifier, unique for this source and route
Required string length:
1 - 200Example:
"01J9ZQ2YD15Y2YZ5H0W3J7D3E2"
Body
application/json
Hide child attributes
Hide child attributes
Required string length:
1 - 200Available options:
PENDING, ACTIVE, SUSPENDED, CLOSED Available options:
BUSINESS Hide child attributes
Hide child attributes
Required string length:
1 - 300Required array length:
1 - 20 elementsRequired string length:
1 - 500Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Pattern:
^[A-Z]{2}$Required string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 500Required array length:
1 - 10 elementsHide child attributes
Hide child attributes
Pattern:
^[A-Z]{2}$Available options:
EIN, TIN, VAT, CNPJ, RFC, NIT, NTN, BIN, TRN, OTHER Required string length:
1 - 500Required string length:
1 - 200Hide child attributes
Hide child attributes
Required array length:
1 - 6 elementsRequired string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 40Pattern:
^[A-Z]{2}$Maximum string length:
320Maximum string length:
2000Hide child attributes
Hide child attributes
Required array length:
1 - 6 elementsRequired string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 40Pattern:
^[A-Z]{2}$Required string length:
1 - 2000Hide child attributes
Hide child attributes
Available options:
NAICS, NACE, ISIC, MCC, OTHER Required string length:
1 - 500Required string length:
1 - 80Required string length:
1 - 500Required string length:
1 - 2000Hide child attributes
Hide child attributes
Required array length:
1 - 7 elementsAvailable options:
OPERATING_REVENUE, OWNER_OR_SHAREHOLDER_FUNDS, INVESTMENT_OR_CAPITAL, LOAN_OR_CREDIT, ASSET_SALE, GRANT_OR_DONATION, OTHER Required string length:
1 - 2000Hide child attributes
Hide child attributes
Required array length:
1 - 50 elementsPattern:
^[A-Z]{2}$Required array length:
1 - 25 elementsHide child attributes
Hide child attributes
Required string length:
1 - 500Available options:
MONEY_TRANSMISSION, PAYMENT_SERVICES, VIRTUAL_ASSET_SERVICES, CUSTODY, EXCHANGE_OR_TRADING, LENDING, BANKING, BROKER_DEALER, OTHER Pattern:
^[A-Z]{2}$Available options:
LICENCE, REGULATORY_REGISTRATION, ACCEPTED_EXEMPTION Required string length:
1 - 500Required string length:
1 - 500Available options:
AUTHORIZED, PENDING, EXEMPT, NOT_AUTHORIZED Maximum string length:
2000Required string length:
1 - 200Pattern:
^\+[1-9]\d{1,14}$Required string length:
1 - 2000Required string length:
1 - 2000At most 50 beneficial owners, 10 roles per owner, and 100 total ownership plus role relationships
Maximum array length:
50Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Required string length:
1 - 200Available options:
PENDING, ACTIVE, SUSPENDED, CLOSED Available options:
INDIVIDUAL Hide child attributes
Hide child attributes
Required string length:
1 - 300Required string length:
1 - 500Required string length:
1 - 500Required string length:
1 - 500Required array length:
1 - 10 elementsPattern:
^[A-Z]{2}$Pattern:
^[A-Z]{2}$Hide child attributes
Hide child attributes
Required array length:
1 - 6 elementsRequired string length:
1 - 500Required string length:
1 - 500beneficialOwners.customer.individual.residentialAddress.administrativeAreaCode
string | null
required
Required string length:
1 - 500beneficialOwners.customer.individual.residentialAddress.administrativeAreaName
string | null
required
Required string length:
1 - 500Required string length:
1 - 40Pattern:
^[A-Z]{2}$Maximum string length:
320Pattern:
^\+[1-9]\d{1,14}$Required array length:
1 - 10 elementsHide child attributes
Hide child attributes
Pattern:
^[A-Z]{2}$Available options:
EIN, TIN, VAT, CNPJ, RFC, NIT, NTN, BIN, TRN, OTHER Required string length:
1 - 500Required string length:
1 - 200Hide child attributes
Hide child attributes
Required range:
-90 <= x <= 90Required range:
-180 <= x <= 180Maximum string length:
2000Required string length:
1 - 200Required string length:
1 - 2000Required string length:
1 - 2000Hide child attributes
Hide child attributes
Required array length:
1 - 7 elementsAvailable options:
OPERATING_REVENUE, OWNER_OR_SHAREHOLDER_FUNDS, INVESTMENT_OR_CAPITAL, LOAN_OR_CREDIT, ASSET_SALE, GRANT_OR_DONATION, OTHER Required string length:
1 - 2000Required string length:
1 - 2000Required string length:
1 - 500Maximum array length:
25Hide child attributes
Hide child attributes
Required string length:
1 - 200Business-time cutoff for the complete snapshot; business, owner, document, and provider facts cannot be effective later
Maximum array length:
50Hide child attributes
Hide child attributes
Required string length:
1 - 200Available options:
FORMATION_DOCUMENT, TAX_AUTHORITY_DOCUMENT, BUSINESS_PROOF_OF_ADDRESS, OWNERSHIP_DOCUMENT, OWNER_ID_FRONT, OWNER_ID_BACK, OWNER_PROOF_OF_ADDRESS, SOURCE_OF_FUNDS, BUSINESS_ACTIVITY, REGULATORY_AUTHORIZATION, BANK_STATEMENT, CONTRACT, INVOICE_OR_RECEIPT, ADDITIONAL_INFO, OTHER Required string length:
1 - 100Pattern:
^[A-Z][A-Z0-9_]*$Required array length:
1 - 3 elementsRequired string length:
2 - 35Maximum array length:
500- Option 1
- Option 2
Hide child attributes
Hide child attributes
Required string length:
1 - 200Required string length:
1 - 200Required string length:
1 - 500Available options:
IDENTITY_VERIFICATION Required string length:
1 - 100Available options:
CURRENT, OTHER Response
Immutable versions were appended to existing source identities
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Available options:
CREATED, VERSION_CREATED Minimum string length:
1Minimum string length:
1Minimum string length:
1Hide child attributes
Hide child attributes
Minimum string length:
1Minimum string length:
1Minimum string length:
1Available options:
CONTROL_PERSON, DIRECTOR, OFFICER, AUTHORIZED_SIGNER, REPRESENTATIVE, OTHER Hide child attributes
Hide child attributes
Minimum string length:
1Minimum string length:
1Minimum string length:
1Minimum string length:
1Available options:
QUEUED, EXISTING Required string length:
1 - 500