Onboard a business and its UBOs

Karsa represents both people and businesses as Customers. Set type to BUSINESS when creating a business and INDIVIDUAL when creating a person. There are two supported ways to provide business data:

What you need	Route	Result
Create or version one business only	`POST /api/ingestion/customers`	One `BUSINESS` Customer
Guarantee the business and every UBO are accepted together	`POST /api/ingestion/business-onboardings`	One `BUSINESS` Customer, one `INDIVIDUAL` Customer per UBO, relationships, and a KYB submission

The atomic route is a convenience operation over the Customer model. It does not create a separate kind of Business resource.

Before you send the request

You need:

your Karsa API base URL;
a source-bound bearer credential;
one stable source identifier for the business;
one stable source identifier for every UBO;
unique source identifiers for every ownership and role relationship; and
one stable Idempotency-Key for this complete onboarding attempt.

Use identifiers from your own system. Do not generate a new externalId when retrying the same customer. Treat dossier.sourceEffectiveAt as the business-time cutoff for the complete snapshot. The business and every beneficial owner’s effectiveAt must be at or before that cutoff. Karsa may receive and record the request later; those availability timestamps do not move the historical business-time cutoff. One request supports at most 50 beneficial owners, 10 role assignments per owner, and 100 total ownership plus role relationships. The complete dossier rules also apply: relationship IDs and provider evidence type/source-record pairs must be unique, every referenced related party must be declared, and all provider evidence must belong to one package with one snapshot observation time no later than sourceEffectiveAt.

Send the canonical three-Customer request

This request creates Example Manufacturing LLC plus Ada and Grace as two separate individual Customers. The two ownership percentages add to 100%, but Karsa does not require every business to use that exact total because sources may provide incomplete or indirect ownership.

curl --request POST \
  --url "$KARSA_API_URL/api/ingestion/business-onboardings" \
  --header "Authorization: Bearer $KARSA_API_TOKEN" \
  --header "Idempotency-Key: business-example-001-onboarding-v1" \
  --header "Content-Type: application/json" \
  --data '{
    "business": {
      "externalId": "customer-example-001",
      "type": "BUSINESS",
      "effectiveAt": "2026-08-05T14:00:00Z",
      "lifecycleStatus": "ACTIVE",
      "onboardedAt": "2026-08-05T13:45:00Z",
      "business": {
        "verificationTier": {
          "sourceText": "standard",
          "category": "STANDARD"
        },
        "onboardingContext": {
          "ipAddress": "203.0.113.10",
          "latitude": 39.1582,
          "longitude": -75.5244
        },
        "legalName": "Example Manufacturing LLC",
        "tradeNames": null,
        "legalForm": null,
        "formationJurisdiction": null,
        "formationDate": null,
        "registrationNumber": null,
        "taxIdentifiers": null,
        "registeredAddress": null,
        "email": "compliance@example.invalid",
        "website": null,
        "operatingAddress": null,
        "businessDescription": null,
        "industry": null,
        "accountPurpose": null,
        "transactionPurpose": "Pay suppliers and receive customer payments",
        "sourceOfFunds": null,
        "sourceOfWealth": "Operating revenue and retained earnings",
        "annualRevenue": null,
        "expectedMonthlyAmount": null,
        "expectedMonthlyTransactionCount": null,
        "operatingCountries": null,
        "handlesThirdPartyFunds": null,
        "publiclyTraded": false,
        "regulatedActivities": null
      },
      "documents": []
    },
    "beneficialOwners": [
      {
        "customer": {
          "externalId": "owner-example-001",
          "type": "INDIVIDUAL",
          "effectiveAt": "2026-08-21T12:00:00Z",
          "lifecycleStatus": "ACTIVE",
          "documents": [],
          "individual": {
            "legalName": "Ada Example",
            "givenName": "Ada",
            "middleName": null,
            "familyName": "Example",
            "dateOfBirth": "1985-06-15",
            "nationalities": ["US"],
            "residenceCountry": "US",
            "residentialAddress": null,
            "email": "ada@example.com",
            "phone": null,
            "taxIdentifiers": null
          }
        },
        "ownership": {
          "relationshipExternalId": "ownership-example-001",
          "ownershipPercent": 60
        },
        "roles": [
          {
            "relationshipExternalId": "control-example-001",
            "role": "CONTROL_PERSON"
          }
        ]
      },
      {
        "customer": {
          "externalId": "owner-example-002",
          "type": "INDIVIDUAL",
          "effectiveAt": "2026-08-21T12:00:00Z",
          "lifecycleStatus": "ACTIVE",
          "documents": [],
          "individual": {
            "legalName": "Grace Example",
            "givenName": "Grace",
            "middleName": null,
            "familyName": "Example",
            "dateOfBirth": "1988-12-09",
            "nationalities": ["US"],
            "residenceCountry": "US",
            "residentialAddress": null,
            "email": "grace@example.com",
            "phone": null,
            "taxIdentifiers": null
          }
        },
        "ownership": {
          "relationshipExternalId": "ownership-example-002",
          "ownershipPercent": 40
        },
        "roles": [
          {
            "relationshipExternalId": "director-example-002",
            "role": "DIRECTOR"
          }
        ]
      }
    ],
    "dossier": {
      "sourceVersion": "provider-kyb-example-001",
      "sourceEffectiveAt": "2026-08-21T12:00:00Z",
      "documents": [],
      "providerEvidence": []
    }
  }'

