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

# customApi

> Bespoke HTTP integration. Registries, payment-rail directories, regulators, internal services, customer callbacks.

`customApi` is the escape hatch when a target isn't in the Data Source catalogue. Holds an HTTP method + endpoint + headers + body, all templated.

## Configuration

```jsonc theme={null}
{
  "id": "ca-issuer-provision",
  "type": "customApi",
  "data": {
    "label": "Issuer — Cardholder Provisioning",
    "description": "POSTs the approved applicant to the issuer to create a cardholder. Idempotent on workflow_run_id so retries are safe.",
    "connectionName": "issuer",
    "method": "POST",
    "endpoint": "https://api.issuer.example/v1/cardholders",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer {{secrets.issuer_api_key}}",
      "X-Idempotency-Key": "{{workflow_run_id}}",
      "X-Program-Id": "card_program_v1",
    },
    "body": "{ \"program_id\": \"card_program_v1\", ... }",
    "outputVariable": "issuer_response",
    "timeout": 15000,
    "retryCount": 2,
  },
}
```

| Field            | Notes                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `connectionName` | Reference into the workflow's `connections` map. See [Connections & secrets](/workflows/connections-secrets). |
| `method`         | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.                                                                      |
| `endpoint`       | Full URL with `{{...}}` interpolation.                                                                        |
| `headers`        | Dictionary with templated values.                                                                             |
| `body`           | JSON string with templated values. Engine resolves templates then parses the JSON.                            |
| `outputVariable` | Response body parsed as JSON and written here.                                                                |
| `timeout`        | Milliseconds.                                                                                                 |
| `retryCount`     | On timeout / 5xx.                                                                                             |

## Idempotency

Outbound POSTs that create resources (cardholder provisioning, regulator submission) carry a stable idempotency header — typically `X-Idempotency-Key: {{workflow_run_id}}`. Retries don't double-create.

## Templating

Same `{{...}}` convention as the rest of the workflow:

* Workflow input: `{{input.applicant_id}}`
* Workflow parameters: `{{params.notification_callback}}`
* Upstream outputs: `{{sumsub_applicant.applicant_id}}`
* Secrets: `{{secrets.issuer_api_key}}`
* System-injected: `{{workflow_run_id}}`, `{{now_unix}}`

## Common targets

| Target type                  | Examples                                              |
| ---------------------------- | ----------------------------------------------------- |
| Identity-suite admin APIs    | Override review, generate scoped tokens               |
| Card / account issuers       | Cardholder provisioning, lifecycle propagation        |
| Tax-authority registries     | Receita Federal (Brazil), local equivalents           |
| Payment-rail directories     | PIX DICT (Brazil), Open Banking equivalents           |
| Financial Intelligence Units | COAF (Brazil), SAR filings (US), STR filings (others) |
| Internal case stores         | Applicant history, case lookup by external id         |
| Client-app callbacks         | SDK launch notification, lifecycle updates            |

## Failure handling

* Non-2xx response → node fails. Workflow either retries (up to `retryCount`) or fails the run.
* `outputVariable` is populated only on 2xx. On failure, downstream nodes reading the variable get `null`.
* The exact failure shape (status code, response body) is written to the execution history under `error`.