Integration guide

A reference for partners integrating with the Frayme fraud-analysis platform.

Today, API keys, the workflow IDs you may submit cases to, and webhook configuration (URL, signing secret) are all provisioned for you by the Frayme team. In the future, both API keys and webhook configuration will be self-served from the Frayme portal.

This guide is the narrative walkthrough. For the field-level reference of each endpoint, see the API reference; for the events Frayme pushes to you, see Webhooks.

Concepts

You submit cases (KYC, KYB, or Transaction) to Frayme. Each case is routed through a tenant-defined workflow that produces a decision (approved, declined, or in_review). You can:

Submit cases via the Case API.
Poll case status via the Case API.
Receive webhooks when a decision is reached (or when an analyst later overrides it).

Authentication

All Case API calls require an API key scoped to your tenant. The key is sent on every request using the X-API-Key header:

X-API-Key: <your-api-key>

No other authentication mechanism is supported on the partner endpoints. Each key carries one or more scopes:

Scope	Grants
`cases:write`	Submit new cases (`POST /cases`), and answer an information request (`POST /cases/{caseId}/rfi/{rfiId}/response`)
`cases:read`	Read a case (`GET /cases/{caseId}`), list its paused nodes (`GET /cases/{caseId}/pending`), and list its durable actions (`GET /cases/{caseId}/actions`)
`cases:callback`	Deliver an external callback result, or invoke a pending or durable action
`tags:read`	List a case’s tags (`GET /cases/{caseId}/tags`)
`tags:write`	Add or remove a case’s tags (`POST` / `DELETE /cases/{caseId}/tags`)

Submitting a case

POST /cases — requires scope cases:write.

Request body

{
  "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.00,
      "currency": "BRL",
      "direction": "outbound",
      "method": "fiat",
      "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"
}

Do not send tenantId — your tenant is derived from the API key, and any tenantId in the body is ignored.

string

required

Provisioned for you by Frayme.

integer

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

string

required

One of KYC, KYB, or Transaction.

object

required

Validated against the workflow’s input schema. Fields and types are dictated by the workflow you target; submitting a payload that does not match the schema returns 400.

object

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

object

required

Typed business attributes used for entity resolution and review. displayName is required on every subject and is the label shown in review queues. Then set exactly one sub-struct, and it must match type: transaction for Transaction, person for KYC, business for KYB. Setting none, more than one, or the wrong one returns 400. See Subject sub-structs for the per-type required fields.

string

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

string

RFC 3339 timestamp of the originating business event (e.g. 2026-05-19T14:32:00Z). Required for Transaction cases, optional otherwise. A value that doesn’t parse, or one too far in the future, returns 400.

Subject sub-structs

displayName is required on every subject. Then set the one sub-struct matching type. Each sub-struct carries one or more identifiers that drive entity resolution.

Identifiers

An identifier is { "type": <string>, "value": <string>, "country": <string, optional> }. type must be one of the closed enum below (exact lowercase match):

`type`	Notes
`cpf`	Brazilian individual taxpayer ID
`cnpj`	Brazilian company registry ID
`passport`	Requires `country`
`national_id`	Requires `country`
`company_registration`	Requires `country`
`tax_id`	Tax identifier for countries without a dedicated type. Requires `country`; not `BR` (send `cpf` or `cnpj`)
`drivers_license`	Requires `country`
`external_customer_id`	Your own stable customer/account reference
`email`
`phone`
`wallet_address`	Crypto wallet
`pix_key`
`bank_account`	Scheme-prefixed; see Bank account formats. `country` is not required

Identifiers are classed strong (resolve identity: cpf, cnpj, passport, national_id, company_registration, tax_id, drivers_license, external_customer_id, wallet_address, pix_key) or weak (attributes only: email, phone, bank_account). A submission that doesn’t meet the per-type identifier requirements below returns 400.

Bank account formats

A bank_account value starts with a scheme, and the scheme determines the country:

Scheme	Format	Example	Countries
`IBAN`	`IBAN:<iban>`	`IBAN:DE89370400440532013000`	Any country in the SWIFT IBAN Registry, including the UK and Brazil
`USABA`	`USABA:<routing>:<account>`	`USABA:021000021:123456789`	US
`BRISP`	`BRISP:<ispb>:<branch>[-<check digit>]:<account>-<check digit>`	`BRISP:00000000:1-0:12345-X`	Brazil
`CLABE`	`CLABE:<18 digits>`	`CLABE:002010077777777771`	Mexico

