> ## 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. # Upload an account > Uploads one bank-account, virtual-account, or wallet snapshot, its optional customer relationship, structured routing details, related accounts, and document links. ## OpenAPI ````yaml /openapi/ingestion.openapi.yaml post /api/ingestion/accounts 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/accounts: post: tags: - Accounts summary: Upload an account description: >- Uploads one bank-account, virtual-account, or wallet snapshot, its optional customer relationship, structured routing details, related accounts, and document links. operationId: ingestAccount 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/AccountWrite' examples: request: value: externalId: account-example-001 sourceExternalId: null customerId: customer_resource_example_01 accountKind: VIRTUAL_ACCOUNT accountType: NAMED_VIRTUAL_ACCOUNT status: ACTIVE openedAt: '2026-07-01T09:00:00.000Z' accountDetails: displayName: Primary USD collection account country: US assets: - USDC paymentRails: - ACH - WIRE - RTP - SWIFT bank: accountHolderName: Example Manufacturing LLC accountClass: BUSINESS recipientRelationship: FIRST_PARTY institutionName: Example Partner Bank institutionAddress: null beneficiaryAddress: null identifiers: - type: ACCOUNT_NUMBER value: '000123456789' paymentRail: ACH - type: ROUTING_NUMBER value: '021000021' paymentRail: ACH - type: SWIFT_BIC value: EXAMPLE0XXX paymentRail: SWIFT wallet: null relatedAccounts: [] customData: null effectiveAt: '2026-08-05T14:10:00.000Z' documents: [] responses: '200': description: A new immutable version was appended to an existing identity content: application/json: schema: $ref: '#/components/schemas/IngestionResponse' examples: success: value: outcome: VERSION_CREATED resourceId: account_resource_example_01 versionId: account_version_example_01 currentVersionId: account_version_example_01 '201': description: The stable identity and first immutable version were created content: application/json: schema: $ref: '#/components/schemas/IngestionResponse' examples: success: value: outcome: CREATED resourceId: account_resource_example_01 versionId: account_version_example_01 currentVersionId: account_version_example_01 '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: The source identity is already bound' 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: The source identity is already bound 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 security: - ingestionBearer: [] components: schemas: AccountWrite: type: object properties: externalId: type: string minLength: 1 maxLength: 200 sourceExternalId: type: - string - 'null' minLength: 1 maxLength: 200 effectiveAt: type: string format: date-time changeReason: type: - string - 'null' minLength: 1 maxLength: 500 accountKind: type: string enum: - BANK_ACCOUNT - VIRTUAL_ACCOUNT - BLOCKCHAIN_WALLET - CUSTODIAL_WALLET - OFFRAMP_WALLET - OTHER description: >- Defaults to OTHER for a new account; omission on a later POST preserves the current immutable kind accountType: type: string minLength: 1 maxLength: 200 customerId: type: - string - 'null' minLength: 1 maxLength: 200 status: type: - string - 'null' minLength: 1 maxLength: 200 openedAt: type: - string - 'null' format: date-time accountDetails: type: - object - 'null' properties: displayName: type: - string - 'null' minLength: 1 maxLength: 500 country: type: - string - 'null' minLength: 1 maxLength: 200 assets: type: array items: type: string minLength: 1 maxLength: 200 maxItems: 25 paymentRails: type: array items: type: string minLength: 1 maxLength: 200 maxItems: 25 bank: type: - object - 'null' properties: accountHolderName: type: - string - 'null' minLength: 1 maxLength: 500 accountClass: type: - string - 'null' minLength: 1 maxLength: 200 recipientRelationship: type: - string - 'null' minLength: 1 maxLength: 200 beneficiaryIndustry: 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 institutionName: type: - string - 'null' minLength: 1 maxLength: 500 institutionAddress: type: - object - 'null' properties: line1: type: - string - 'null' minLength: 1 maxLength: 500 line2: type: - string - 'null' minLength: 1 maxLength: 500 city: type: - string - 'null' minLength: 1 maxLength: 200 region: type: - string - 'null' minLength: 1 maxLength: 200 postalCode: type: - string - 'null' minLength: 1 maxLength: 200 country: type: - string - 'null' minLength: 1 maxLength: 200 required: - line1 - line2 - city - region - postalCode - country additionalProperties: false beneficiaryAddress: type: - object - 'null' properties: line1: type: - string - 'null' minLength: 1 maxLength: 500 line2: type: - string - 'null' minLength: 1 maxLength: 500 city: type: - string - 'null' minLength: 1 maxLength: 200 region: type: - string - 'null' minLength: 1 maxLength: 200 postalCode: type: - string - 'null' minLength: 1 maxLength: 200 country: type: - string - 'null' minLength: 1 maxLength: 200 required: - line1 - line2 - city - region - postalCode - country additionalProperties: false identifiers: type: array items: type: object properties: type: type: string minLength: 1 maxLength: 200 value: type: string minLength: 1 maxLength: 500 paymentRail: type: - string - 'null' minLength: 1 maxLength: 200 required: - type - value additionalProperties: false maxItems: 50 required: - accountHolderName - accountClass - recipientRelationship - institutionName - institutionAddress - beneficiaryAddress - identifiers additionalProperties: false wallet: type: - object - 'null' properties: network: type: - string - 'null' minLength: 1 maxLength: 200 address: type: - string - 'null' minLength: 1 maxLength: 500 signatureTransactionHash: type: - string - 'null' minLength: 1 maxLength: 500 custodyType: type: - string - 'null' minLength: 1 maxLength: 200 isAccountAbstraction: type: - boolean - 'null' required: - network - address - custodyType - isAccountAbstraction additionalProperties: false relatedAccounts: type: array items: type: object properties: accountId: type: string minLength: 1 maxLength: 200 relationshipType: type: string minLength: 1 maxLength: 200 required: - accountId - relationshipType additionalProperties: false maxItems: 25 default: null required: - displayName - country - assets - paymentRails - bank - wallet - relatedAccounts additionalProperties: false 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 required: - externalId - effectiveAt - accountType - customerId - status - openedAt - customData - documents additionalProperties: false IngestionResponse: 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 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.