> ## Documentation Index > Fetch the complete documentation index at: https://docs.useasterisk.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Document only operations in the linked OpenAPI contract: the source-data ingestion operations and the source-scoped outbound webhook management operations. > Treat the generated OpenAPI document as authoritative for request fields. Never invent compatibility fields, alternate endpoints, or additional source models. > Preserve explicit nulls, decimal strings, timestamps, source identifiers, immutable version identifiers, and document-version links exactly as defined. # 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. ## OpenAPI ````yaml /openapi/ingestion.openapi.yaml post /api/ingestion/business-onboardings openapi: 3.1.0 info: title: Karsa Data Ingestion API version: current description: >- Source-bound writes for documents, business onboardings, customers, kyb-dossiers, accounts, transactions, outcomes, screening observations, screening dispositions, monitoring controls, monitoring control executions, historical RFI events, source checkpoints, native SEON screening observations, native AiPrise screening observations, and native Chainalysis screening observations. servers: - url: https://api.sandbox.useasterisk.com description: Karsa sandbox API (synthetic test data) - url: https://api.useasterisk.com description: Karsa production API security: [] tags: - name: Customers description: >- Create and version individual or business customer records, including atomic business onboarding where every beneficial owner is an individual Customer. - name: Verifications description: >- Submit immutable customer evidence snapshots for KYC or KYB evaluation, or start a KYB run for a business customer and poll its status. - name: Accounts description: >- Create and version customer-linked bank accounts, virtual accounts, and wallets without coupling the contract to a provider. - name: Documents description: Submit immutable document bytes or URL references and metadata. - name: Transactions description: Create and version money-movement records. - name: Sources description: >- Record source-attested, append-only completeness checkpoints used to qualify downstream evidence windows. - name: Outcomes description: >- Record source outcomes against customers, accounts, transactions, or documents. - name: Screening description: >- Submit provider-neutral verification, screening, alert, and reviewer-disposition evidence for Routine 6 qualification. - name: Controls description: >- Submit the source-owned monitoring control catalog and immutable execution evidence used to assess control coverage. - name: Requests description: >- Submit immutable historical request-for-information lifecycle events used to measure repeat requests and expiry. - name: Webhooks description: >- Manage source-scoped outbound destinations, receive later KYB evaluation lifecycle changes, and list recorded events to catch up on missed deliveries. paths: /api/ingestion/business-onboardings: post: tags: - Customers summary: Create a business and its UBO customers description: >- 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. operationId: ingestBusinessOnboarding parameters: - schema: type: string minLength: 1 maxLength: 200 description: >- Stable source submission identifier, unique for this source and route example: 01J9ZQ2YD15Y2YZ5H0W3J7D3E2 required: true name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BusinessOnboardingWrite' examples: request: value: business: externalId: customer-example-001 type: BUSINESS effectiveAt: '2026-08-05T14:00:00.000Z' lifecycleStatus: ACTIVE onboardedAt: '2026-08-05T13:45:00.000Z' 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:00.000Z' lifecycleStatus: ACTIVE documents: [] individual: legalName: Ada Example givenName: Ada middleName: null familyName: Example dateOfBirth: '1985-06-15T00:00:00.000Z' 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:00.000Z' lifecycleStatus: ACTIVE documents: [] individual: legalName: Grace Example givenName: Grace middleName: null familyName: Example dateOfBirth: '1988-12-09T00:00:00.000Z' 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:00.000Z' documents: [] providerEvidence: [] responses: '200': description: Immutable versions were appended to existing source identities content: application/json: schema: $ref: '#/components/schemas/BusinessOnboardingResponse' examples: success: value: 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' '201': description: >- The business onboarding and every durable source identity were created content: application/json: schema: $ref: '#/components/schemas/BusinessOnboardingResponse' examples: success: value: 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' '400': description: 'INVALID_REQUEST: The request did not match the ingestion schema' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: INVALID_REQUEST: value: 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 '401': description: >- AUTHENTICATION_REQUIRED: A source-bound bearer credential is required content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: AUTHENTICATION_REQUIRED: value: 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 '404': description: 'RESOURCE_NOT_FOUND: A referenced source resource was not found' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: RESOURCE_NOT_FOUND: value: 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 '409': description: >- SOURCE_IDENTITY_CONFLICT: A customer or relationship source identity is already bound differently content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: SOURCE_IDENTITY_CONFLICT: value: 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 '422': description: 'FUTURE_EFFECTIVE_AT: Future-effective scheduling is not supported' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: FUTURE_EFFECTIVE_AT: value: 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 '429': description: 'RATE_LIMITED: The ingestion source exceeded its configured rate' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: RATE_LIMITED: value: 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 '500': description: >- INGESTION_INTERNAL_ERROR: The ingestion request could not be completed content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: INGESTION_INTERNAL_ERROR: value: 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 '503': description: >- KYB_RUNTIME_UNAVAILABLE: KYB evaluation is not available in this deployment, or KYB is not set up for this workspace content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: KYB_RUNTIME_UNAVAILABLE: value: 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 security: - ingestionBearer: [] components: schemas: BusinessOnboardingWrite: type: object properties: business: type: object properties: externalId: type: string minLength: 1 maxLength: 200 effectiveAt: type: string format: date-time lifecycleStatus: type: string enum: - PENDING - ACTIVE - SUSPENDED - CLOSED onboardedAt: type: - string - 'null' format: date-time customData: type: - object - 'null' additionalProperties: {} documents: type: array items: type: object properties: documentVersionId: type: string minLength: 1 maxLength: 200 role: type: string minLength: 1 maxLength: 200 roleDetail: type: - string - 'null' minLength: 1 maxLength: 200 required: - documentVersionId - role additionalProperties: false maxItems: 25 default: [] type: type: string enum: - BUSINESS business: type: object properties: verificationTier: type: - object - 'null' properties: sourceText: type: string minLength: 1 maxLength: 500 category: type: - string - 'null' enum: - LIGHT - STANDARD - ENHANCED - OTHER required: - sourceText - category additionalProperties: false onboardingContext: type: - object - 'null' properties: ipAddress: type: - string - 'null' format: ip latitude: type: - number - 'null' minimum: -90 maximum: 90 longitude: type: - number - 'null' minimum: -180 maximum: 180 required: - ipAddress - latitude - longitude additionalProperties: false profileImageUrl: type: - string - 'null' maxLength: 2000 format: uri termsAcceptanceId: type: - string - 'null' minLength: 1 maxLength: 200 additionalInformation: type: - array - 'null' items: type: object properties: label: type: string minLength: 1 maxLength: 500 value: type: string minLength: 1 maxLength: 5000 required: - label - value additionalProperties: false maxItems: 50 legalName: type: string minLength: 1 maxLength: 300 tradeNames: type: - array - 'null' items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 20 legalForm: type: - object - 'null' properties: sourceText: type: string minLength: 1 maxLength: 500 category: type: - string - 'null' enum: - SOLE_PROPRIETORSHIP - PARTNERSHIP - LIMITED_LIABILITY_ENTITY - CORPORATION - NONPROFIT - TRUST_OR_FOUNDATION - GOVERNMENT_ENTITY - OTHER required: - sourceText - category additionalProperties: false formationJurisdiction: type: - object - 'null' properties: country: type: string pattern: ^[A-Z]{2}$ administrativeAreaCode: type: - string - 'null' minLength: 1 maxLength: 500 administrativeAreaName: type: - string - 'null' minLength: 1 maxLength: 500 required: - country - administrativeAreaCode - administrativeAreaName additionalProperties: false formationDate: type: - string - 'null' format: date registrationNumber: type: - string - 'null' minLength: 1 maxLength: 500 taxIdentifiers: type: - array - 'null' items: type: object properties: country: type: string pattern: ^[A-Z]{2}$ type: type: string enum: - EIN - TIN - VAT - CNPJ - RFC - NIT - NTN - BIN - TRN - OTHER typeSourceText: type: - string - 'null' minLength: 1 maxLength: 500 number: type: string minLength: 1 maxLength: 200 required: - country - type - typeSourceText - number additionalProperties: false minItems: 1 maxItems: 10 registeredAddress: type: - object - 'null' properties: addressLines: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 6 locality: type: - string - 'null' minLength: 1 maxLength: 500 administrativeAreaCode: type: - string - 'null' minLength: 1 maxLength: 500 administrativeAreaName: type: - string - 'null' minLength: 1 maxLength: 500 postalCode: type: - string - 'null' minLength: 1 maxLength: 40 country: type: string pattern: ^[A-Z]{2}$ required: - addressLines - locality - administrativeAreaCode - administrativeAreaName - postalCode - country additionalProperties: false email: type: - string - 'null' maxLength: 320 format: email phone: type: - string - 'null' pattern: ^\+[1-9]\d{1,14}$ website: type: - string - 'null' maxLength: 2000 format: uri operatingAddress: type: - object - 'null' properties: addressLines: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 6 locality: type: - string - 'null' minLength: 1 maxLength: 500 administrativeAreaCode: type: - string - 'null' minLength: 1 maxLength: 500 administrativeAreaName: type: - string - 'null' minLength: 1 maxLength: 500 postalCode: type: - string - 'null' minLength: 1 maxLength: 40 country: type: string pattern: ^[A-Z]{2}$ required: - addressLines - locality - administrativeAreaCode - administrativeAreaName - postalCode - country additionalProperties: false businessDescription: type: - string - 'null' minLength: 1 maxLength: 2000 industry: type: - object - 'null' properties: system: type: string enum: - NAICS - NACE - ISIC - MCC - OTHER systemSourceText: type: - string - 'null' minLength: 1 maxLength: 500 code: type: - string - 'null' minLength: 1 maxLength: 80 label: type: - string - 'null' minLength: 1 maxLength: 500 required: - system - systemSourceText - code - label additionalProperties: false accountPurpose: type: - string - 'null' minLength: 1 maxLength: 2000 transactionPurpose: type: - string - 'null' minLength: 1 maxLength: 2000 sourceOfFunds: type: - object - 'null' properties: categories: type: array items: type: string enum: - OPERATING_REVENUE - OWNER_OR_SHAREHOLDER_FUNDS - INVESTMENT_OR_CAPITAL - LOAN_OR_CREDIT - ASSET_SALE - GRANT_OR_DONATION - OTHER minItems: 1 maxItems: 7 explanation: type: - string - 'null' minLength: 1 maxLength: 2000 required: - categories - explanation additionalProperties: false sourceOfWealth: type: - string - 'null' minLength: 1 maxLength: 2000 annualRevenue: type: - object - 'null' properties: currency: type: string pattern: ^[A-Z]{3}$ minimum: type: - string - 'null' pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ maximum: type: - string - 'null' pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ required: - currency - minimum - maximum additionalProperties: false expectedMonthlyAmount: type: - object - 'null' properties: currency: type: string pattern: ^[A-Z]{3}$ minimum: type: - string - 'null' pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ maximum: type: - string - 'null' pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ required: - currency - minimum - maximum additionalProperties: false expectedMonthlyTransactionCount: type: - object - 'null' properties: minimum: type: - integer - 'null' minimum: 0 maximum: type: - integer - 'null' minimum: 0 required: - minimum - maximum additionalProperties: false operatingCountries: type: - array - 'null' items: type: string pattern: ^[A-Z]{2}$ minItems: 1 maxItems: 50 handlesThirdPartyFunds: type: - boolean - 'null' publiclyTraded: type: - boolean - 'null' regulatedActivities: type: - array - 'null' items: type: object properties: sourceActivity: type: string minLength: 1 maxLength: 500 activityCode: type: string enum: - MONEY_TRANSMISSION - PAYMENT_SERVICES - VIRTUAL_ASSET_SERVICES - CUSTODY - EXCHANGE_OR_TRADING - LENDING - BANKING - BROKER_DEALER - OTHER jurisdictionCountry: type: - string - 'null' pattern: ^[A-Z]{2}$ authorizationKind: type: - string - 'null' enum: - LICENCE - REGULATORY_REGISTRATION - ACCEPTED_EXEMPTION authority: type: - string - 'null' minLength: 1 maxLength: 500 authorizationNumber: type: - string - 'null' minLength: 1 maxLength: 500 declaredStatus: type: - string - 'null' enum: - AUTHORIZED - PENDING - EXEMPT - NOT_AUTHORIZED required: - sourceActivity - activityCode - jurisdictionCountry - authorizationKind - authority - authorizationNumber - declaredStatus additionalProperties: false minItems: 1 maxItems: 25 required: - legalName - tradeNames - legalForm - formationJurisdiction - formationDate - registrationNumber - taxIdentifiers - registeredAddress - email - website - operatingAddress - businessDescription - industry - accountPurpose - sourceOfFunds - annualRevenue - expectedMonthlyAmount - expectedMonthlyTransactionCount - operatingCountries - handlesThirdPartyFunds - regulatedActivities additionalProperties: false required: - externalId - effectiveAt - lifecycleStatus - type - business additionalProperties: false beneficialOwners: type: array items: type: object properties: customer: type: object properties: externalId: type: string minLength: 1 maxLength: 200 effectiveAt: type: string format: date-time lifecycleStatus: type: string enum: - PENDING - ACTIVE - SUSPENDED - CLOSED onboardedAt: type: - string - 'null' format: date-time customData: type: - object - 'null' additionalProperties: {} documents: type: array items: type: object properties: documentVersionId: type: string minLength: 1 maxLength: 200 role: type: string minLength: 1 maxLength: 200 roleDetail: type: - string - 'null' minLength: 1 maxLength: 200 required: - documentVersionId - role additionalProperties: false maxItems: 25 default: [] type: type: string enum: - INDIVIDUAL individual: type: object properties: verificationTier: type: - object - 'null' properties: sourceText: type: string minLength: 1 maxLength: 500 category: type: - string - 'null' enum: - LIGHT - STANDARD - ENHANCED - OTHER required: - sourceText - category additionalProperties: false onboardingContext: type: - object - 'null' properties: ipAddress: type: - string - 'null' format: ip latitude: type: - number - 'null' minimum: -90 maximum: 90 longitude: type: - number - 'null' minimum: -180 maximum: 180 required: - ipAddress - latitude - longitude additionalProperties: false profileImageUrl: type: - string - 'null' maxLength: 2000 format: uri termsAcceptanceId: type: - string - 'null' minLength: 1 maxLength: 200 additionalInformation: type: - array - 'null' items: type: object properties: label: type: string minLength: 1 maxLength: 500 value: type: string minLength: 1 maxLength: 5000 required: - label - value additionalProperties: false maxItems: 50 legalName: type: string minLength: 1 maxLength: 300 givenName: type: - string - 'null' minLength: 1 maxLength: 500 middleName: type: - string - 'null' minLength: 1 maxLength: 500 familyName: type: - string - 'null' minLength: 1 maxLength: 500 dateOfBirth: type: - string - 'null' format: date nationalities: type: - array - 'null' items: type: string pattern: ^[A-Z]{2}$ minItems: 1 maxItems: 10 residenceCountry: type: - string - 'null' pattern: ^[A-Z]{2}$ residentialAddress: type: - object - 'null' properties: addressLines: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 6 locality: type: - string - 'null' minLength: 1 maxLength: 500 administrativeAreaCode: type: - string - 'null' minLength: 1 maxLength: 500 administrativeAreaName: type: - string - 'null' minLength: 1 maxLength: 500 postalCode: type: - string - 'null' minLength: 1 maxLength: 40 country: type: string pattern: ^[A-Z]{2}$ required: - addressLines - locality - administrativeAreaCode - administrativeAreaName - postalCode - country additionalProperties: false email: type: - string - 'null' maxLength: 320 format: email phone: type: - string - 'null' pattern: ^\+[1-9]\d{1,14}$ taxIdentifiers: type: - array - 'null' items: type: object properties: country: type: string pattern: ^[A-Z]{2}$ type: type: string enum: - EIN - TIN - VAT - CNPJ - RFC - NIT - NTN - BIN - TRN - OTHER typeSourceText: type: - string - 'null' minLength: 1 maxLength: 500 number: type: string minLength: 1 maxLength: 200 required: - country - type - typeSourceText - number additionalProperties: false minItems: 1 maxItems: 10 accountPurpose: type: - string - 'null' minLength: 1 maxLength: 2000 transactionPurpose: type: - string - 'null' minLength: 1 maxLength: 2000 sourceOfFunds: type: - object - 'null' properties: categories: type: array items: type: string enum: - OPERATING_REVENUE - OWNER_OR_SHAREHOLDER_FUNDS - INVESTMENT_OR_CAPITAL - LOAN_OR_CREDIT - ASSET_SALE - GRANT_OR_DONATION - OTHER minItems: 1 maxItems: 7 explanation: type: - string - 'null' minLength: 1 maxLength: 2000 required: - categories - explanation additionalProperties: false sourceOfWealth: type: - string - 'null' minLength: 1 maxLength: 2000 occupation: type: - string - 'null' minLength: 1 maxLength: 500 required: - legalName - givenName - middleName - familyName - dateOfBirth - nationalities - residenceCountry - residentialAddress - email - phone - taxIdentifiers additionalProperties: false required: - externalId - effectiveAt - lifecycleStatus - type - individual additionalProperties: false ownership: type: object properties: relationshipExternalId: type: string minLength: 1 maxLength: 200 ownershipPercent: type: - number - 'null' exclusiveMinimum: 0 maximum: 100 required: - relationshipExternalId - ownershipPercent additionalProperties: false roles: type: array items: type: object properties: relationshipExternalId: type: string minLength: 1 maxLength: 200 role: type: string enum: - CONTROL_PERSON - DIRECTOR - OFFICER - AUTHORIZED_SIGNER - REPRESENTATIVE - OTHER required: - relationshipExternalId - role additionalProperties: false maxItems: 10 required: - customer - ownership - roles additionalProperties: false maxItems: 50 description: >- At most 50 beneficial owners, 10 roles per owner, and 100 total ownership plus role relationships dossier: type: object properties: sourceVersion: type: string minLength: 1 maxLength: 200 sourceEffectiveAt: type: string format: date-time description: >- Business-time cutoff for the complete snapshot; business, owner, document, and provider facts cannot be effective later documents: type: array items: type: object properties: documentVersionId: type: string minLength: 1 maxLength: 200 role: type: string enum: - 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 subtype: type: string minLength: 1 maxLength: 100 pattern: ^[A-Z][A-Z0-9_]*$ subject: oneOf: - type: object properties: type: type: string enum: - ROOT_CUSTOMER required: - type additionalProperties: false - type: object properties: type: type: string enum: - RELATED_PARTY externalId: type: string minLength: 1 maxLength: 200 required: - type - externalId additionalProperties: false languageTags: type: array items: type: string minLength: 2 maxLength: 35 minItems: 1 maxItems: 3 required: - documentVersionId - role - subtype - subject - languageTags additionalProperties: false maxItems: 50 providerEvidence: type: array items: oneOf: - type: object properties: sourceRecordId: type: string minLength: 1 maxLength: 200 sourceStatus: type: string minLength: 1 maxLength: 200 sourceResult: type: - string - 'null' minLength: 1 maxLength: 500 subject: oneOf: - type: object properties: type: type: string enum: - ROOT_CUSTOMER required: - type additionalProperties: false - type: object properties: type: type: string enum: - RELATED_PARTY externalId: type: string minLength: 1 maxLength: 200 required: - type - externalId additionalProperties: false sourceObservedAt: type: string format: date-time sourceOperation: type: object properties: packageId: type: string minLength: 1 maxLength: 200 operationId: type: - string - 'null' minLength: 1 maxLength: 200 required: - packageId - operationId additionalProperties: false evidenceType: type: string enum: - IDENTITY_VERIFICATION verificationType: type: string minLength: 1 maxLength: 100 context: type: string enum: - CURRENT - OTHER required: - sourceRecordId - sourceStatus - sourceResult - subject - sourceObservedAt - sourceOperation - evidenceType - verificationType - context additionalProperties: false - type: object properties: sourceRecordId: type: string minLength: 1 maxLength: 200 sourceStatus: type: string minLength: 1 maxLength: 200 sourceResult: type: - string - 'null' minLength: 1 maxLength: 500 subject: oneOf: - type: object properties: type: type: string enum: - ROOT_CUSTOMER required: - type additionalProperties: false - type: object properties: type: type: string enum: - RELATED_PARTY externalId: type: string minLength: 1 maxLength: 200 required: - type - externalId additionalProperties: false sourceObservedAt: type: string format: date-time sourceOperation: type: object properties: packageId: type: string minLength: 1 maxLength: 200 operationId: type: - string - 'null' minLength: 1 maxLength: 200 required: - packageId - operationId additionalProperties: false evidenceType: type: string enum: - SCREENING screeningCategories: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 25 findingExternalIds: type: array items: type: string minLength: 1 maxLength: 200 maxItems: 100 context: type: string enum: - CURRENT - OTHER required: - sourceRecordId - sourceStatus - sourceResult - subject - sourceObservedAt - sourceOperation - evidenceType - screeningCategories - findingExternalIds - context additionalProperties: false maxItems: 500 required: - sourceVersion - sourceEffectiveAt - documents - providerEvidence additionalProperties: false required: - business - beneficialOwners - dossier additionalProperties: false BusinessOnboardingResponse: type: object properties: business: type: object properties: outcome: type: string enum: - CREATED - VERSION_CREATED resourceId: type: string minLength: 1 versionId: type: string minLength: 1 currentVersionId: type: - string - 'null' minLength: 1 required: - outcome - resourceId - versionId - currentVersionId additionalProperties: false beneficialOwners: type: array items: type: object properties: customer: type: object properties: outcome: type: string enum: - CREATED - VERSION_CREATED resourceId: type: string minLength: 1 versionId: type: string minLength: 1 currentVersionId: type: - string - 'null' minLength: 1 required: - outcome - resourceId - versionId - currentVersionId additionalProperties: false ownership: type: object properties: resourceId: type: string minLength: 1 versionId: type: string minLength: 1 currentVersionId: type: string minLength: 1 required: - resourceId - versionId - currentVersionId additionalProperties: false roles: type: array items: type: object properties: resourceId: type: string minLength: 1 versionId: type: string minLength: 1 currentVersionId: type: string minLength: 1 role: type: string enum: - CONTROL_PERSON - DIRECTOR - OFFICER - AUTHORIZED_SIGNER - REPRESENTATIVE - OTHER required: - resourceId - versionId - currentVersionId - role additionalProperties: false required: - customer - ownership - roles additionalProperties: false dossier: type: object properties: dossierId: type: string minLength: 1 customerVersionId: type: string minLength: 1 workflowRunId: type: string minLength: 1 caseId: type: string minLength: 1 evaluationStatus: type: string enum: - QUEUED - EXISTING statusUrl: type: string minLength: 1 maxLength: 500 observedAt: type: string format: date-time required: - dossierId - customerVersionId - workflowRunId - caseId - evaluationStatus - statusUrl - observedAt additionalProperties: false required: - business - beneficialOwners - dossier additionalProperties: false Problem: type: object properties: type: type: string minLength: 1 title: type: string minLength: 1 status: type: integer detail: type: string minLength: 1 code: type: string minLength: 1 requestId: type: string minLength: 1 existingRunId: type: string minLength: 1 issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false maxItems: 20 required: - type - title - status - detail - code - requestId additionalProperties: false securitySchemes: ingestionBearer: type: http scheme: bearer description: >- Source-bound WorkOS API key or configured machine OIDC token. OIDC webhook management requires karsa:webhooks:manage. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.