Brazil accepts either IBAN or BRISP. For BRISP, the account check digit is required after a hyphen; the branch check digit is optional.
Other countries cannot send a bank_account yet.
IBAN check digits (mod-97), the US routing-number checksum and the CLABE check digit are validated. An invalid value returns 400.
bank_account is weak. It never identifies a party on its own, so a transaction party (sender or receiver) whose only identifiers are weak returns 400. Send a strong identifier with it, such as cpf, cnpj, pix_key or external_customer_id.

`Transaction` → `transaction`

Field	Type	Required	Notes
`amount`	number	yes	Must be `> 0`.
`currency`	string	yes	ISO-4217 or a registered crypto-asset code.
`additionalAmounts`	array	no	The same transaction in other currencies, each `{ "currency": <string>, "amount": <number> }`. Each `amount` must be `> 0`, each `currency` valid, never the transaction’s own `currency`, and at most one entry per currency. Stored as given, with no conversion.
`direction`	string	yes	`outbound` (sender is your customer) or `inbound` (receiver is your customer).
`method`	string	yes	`card`, `crypto` or `fiat`, matched exactly (lowercase).
`type`	string	yes	Free-form transaction type label (e.g. `pix`, `wire`). Must not be empty.
`externalTransactionId`	string	yes	Your reference for the transaction, unique per tenant.
`parties`	array	yes	Exactly one party with `role: "sender"` and exactly one with `role: "receiver"`.

Each party is { "role": "sender" | "receiver", "displayName": <string, optional>, "identifiers": [...] }. Both parties need at least one strong identifier; a party carrying only weak identifiers returns 400. The customer-side party (the sender when outbound, the receiver when inbound) must also have a non-empty displayName and an external_customer_id.

`KYC` → `person`

Field	Type	Required	Notes
`dateOfBirth`	string	no	ISO-8601.
`identifiers`	array	yes	Must include at least one document identifier (`cpf`, `passport`, or `national_id`) and an `external_customer_id`.

`KYB` → `business`

Field	Type	Required	Notes
`legalName`	string	yes
`country`	string	yes	ISO 3166-1 alpha-2.
`identifiers`	array	yes	Must include a registration identifier (`cnpj` or `company_registration`) and an `external_customer_id`.
`relatedParties`	array	no	Each `{ "role": "owner" \| "representative" \| "ubo", "displayName": <optional>, "identifiers": [...] }`; each related party needs at least one identifier.

Response

{
  "caseId": "case_01HABCXYZ...",
  "requestId": "req_01HABCXYZ...",
  "status": "received"
}

Status	Meaning
`201 Created`	New case accepted.
`200 OK`	Case already existed for the supplied `idempotencyKey`.
`400 Bad Request`	Malformed body, unknown `type`, missing required field, or payload does not match the workflow’s input schema.
`403 Forbidden`	API key is missing the `cases:write` scope.
`404 Not Found`	Workflow not found.
`409 Conflict`	The `externalTransactionId` is already recorded against another case. Resubmit with that case’s original `idempotencyKey` to get it back.

Polling case status

GET /cases/{caseId} — requires scope cases:read.

Response

{
  "caseId": "case_01HABCXYZ...",
  "requestId": "req_01HABCXYZ...",
  "workflowId": "wf_transactions_v2",
  "workflowVersion": 3,
  "type": "Transaction",
  "status": "completed",
  "createdAt": "2026-05-19T14:32:01Z",
  "completedAt": "2026-05-19T14:32:04Z",
  "payload": { "...": "..." },
  "metadata": { "...": "..." },
  "subject": { "...": "..." },
  "result": {
    "decision": {
      "value": "approved",
      "source": "workflow",
      "actor": "wf_transactions_v2",
      "decidedAt": "2026-05-19T14:32:04Z"
    },
    "decisionHistory": [
      {
        "value": "approved",
        "source": "workflow",
        "actor": "wf_transactions_v2",
        "decidedAt": "2026-05-19T14:32:04Z"
      }
    ],
    "workflow_result": { "...": "raw vars emitted by the output node" },
    "riskEvaluation": {
      "evaluatedAt": "2026-05-19T14:32:02Z",
      "status": "ok",
      "action": "workflow",
      "highestSeverity": "low",
      "triggeredRules": [
        {
          "id": "rule_high_amount",
          "name": "High amount",
          "severity": "low",
          "conditions": [ "amount > 1000" ],
          "ruleVersion": "v3"
        }
      ]
    },
    "dataSources": [
      {
        "nodeId": "node_sumsub",
        "providerId": "sumsub",
        "status": "ok"
      }
    ]
  }
}

