> ## 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. # Trigger a KYB run (by customer ID) > Starts a KYB run for a business customer addressed by the Karsa customer ID. Without a body the run uses the customer's current version and its currently available ingested documents; related parties and provider evidence carry forward from the customer's latest KYB dossier. Status is derived from the run and its Case: pending (queued), running, needs_review (finished with open issues for an analyst), completed (finished without open issues), or failed. Only customers owned by the calling ingestion source are visible. ## OpenAPI ````yaml /openapi/ingestion.openapi.yaml post /api/ingestion/customers/{customerId}/kyb-runs 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/customers/{customerId}/kyb-runs: post: tags: - Verifications summary: Trigger a KYB run (by customer ID) description: >- Starts a KYB run for a business customer addressed by the Karsa customer ID. Without a body the run uses the customer's current version and its currently available ingested documents; related parties and provider evidence carry forward from the customer's latest KYB dossier. Status is derived from the run and its Case: pending (queued), running, needs_review (finished with open issues for an analyst), completed (finished without open issues), or failed. Only customers owned by the calling ingestion source are visible. operationId: triggerKybRun parameters: - schema: type: string minLength: 1 description: Karsa customer ID required: true name: customerId in: path - 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: false content: application/json: schema: $ref: '#/components/schemas/KybRunTrigger' examples: currentDocuments: value: {} selectedDocuments: value: documents: - documentVersionId: document_version_example_01 role: FORMATION_DOCUMENT responses: '202': description: >- The KYB run was queued. The Location header names the run; replaying the same Idempotency-Key and body returns this response again. headers: Location: description: Path of the run status resource schema: type: string example: /api/ingestion/kyb-runs/workflow_run_example_01 content: application/json: schema: $ref: '#/components/schemas/KybRunAccepted' examples: accepted: value: id: workflow_run_example_01 status: pending customerId: customer_resource_example_01 externalCustomerId: business-example-001 caseId: case_example_01 createdAt: '2026-09-25T12:00:00.000Z' '400': description: >- INVALID_REQUEST: The body, path, or required Idempotency-Key header did not match the 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 body, path, or required Idempotency-Key header did not match the 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 '403': description: >- MACHINE_PRINCIPAL_REQUIRED: A source-bound machine principal is required TENANT_NOT_ACTIVE: The workspace is not active content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: MACHINE_PRINCIPAL_REQUIRED: value: type: https://karsa.app/problems/machine-principal-required title: Ingestion Rejected status: 403 detail: A source-bound machine principal is required code: MACHINE_PRINCIPAL_REQUIRED requestId: req_example_01 TENANT_NOT_ACTIVE: value: type: https://karsa.app/problems/tenant-not-active title: Ingestion Rejected status: 403 detail: The workspace is not active code: TENANT_NOT_ACTIVE requestId: req_example_01 '404': description: 'CUSTOMER_NOT_FOUND: The customer was not found' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: CUSTOMER_NOT_FOUND: value: type: https://karsa.app/problems/customer-not-found title: Ingestion Rejected status: 404 detail: The customer was not found code: CUSTOMER_NOT_FOUND requestId: req_example_01 '409': description: >- KYB_RUN_IN_PROGRESS: A KYB run is already queued or running; see existingRunId IDEMPOTENCY_CONFLICT: Idempotency-Key was already used with a different request content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: KYB_RUN_IN_PROGRESS: value: type: https://karsa.app/problems/kyb-run-in-progress title: Ingestion Rejected status: 409 detail: A KYB run is already queued or running; see existingRunId code: KYB_RUN_IN_PROGRESS requestId: req_example_01 IDEMPOTENCY_CONFLICT: value: type: https://karsa.app/problems/idempotency-conflict title: Ingestion Rejected status: 409 detail: Idempotency-Key was already used with a different request code: IDEMPOTENCY_CONFLICT requestId: req_example_01 '422': description: >- CUSTOMER_NOT_BUSINESS: KYB runs require a customer whose current version is a business KYB_DOCUMENTS_UNAVAILABLE: The customer has no available ingested documents KYB_DOCUMENT_METADATA_REQUIRED: Selected documents need a subtype or language; see issues INVALID_KYB_DOCUMENT_VERSION: A selected document version is not admissible content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: CUSTOMER_NOT_BUSINESS: value: type: https://karsa.app/problems/customer-not-business title: Ingestion Rejected status: 422 detail: >- KYB runs require a customer whose current version is a business code: CUSTOMER_NOT_BUSINESS requestId: req_example_01 KYB_DOCUMENTS_UNAVAILABLE: value: type: https://karsa.app/problems/kyb-documents-unavailable title: Ingestion Rejected status: 422 detail: The customer has no available ingested documents code: KYB_DOCUMENTS_UNAVAILABLE requestId: req_example_01 KYB_DOCUMENT_METADATA_REQUIRED: value: type: https://karsa.app/problems/kyb-document-metadata-required title: Ingestion Rejected status: 422 detail: Selected documents need a subtype or language; see issues code: KYB_DOCUMENT_METADATA_REQUIRED requestId: req_example_01 INVALID_KYB_DOCUMENT_VERSION: value: type: https://karsa.app/problems/invalid-kyb-document-version title: Ingestion Rejected status: 422 detail: A selected document version is not admissible code: INVALID_KYB_DOCUMENT_VERSION 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: KybRunTrigger: type: object properties: 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_]*$ language: type: string maxLength: 35 pattern: ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$ required: - documentVersionId - role additionalProperties: false minItems: 1 maxItems: 50 additionalProperties: false KybRunAccepted: type: object properties: id: type: string minLength: 1 status: anyOf: - type: string enum: - pending - running - needs_review - completed - failed - type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$ customerId: type: string minLength: 1 externalCustomerId: type: - string - 'null' minLength: 1 caseId: type: string minLength: 1 createdAt: type: string format: date-time required: - id - status - customerId - externalCustomerId - caseId - createdAt 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.