> ## Documentation Index > Fetch the complete documentation index at: https://docs.frayme.io/llms.txt > Use this file to discover all available pages before exploring further. # Submit a case > Submit a new case. Requires the **`cases:write`** scope. The case is routed through the tenant-defined workflow you target and produces a decision (`approved`, `declined`, or `in_review`). If `idempotencyKey` is supplied and a case with the same key already exists, the existing case is returned with `200 OK` instead of `201 Created`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /cases openapi: 3.1.0 info: title: Frayme Case API version: 1.0.0 description: > The partner-facing HTTP API for the Frayme fraud-analysis platform. Submit **cases** (KYC, KYB, or Transaction), poll their status, act on paused workflow nodes, and deliver external callbacks. All requests authenticate with a tenant-scoped API key sent in the `X-API-Key` header. Each key carries one or more **scopes** — the required scope is listed on every operation below. | Scope | Grants | | --- | --- | | `cases:write` | Submit new cases (`POST /cases`) | | `cases:read` | Read a case, list paused nodes, list durable actions | | `cases:callback` | Deliver an external callback, or invoke a pending / durable action | Your tenant is derived from the API key — never send `tenantId` in a request body; it is ignored. The base URL and your webhook configuration are provisioned for you by Frayme. servers: - url: https://core.us.api.frayme.io description: Production. - url: https://core.us.api.stg.frayme.io description: Staging. security: - apiKeyAuth: [] tags: - name: Cases description: Submit and read cases. - name: Pending actions description: Act on a workflow node that is paused awaiting an external system. - name: Durable actions description: Invoke a broker action on a case after it has been decided. - name: Callbacks description: Deliver the result of an external callback back to a paused node. paths: /cases: post: tags: - Cases summary: Submit a case description: | Submit a new case. Requires the **`cases:write`** scope. The case is routed through the tenant-defined workflow you target and produces a decision (`approved`, `declined`, or `in_review`). If `idempotencyKey` is supplied and a case with the same key already exists, the existing case is returned with `200 OK` instead of `201 Created`. operationId: createCase requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCaseRequest' example: workflowId: wf_transactions_v2 workflowVersion: 3 type: Transaction payload: documentNumber: DOC-001-BR documentType: cpf countryCode: BR metadata: source: checkout-service subject: displayName: Maria Silva transaction: amount: 1250 currency: BRL direction: outbound type: pix externalTransactionId: txn-9f8e7d6c parties: - role: sender displayName: Maria Silva identifiers: - type: cpf value: '52998224725' country: BR - type: external_customer_id value: cust-00481 - role: receiver displayName: Acme Pagamentos Ltda identifiers: - type: pix_key value: a1b2-evp-key idempotencyKey: order-9f8e7d6c eventTimestamp: '2026-05-19T14:32:00Z' responses: '200': description: A case already existed for the supplied `idempotencyKey`. content: application/json: schema: $ref: '#/components/schemas/CreateCaseResponse' '201': description: New case accepted. content: application/json: schema: $ref: '#/components/schemas/CreateCaseResponse' example: caseId: case_01HABCXYZ requestId: req_01HABCXYZ status: received '400': description: >- Malformed body, unknown `type`, missing required field, or the payload does not match the workflow's input schema. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- The API key is missing the `cases:write` scope, or the request's `tenantId` does not match the key's tenant. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Workflow not found. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateCaseRequest: type: object required: - workflowId - type - payload - subject properties: workflowId: type: string description: >- The workflow to route this case through. Provisioned for you by Frayme. workflowVersion: type: integer description: >- Pin the version your client expects. If omitted, the workflow's current published version is used. type: type: string enum: - KYC - KYB - Transaction description: The case type. Determines which `subject` sub-struct is required. payload: type: object additionalProperties: true description: >- Validated against the workflow's input schema. Fields and types are dictated by the workflow you target; a payload that does not match the schema returns `400`. metadata: type: object additionalProperties: true description: Free-form audit fields; surfaced in the portal and event log. subject: $ref: '#/components/schemas/Subject' idempotencyKey: type: string description: >- If provided and a case with the same key already exists, the existing case is returned with `200 OK` instead of `201 Created`. eventTimestamp: type: string format: date-time description: ISO-8601 timestamp of the originating business event. CreateCaseResponse: type: object properties: caseId: type: string requestId: type: string status: type: string description: Lifecycle status of the newly-created case (e.g. `received`). Error: type: object properties: error: type: string description: A human-readable error message. Subject: type: object required: - displayName description: >- Typed business attributes used for entity resolution and review. Set **exactly one** sub-struct, and it must match `type`: `transaction` for `Transaction`, `person` for `KYC`, `business` for `KYB`. properties: displayName: type: string description: The label shown in review queues. Required on every subject. transaction: $ref: '#/components/schemas/TransactionSubject' person: $ref: '#/components/schemas/PersonSubject' business: $ref: '#/components/schemas/BusinessSubject' TransactionSubject: type: object required: - amount - currency - direction - parties properties: amount: type: number description: Must be greater than 0. currency: type: string description: ISO-4217 or a registered crypto-asset code. amountUsd: type: number description: Required (and > 0) when `currency` is a crypto asset. direction: type: string enum: - outbound - inbound description: >- `outbound` (sender is your customer) or `inbound` (receiver is your customer). type: type: string description: Free-form transaction type label (e.g. `pix`, `wire`). externalTransactionId: type: string description: Your reference for the transaction. parties: type: array description: >- Exactly one party with `role: sender` and at least one with `role: receiver`. The customer-side party (sender when `outbound`, first receiver when `inbound`) must have a non-empty `displayName` and at least one strong identifier. items: $ref: '#/components/schemas/Party' PersonSubject: type: object required: - identifiers properties: dateOfBirth: type: string format: date description: ISO-8601. identifiers: type: array description: >- Must include at least one document identifier (`cpf`, `passport`, or `national_id`) and an `external_customer_id`. items: $ref: '#/components/schemas/Identifier' BusinessSubject: type: object required: - legalName - country - identifiers properties: legalName: type: string country: type: string description: ISO 3166-1 alpha-2. identifiers: type: array description: >- Must include a registration identifier (`cnpj` or `company_registration`) and an `external_customer_id`. items: $ref: '#/components/schemas/Identifier' relatedParties: type: array items: $ref: '#/components/schemas/RelatedParty' Party: type: object required: - role properties: role: type: string enum: - sender - receiver displayName: type: string identifiers: type: array items: $ref: '#/components/schemas/Identifier' Identifier: type: object required: - type - value description: >- Drives entity resolution. Identifiers are classed **strong** (resolve identity) or **weak** (attributes only). `passport`, `national_id`, and `company_registration` require `country`. properties: type: type: string enum: - cpf - cnpj - passport - national_id - company_registration - external_customer_id - email - phone - wallet_address - pix_key value: type: string country: type: string description: >- ISO 3166-1 alpha-2. Required for `passport`, `national_id`, `company_registration`. RelatedParty: type: object required: - role properties: role: type: string enum: - owner - representative - ubo displayName: type: string identifiers: type: array items: $ref: '#/components/schemas/Identifier' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: A tenant-scoped API key provisioned by Frayme. ````