Status values

The case status reflects only lifecycle, not the outcome — read result.decision.value for the outcome.

Status	Meaning
`received`	Case accepted; workflow not yet finished. `result` is absent.
`completed`	Workflow finished. Inspect `result.decision.value` — `approved`, `declined`, or `in_review` (awaiting analyst decision).

Notes:

result is absent until the workflow completes.
result.decision.value is one of approved, declined, or in_review.
result.decision is always the current decision; result.decisionHistory[0] is the workflow’s initial decision, and later entries are analyst overrides.
result.decision.source is one of workflow, risk_evaluation, or analyst. risk_evaluation means the case was decided by the pre-DAG risk gate before the workflow ran; analyst means a human overrode the decision.
Each decision entry (current and historical) may also carry optional fields: declineReason, queueName, riskScore, and notes. They are present only when set.
result.workflow_result is write-once: analyst overrides never mutate it.
result.riskEvaluation is the audit record of the pre-DAG risk gate (when it ran): status (ok / failed_closed), action (deny / review / workflow), highestSeverity (low / medium / high / critical), and a list of triggeredRules (each with id, name, severity, conditions, ruleVersion). Treat it as read-only audit evidence.
result.dataSources (when present) lists the enrichment providers the workflow called, each with nodeId, providerId, and status.

Poll on a backoff (for example, 1s, 2s, 5s, then every 10s) until status is completed, then read result.decision.value. Prefer webhooks over long polling whenever possible.

Webhooks

Frayme delivers signed HTTPS POSTs to a URL configured for you. The dedicated Webhooks page is the canonical reference for every event, payload shape, and signature-verification detail.

Events you may receive

`event_type`	When	Body shape
`case.decided`	Workflow finished with `approved` or `declined`.	Decision payload
`case.pending_review`	Workflow finished with `in_review`; case is now in a queue.	Decision payload
`case.decision_overridden`	An analyst overrode an existing decision.	Decision payload (the new `result.decision` reflects the override)
`external_callback.dispatch`	Your tenant uses a workflow node that pauses for an external system. Frayme is asking that system to perform work and post back to a one-time callback URL.	External callback dispatch payload
`node.notification`	A workflow node configured to notify emitted output mid-run — for example, a Sumsub node publishing a hosted verification link and a pending-action handle before it pauses for review.	Node notification payload
`case.rfi_requested`	An information request was raised on a case by an analyst or a workflow node. Your systems send the resulting email — Frayme never does.	Information request payload
`case.rfi_answered`	An information request was answered. Attribution and counts only, no answer content.	Information request answered payload

Payload shapes

Decision payload
External callback dispatch
Node notification

Sent for case.decided, case.pending_review, and case.decision_overridden.

{
  "webhookId": "8f1d2e6c-3a4b-4c5d-9e8f-0a1b2c3d4e5f",
  "event_type": "case.decided",
  "case_id": "case_01HABCXYZ...",
  "tenant_id": "tenant_01HABCXYZ...",
  "result": {
    "decision": {
      "value": "approved",
      "source": "workflow",
      "actor": "wf_transactions_v2",
      "decidedAt": "2026-05-19T14:32:04Z"
    },
    "decisionHistory": [ "..." ],
    "workflow_result": { "...": "..." }
  },
  "timestamp": "2026-05-19T14:32:04Z"
}

Sent for external_callback.dispatch. The receiving system performs its work, then calls back (see Delivering an external callback) before expiresAt.