Use explicit null when your source states that a nullable fact is unavailable. Do not remove required keys or invent placeholder values. The API Reference is authoritative for the complete field constraints.

Read the response

The response gives the business and each UBO a distinct stable Customer resourceId:

{
  "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": "business_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:01Z"
  }
}

Store all three Customer resourceId values. The UBO IDs can be referenced anywhere another individual Customer can be referenced.

How the API ingests this request

The supported integration boundary is the HTTP API. Karsa processes this request as follows:

Fastify authenticates the bearer credential and binds the request to its tenant and source.
The request schema validates the business, every complete INDIVIDUAL UBO profile, every relationship, and the same complete dossier contract used by the standalone KYB endpoint before any records are committed.
The idempotency receipt and one database transaction cover the complete onboarding operation.
The business and every UBO pass through the same Customer ingestion path used by POST /api/ingestion/customers.
Karsa creates the ownership and role relationships, pins the dossier to the returned business CustomerVersion and the stated business-time cutoff, creates its durable Case, and queues the internal KYB workflow.
The transaction commits and the API returns all Customer, relationship, dossier, Case, and internal workflow identifiers.

Our local acceptance test follows this exact path: it sends the authenticated request to the local Fastify server over loopback HTTP, retries it with the same idempotency key, and only then uses read-only PostgreSQL queries to verify the committed rows. It does not insert test records directly into the database.

What Karsa commits

Karsa validates the whole request before committing it. One successful request writes:

one stable business Customer and its immutable CustomerVersion;
one stable individual Customer and CustomerVersion for every UBO;
versioned beneficial-ownership and role relationships from each UBO Customer to the business Customer;
one immutable KYB dossier pinned to the business CustomerVersion;
one durable Case in PROCESSING; and
one queued internal KYB workflow run.

These writes are atomic. If Customer validation, a relationship, the dossier, or the KYB runtime fails, none of the Customers or relationships from that request are committed.

Retry safely

After a timeout or ambiguous network response, send the exact same body with the same Idempotency-Key. Karsa returns the original response instead of creating duplicate Customers, relationships, dossiers, Cases, or workflow runs. Use a new idempotency key only for a new logical submission. Keep each source externalId stable so later observations append immutable versions to the same Customer identity.

Use separate requests when you need more control

You can instead create the business and each person separately through POST /api/ingestion/customers, then submit the KYB dossier. That pattern is useful when the people already exist as Customers or arrive at different times. Use the atomic onboarding route when your system needs certainty that the business and every supplied UBO were accepted together.

Customers: understand business and individual Customer records
KYB dossiers: submit evidence for an existing business CustomerVersion
Upload flow: connect documents, accounts, transactions, and outcomes
API Reference → Customers → Create a business and its UBO customers: inspect every field and error

Start here

Onboard customers

Integration pattern

Before you send the request

Send the canonical three-Customer request

Read the response

How the API ingests this request

What Karsa commits

Retry safely

Use separate requests when you need more control

​Before you send the request

​Send the canonical three-Customer request

​Read the response

​How the API ingests this request

​What Karsa commits

​Retry safely

​Use separate requests when you need more control

​Related

Before you send the request

Send the canonical three-Customer request

Read the response

How the API ingests this request

What Karsa commits

Retry safely

Use separate requests when you need more control

Related