> ## 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.

# Get a case

> Fetch a case by id, including its decision `result` once the workflow
has completed. Requires the **`cases:read`** scope.

The `status` field reflects only lifecycle (`received` / `completed`),
not the outcome — read `result.decision.value` for the decision.




## OpenAPI

````yaml /api-reference/openapi.yaml get /cases/{caseId}
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/{caseId}:
    get:
      tags:
        - Cases
      summary: Get a case
      description: |
        Fetch a case by id, including its decision `result` once the workflow
        has completed. Requires the **`cases:read`** scope.

        The `status` field reflects only lifecycle (`received` / `completed`),
        not the outcome — read `result.decision.value` for the decision.
      operationId: getCase
      parameters:
        - $ref: '#/components/parameters/CaseId'
      responses:
        '200':
          description: The case.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
        '403':
          description: The API key is missing the `cases:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Case not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    CaseId:
      name: caseId
      in: path
      required: true
      description: The case identifier returned by `POST /cases`.
      schema:
        type: string
  schemas:
    Case:
      type: object
      properties:
        caseId:
          type: string
        requestId:
          type: string
        workflowId:
          type: string
        workflowVersion:
          type: integer
        type:
          type: string
          enum:
            - KYC
            - KYB
            - Transaction
        status:
          type: string
          enum:
            - received
            - in_review
            - completed
          description: >-
            Lifecycle only, not the outcome. `received` — workflow not yet
            finished (`result` absent). `in_review` — paused in a manual-review
            queue. `completed` — inspect `result.decision.value`.
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        payload:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        subject:
          $ref: '#/components/schemas/Subject'
        result:
          $ref: '#/components/schemas/CaseResult'
    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'
    CaseResult:
      type: object
      description: Present only once the workflow has completed.
      properties:
        decision:
          $ref: '#/components/schemas/Decision'
        decisionHistory:
          type: array
          description: >-
            `decisionHistory[0]` is the workflow's initial decision; later
            entries are analyst overrides.
          items:
            $ref: '#/components/schemas/Decision'
        workflow_result:
          type: object
          additionalProperties: true
          description: >-
            Raw vars emitted by the output node. Write-once — analyst overrides
            never mutate it.
        riskEvaluation:
          $ref: '#/components/schemas/RiskEvaluation'
        dataSources:
          type: array
          items:
            $ref: '#/components/schemas/DataSourceCall'
    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'
    Decision:
      type: object
      properties:
        value:
          type: string
          enum:
            - approved
            - declined
            - in_review
        source:
          type: string
          enum:
            - workflow
            - risk_evaluation
            - analyst
          description: >-
            `risk_evaluation` — decided by the pre-DAG risk gate before the
            workflow ran; `analyst` — a human overrode the decision.
        actor:
          type: string
        decidedAt:
          type: string
          format: date-time
        declineReason:
          type: string
        queueName:
          type: string
        riskScore:
          type: integer
        notes:
          type: string
    RiskEvaluation:
      type: object
      description: Audit record of the pre-DAG risk gate, when it ran. Read-only.
      properties:
        evaluatedAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - ok
            - failed_closed
        action:
          type: string
          enum:
            - deny
            - review
            - workflow
        highestSeverity:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
        triggeredRules:
          type: array
          items:
            $ref: '#/components/schemas/TriggeredRule'
    DataSourceCall:
      type: object
      description: An enrichment provider the workflow called.
      properties:
        nodeId:
          type: string
        providerId:
          type: string
        status:
          type: string
    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'
    TriggeredRule:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        severity:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
        conditions:
          type: array
          items:
            type: string
        ruleVersion:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: A tenant-scoped API key provisioned by Frayme.

````