{
  "webhookId": "1c2b3a4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "event_type": "external_callback.dispatch",
  "tenantId": "tenant_01HABCXYZ...",
  "caseId": "case_01HABCXYZ...",
  "nodeId": "node_partner_review",
  "webhookKey": "partner-review",
  "callbackUrl": "https://core.us.api.frayme.io/cases/case_01HABCXYZ/callbacks/cbk_oneTimeToken",
  "expiresAt": "2026-05-19T15:32:04Z",
  "payload": { "...": "node-specific input" }
}

Sent for node.notification when a node configured to notify emits output. payloadType identifies the output schema (for example, sumsub-application-start); output carries the node’s emitted fields, including a pending_handle when the node also exposes pending actions.

{
  "webhookId": "3f2a1b0c-9d8e-7f6a-5b4c-3d2e1f0a9b8c",
  "event_type": "node.notification",
  "payloadType": "sumsub-application-start",
  "tag": "kyc-onboarding",
  "tenantId": "tenant_01HABCXYZ...",
  "caseId": "case_01HABCXYZ...",
  "nodeId": "node_sumsub",
  "webhookKey": "kyc-links",
  "output": {
    "applicant_id": "6a3d4ca539de5a064a06f245",
    "external_user_id": "tenant_01HABCXYZ:cust-00481:node_sumsub",
    "verification_url": "https://in.sumsub.com/websdk/p/abc123",
    "sdk_token": "_act-sbx-jwt-...",
    "sdk_token_expires_at": "2026-05-19T15:00:00Z",
    "pending_handle": "84147546-1b38-46d9-95ed-537d0dd4945e"
  }
}

event_type is the only snake_case key; identity keys are camelCase. payloadType and tag appear only when configured on the node. The output keys depend on the node’s provider and configuration.The same node.notification event carries other payloadTypes too. A Sumsub node that allows retries emits sumsub-retry-requested each time the applicant must resubmit — see Data sources → Sumsub → Resubmission retries.

Deduplication via `webhookId`

Every outbound webhook (decision events and dispatch events alike) carries a unique webhookId (UUID). Frayme’s delivery is at-least-once — a transient failure or network blip can produce duplicate deliveries with the same webhookId. Persist the webhookId of every event you successfully process and reject (or short-circuit) any event whose webhookId you’ve seen before.

Headers

Header	Value
`X-Frayme-Signature`	HMAC-SHA256 of the raw request body, keyed by your signing secret, hex-encoded.
`X-Frayme-Secret-ID`	(When set) identifier of the active signing secret — used during secret rotation.
`Content-Type`	`application/json`

Verifying the signature

import hmac, hashlib

expected = hmac.new(SIGNING_SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers["X-Frayme-Signature"]):
    return 401

Compute HMAC over the exact bytes of the request body — do not re-serialize the JSON.
Use a constant-time comparison (for example, hmac.compare_digest).
If X-Frayme-Secret-ID is present, pick the matching secret from your rotation set.
Respond 2xx within ~10 seconds (the per-delivery timeout). Non-2xx responses and timeouts are retried with exponential backoff — 1s, 2s, 4s, 8s, 16s — up to the configured retry limit (5 attempts by default); final failures are recorded but not retried indefinitely.
Treat deliveries as at-least-once; deduplicate by webhookId as described above.

Delivering an external callback

Used only if your workflow has a node that pauses awaiting an external system. After receiving an external_callback.dispatch webhook, the external system posts the result to the one-time URL from the dispatch payload: POST /cases/{caseId}/callbacks/{callbackRef} — requires scope cases:callback.

Content-Type: application/json; the body is a JSON object the workflow node consumes.

Status	Meaning
`202 Accepted`	Callback accepted.
`409 Conflict`	The callback was already consumed.
`404 Not Found`	The token is invalid or expired.
`401 Unauthorized`	No API key was supplied.
`403 Forbidden`	The key lacks the `cases:callback` scope.

Answering an information request

An information request asks a case’s customer for more information. One is raised by an analyst in the Frayme console or by a workflow node — raising one is not yet part of the published Case API — and it publishes a case.rfi_requested webhook to your endpoint; your systems send the actual email, Frayme never does. That webhook carries the rfi_id you need below. A case with a request outstanding also reports openRfiCount: 1 on GET /cases/{caseId}, and only one request may be open per case at a time. When the case reaches a terminal decision, any pending request is cancelled silently — you receive the case.decided webhook, never a cancel event.

