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

# Use the Case API

> What to collect in the console, how to submit a case with curl, and how to follow it to a decision.

## What you need from the portal

* An API key with **Create cases** and **Read cases** ([API keys](/guides/engineer/api-keys)).
* The `workflowId` and, optionally, the version from the builder's URL and toolbar.
* A webhook config to receive the decision ([Webhooks](/guides/engineer/webhooks)).

## Submit a case

```bash theme={null}
curl -X POST "$FRAYME_API/cases" \
  -H "X-API-Key: $FRAYME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "wf-docs-onboarding",
    "type": "Transaction",
    "idempotencyKey": "order-9f8e7d6c",
    "subject": {
      "displayName": "Beatriz Nogueira",
      "transaction": {
        "amount": 50000, "currency": "USD", "direction": "outbound",
        "method": "fiat", "type": "wire", "externalTransactionId": "txn-20260916-0001",
        "parties": [
          { "role": "sender", "displayName": "Beatriz Nogueira",
            "identifiers": [ { "type": "external_customer_id", "value": "cust-beatriz-nogueira" },
                             { "type": "email", "value": "beatriz.nogueira@example.com" } ] },
          { "role": "receiver", "identifiers": [ { "type": "pix_key", "value": "beneficiary-001" } ] }
        ]
      }
    },
    "payload": { "document_number": "CPF-529.982.247-25", "document_type": "cpf", "country_code": "BR", "amount": 50000 },
    "metadata": { "source": "checkout-service" }
  }'
```

The response is `201` with `{ "caseId": "...", "requestId": "...", "status": "received" }`. Repeating the same `idempotencyKey` returns the existing case with `200`. The payload is validated against the Input node's schema; the transaction subject needs `method`, a unique `externalTransactionId` and exactly one sender party.

## Poll or wait for the webhook

`GET /cases/{caseId}` returns `status` (`received`, `pending_review`, `decided`) and `result.decision`. Prefer the webhook: `case.pending_review` arrives when the case reaches an analyst, `case.decided` when it is decided, `case.decision_overridden` if a manager corrects it.

## Tags via API

`POST /cases/{caseId}/tags` with `{ "tag": "High Risk" }` applies a tag from the managed vocabulary in **Settings → Tags**; anything else is rejected with 400. Needs the **Manage tags** scope.

## Raise an information request via API

`POST /cases/{caseId}/rfi` with a `templateId` (or literal subject and body) and an `rfiId` idempotency key. One open request per case.

## Full reference

Field-level documentation, error codes and the webhook payloads are in the [Integration guide](/integration/guide) and the [API reference](/api-reference/introduction).