Skip to main content
POST
/
cases
Submit a case
curl --request POST \
  --url https://core.us.api.frayme.io/cases \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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"
}
'
{
  "caseId": "<string>",
  "requestId": "<string>",
  "status": "<string>"
}

Authorizations

​
X-API-Key
string
header
required

A tenant-scoped API key provisioned by Frayme.

Body

application/json
​
workflowId
string
required

The workflow to route this case through. Provisioned for you by Frayme.

​
type
enum<string>
required

The case type. Determines which subject sub-struct is required.

Available options:
KYC,
KYB,
Transaction
​
payload
object
required

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.

​
subject
object
required

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.

​
workflowVersion
integer

Pin the version your client expects. If omitted, the workflow's current published version is used.

​
metadata
object

Free-form audit fields; surfaced in the portal and event log.

​
idempotencyKey
string

If provided and a case with the same key already exists, the existing case is returned with 200 OK instead of 201 Created.

​
eventTimestamp
string<date-time>

ISO-8601 timestamp of the originating business event.

Response

A case already existed for the supplied idempotencyKey.

​
caseId
string
​
requestId
string
​
status
string

Lifecycle status of the newly-created case (e.g. received).