The case.rfi_requested webhook carries customer PII — to, cc, subject, and body. Keep it out of your logs, including on redelivery, and see the webhook PII warning.

When your customer replies, your backend finishes the request in two steps: upload each document into a presigned slot, then submit the answer. Both routes require scope cases:write, and the request must still be pending.

Mint an upload slot, once per file

POST /cases/{caseId}/rfi/{rfiId}/documents

{ "filename": "proof_of_address.pdf", "contentType": "application/pdf", "sizeBytes": 348211 }

201 Created returns { "uploadId", "uploadUrl", "expiresAt" }. Accepted types are application/pdf, image/jpeg, and image/png, at 1 byte – 20 MB.Every slot you mint counts against the budget for good, even one you never upload to or that expires: 30 per request, 100 per case (a response attaches at most 10 documents). Exceeding it is 422 too_many_documents. A request that can no longer take documents is 409 — already_answered, not_pending, case_terminal, or dry_run.

PUT the bytes

PUT the file to uploadUrl before expiresAt, with exactly the Content-Type and Content-Length you declared and the header If-None-Match: * — all three are pinned into the signature and the upload is rejected otherwise.

PUT {uploadUrl}
Content-Type: application/pdf
Content-Length: 348211
If-None-Match: *

The URL is create-only: once the object exists a second PUT returns 412 Precondition Failed, so an upload cannot be replaced once it has landed. expiresAt also bounds step 3 — a slot not attached by then is refused, and you mint a fresh one.

Frayme does not inspect file content. The Content-Type you declare is pinned into the signature and checked against the stored object’s header, but the bytes are never sniffed, validated, or scanned for malware. Scan files you collect from end customers before uploading them — an attached document is shown to analysts and may be read by an AI workflow node.

Submit the answer, once

POST /cases/{caseId}/rfi/{rfiId}/response

{
  "fields": [
    { "key": "occupation", "value": "Software engineer" },
    { "key": "monthly_income_eur", "value": 6500, "label": "Monthly income" }
  ],
  "documents": [{ "uploadId": "9a2e4d71-0b83-4c17-8f5a-1d6e7c0b3a49", "label": "Proof of address" }]
}

200 OK returns { "rfiId", "status": "answered", "answeredAt", "fieldCount", "documentCount" }.

fields is an ordered array of scalar answers (string, number, boolean, null). Each entry’s key is an identifier (^[A-Za-z_][A-Za-z0-9_]*$) and must be unique across the array — a repeat is 422 invalid_field_key, never a silent last-one-wins. Limits: ≤ 100 entries, ≤ 4 KB per value, ≤ 16 KB in total. At least one field or document is required. The console shows the answers in the order you send them. Each entry may carry an optional label, a human display name for the console (≤ 256 bytes, counted against the same 16 KB total). Labels are display-only — they are never bound into the workflow, so rules keep matching on the key. Every uploadId must have been minted for this request and its object must already be in the bucket with the declared size and type — a minted-but-never-uploaded slot fails the whole submission, and nothing is recorded partially.

Status	Meaning
`409 Conflict`	`already_answered` (with `answeredBy` and `answeredAt`), `not_pending`, `case_terminal`, or `dry_run`.
`422 Unprocessable Entity`	`document_not_uploaded` (with `uploadId`), `invalid_field_key` (malformed or repeated key) / `invalid_field_value` (with `key`), `fields_too_large`, or `too_many_documents` (more than 10 documents in one submission).

A request is answered once — there is no amend and no re-open; a follow-up is a new request. answeredBy is apikey:<keyId> when a key answered, so a retry after a lost response recognises its own answer, or analyst when an analyst recorded the reply in the console.

A successful answer publishes case.rfi_answered and, when the request was raised by an awaiting Information request workflow node, resumes the workflow with the answers available to its rules.

Tagging a case

Tags are short, non-PII operator labels used to organise and triage cases (for example high-risk, review-later) — the same labels analysts apply in the Frayme console. Your tenant is taken from the API key, so tag paths are not tenant-scoped in the URL. Tags applied via the API must come from your tenant’s managed tag vocabulary, configured under Settings → Tags in the portal. An arbitrary label is rejected, so the console’s chips, colours, and filters stay consistent. Add a tag — POST /cases/{caseId}/tags, requires scope tags:write.

{ "tag": "high-risk" }

Both success responses return the stored tag as { "tag", "createdBy", "createdAt" }. The applier is recorded as your API key (createdBy: "apikey:<keyId>"); any createdBy in the request body is ignored.

Status	Meaning
`201 Created`	The tag was newly applied.
`200 OK`	The case already carried the tag (idempotent re-apply); the body reflects the originally stored `createdBy` / `createdAt`.
`400 Bad Request`	The tag is empty, exceeds 64 characters, or is not an enabled option in your managed vocabulary.
`403 Forbidden`	The key lacks the `tags:write` scope.
`502 Bad Gateway`	The tag vocabulary could not be resolved right now; retry.

List a case’s tags — GET /cases/{caseId}/tags, requires scope tags:read. Returns { "tags": [ { "tag", "createdBy", "createdAt" } ] }, oldest-first (an empty array for an untagged case). Remove a tag — DELETE /cases/{caseId}/tags?tag=<label>, requires scope tags:write. Idempotent: removing an absent tag still returns 204 No Content.

Pending actions on a paused node

Some workflow nodes pause to await an external review — a Sumsub identity check, for example — and while paused they expose named actions you can invoke. Unlike an external callback (which resolves the node and resumes the workflow), a pending action is a side effect on the paused node: it returns data and leaves the node paused. Typical uses are re-minting an expiring access token or verification link, or pushing applicant data to the provider before the end user starts.

Handles

Each paused node is addressed by an opaque pending_handle:

It is per-paused-node and stable across retries — the same paused node always resolves to the same handle.
It is tenant-scoped: a handle from another tenant resolves to 404 (handle existence is never revealed across tenants).
It expires with the node’s await window (expiresAt); after that, invoking it returns 404.

You obtain a handle in one of two ways:

From a node.notification webhook — the output.pending_handle field (see Webhooks).
By listing the case’s paused nodes (below).

List paused nodes

GET /cases/{caseId}/pending — requires scope cases:read.

{
  "pending": [
    {
      "nodeId": "node_sumsub",
      "providerId": "sumsub",
      "pendingHandle": "84147546-1b38-46d9-95ed-537d0dd4945e",
      "expiresAt": "2026-05-19T15:32:04Z",
      "availableActions": [
        { "id": "refresh_sdk_token", "label": "Refresh SDK Token", "resolvesAwait": false },
        { "id": "regenerate_link", "label": "Regenerate Verification Link", "resolvesAwait": false },
        { "id": "prefill_applicant_info", "label": "Prefill Applicant Info", "resolvesAwait": false },
        { "id": "prefill_company_info", "label": "Prefill Company Info", "resolvesAwait": false },
        { "id": "reset_level_step", "label": "Reset Verification Steps", "resolvesAwait": false },
        { "id": "reset_applicant", "label": "Reset Applicant", "resolvesAwait": false }
      ]
    }
  ]
}

availableActions is provider-specific — it lists exactly the ids you may invoke on that node. resolvesAwait is false for every action available today (all are side effects).

Invoke an action

POST /pending/{handle}/actions/{actionId} — requires scope cases:callback.

{
  "params": { "...": "action-specific, see the provider's page" }
}

The body is { "params": { ... } }; an empty body is valid for actions that take no parameters. The response wraps the action’s output:

{
  "output": { "...": "action-specific fields" }
}

Status	Meaning
`200 OK`	Action performed; `output` carries its result.
`400 Bad Request`	Unknown action for this node, or invalid/missing params.
`401 Unauthorized`	No API key was supplied.
`403 Forbidden`	The key lacks the `cases:callback` scope.
`404 Not Found`	The handle is unknown, expired, already resolved, or belongs to another tenant.
`502 Bad Gateway`	The upstream provider rejected or failed the action.

The available actions and their params depend on the node’s provider. For Sumsub, see Data sources → Sumsub → Real-time actions on a paused node.

Durable case actions

A pending action only exists while a node is paused — once the case is decided, the handle is gone. Some provider operations, though, stay meaningful long after the case has finished. The clearest example is re-issuing a Sumsub share token so a partner client can access the applicant months later. For those, Frayme exposes durable case actions, addressed by caseId (no handle) and scoped to the broker that owns them — so they work from the moment the node ran, through the decision, and indefinitely afterward.

Durable case actions are addressed by (brokerId, action) so action ids never collide across brokers. The applicant is re-resolved from the case’s external_customer_id — so the case must have been submitted with one (it is required on every case type).

List durable actions

GET /cases/{caseId}/actions — requires scope cases:read. Lists the durable actions invocable on the case, derived from the brokers it actually ran:

{
  "actions": [
    { "brokerId": "sumsub", "id": "regenerate_share_token", "label": "Regenerate Share Token" }
  ]
}

Invoke a durable action

POST /cases/{caseId}/actions/{brokerId}/{action} — requires scope cases:callback.

{
  "params": { "...": "action-specific, see the provider's page" }
}

The response wraps the action’s output, exactly like a pending action:

{
  "output": { "...": "action-specific fields" }
}

Status	Meaning
`200 OK`	Action performed; `output` carries its result.
`400 Bad Request`	Invalid body, or a required param is missing.
`401 Unauthorized`	No API key was supplied.
`403 Forbidden`	The key lacks the `cases:callback` scope.
`404 Not Found`	The case or action is unknown, or belongs to another tenant.
`422 Unprocessable Entity`	The case has no `external_customer_id` to resolve the applicant from.
`502 Bad Gateway`	The upstream provider rejected or failed the action.

Each invocation is an independent vendor call — there is no idempotency, so a retry mints a new artifact. Use the returned value rather than calling again “to be safe”.

For Sumsub, see Data sources → Sumsub → Regenerate a share token.

Quick reference

Action	Method and path	Scope
Submit a case	`POST /cases`	`cases:write`
Get a case	`GET /cases/{caseId}`	`cases:read`
List paused nodes on a case	`GET /cases/{caseId}/pending`	`cases:read`
Invoke a pending action	`POST /pending/{handle}/actions/{actionId}`	`cases:callback`
List durable case actions	`GET /cases/{caseId}/actions`	`cases:read`
Invoke a durable case action	`POST /cases/{caseId}/actions/{brokerId}/{action}`	`cases:callback`
Deliver an external callback	`POST /cases/{caseId}/callbacks/{callbackRef}`	`cases:callback`
Mint an upload slot for a reply	`POST /cases/{caseId}/rfi/{rfiId}/documents`	`cases:write`
Answer an information request	`POST /cases/{caseId}/rfi/{rfiId}/response`	`cases:write`
List a case’s tags	`GET /cases/{caseId}/tags`	`tags:read`
Add a tag	`POST /cases/{caseId}/tags`	`tags:write`
Remove a tag	`DELETE /cases/{caseId}/tags?tag=`	`tags:write`

All requests authenticate via the X-API-Key header. The base URL of the Case API and your webhook configuration (URL, signing secret, secret ID, retry policy) are provided by Frayme — these will move to self-service in the portal.

​Concepts

​Authentication

​Submitting a case

​Request body

​Subject sub-structs

​Identifiers

​Bank account formats

​Transaction → transaction

​KYC → person

​KYB → business

​Response

​Polling case status

​Response

​Status values

​Webhooks

​Events you may receive

​Payload shapes

​Deduplication via webhookId

​Headers

​Verifying the signature

​Delivering an external callback

​Answering an information request

​Tagging a case

​Pending actions on a paused node

​Handles

​List paused nodes

​Invoke an action

​Durable case actions

​List durable actions

​Invoke a durable action

​Quick reference

Concepts

Authentication

Submitting a case

Request body

Subject sub-structs

Identifiers

Bank account formats

`Transaction` → `transaction`

`KYC` → `person`

`KYB` → `business`

Response

Polling case status

Response

Status values

Webhooks

Events you may receive

Payload shapes

Deduplication via `webhookId`

Headers

Verifying the signature

Delivering an external callback

Answering an information request

Tagging a case

Pending actions on a paused node

Handles

List paused nodes

Invoke an action

Durable case actions

List durable actions

Invoke a durable action

Quick reference