> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talescria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipients

> Add the people and businesses you pay, and where to pay them.

A **recipient** is who you pay: their name, email and address. A **destination** is where you pay them: a bank account or mobile money wallet in one currency. One recipient can have several destinations, for example a GBP bank account and an NGN one.

Scopes: `recipients:read`, `recipients:write`. Your account must be verified before you can add recipients (`409 NOT_VERIFIED` otherwise).

## 1. Create the recipient

```bash curl theme={null}
curl https://api.talescria.com/v1/recipients \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: recipient-ola-nwosu" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "firstName": "Ola",
    "lastName": "Nwosu",
    "relationship": "vendor",
    "email": "ola@example.com",
    "address": {
      "line1": "14 Broad Street",
      "city": "Lagos",
      "stateOrProvince": "Lagos",
      "postalCode": "101231",
      "country": "NG"
    }
  }'
```

```python Python theme={null}
resp = requests.post(
    "https://api.talescria.com/v1/recipients",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "recipient-ola-nwosu"},
    json={
        "type": "individual",
        "firstName": "Ola",
        "lastName": "Nwosu",
        "relationship": "vendor",
        "email": "ola@example.com",
        "address": {
            "line1": "14 Broad Street",
            "city": "Lagos",
            "stateOrProvince": "Lagos",
            "postalCode": "101231",
            "country": "NG",
        },
    },
    timeout=30,
)
recipient = resp.json()["recipient"]
```

* `type: individual` needs `firstName` and `lastName`. `type: business` needs `legalName`, and optionally `tradingName`.
* `relationship` is `vendor`, `supplier`, `customer` or `employee`. Pick the one that's true: it's part of a compliance record. Contractors are usually `vendor`.
* `address.stateOrProvince` is required. Payment networks can accept a recipient without one and then refuse every payment to them.
* `phone`, if you send it, must be in international format (for example `+2348012345678`).

## 2. Find out what the destination needs

What a bank account looks like depends on the corridor: a sort code in the UK, a routing number and account type in the US, an IBAN in the eurozone, a bank and account number in Nigeria. Ask instead of hardcoding:

```bash theme={null}
curl "https://api.talescria.com/v1/destination-requirements?method=bank_transfer&currency=NGN&country=NG" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The response lists the corridor's `schemes` and `fields`. Each field has a `key`, a `label`, whether it's `required`, and optionally a `pattern` and an `example`. Call it without `method` and `currency` to list every supported corridor.

* **Keys with a dot are parts of one nested field.** `bank_address.line1` and `bank_address.city` are both parts of the bank's address. Send each one flat under `fields`, exactly as listed.
* **`pattern` is a hint.** Use it to catch typos, but don't make your checks stricter than it; the payment network has the final say.
* **More than one scheme** (for example `ach`, `wire` and `rtp` for USD) means you must choose one.

## 3. Pick the bank

Where a corridor needs a bank, list the country's banks and let the user choose:

```bash theme={null}
curl "https://api.talescria.com/v1/banks?country=NG&q=guaranty" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Send back the chosen bank's `bankId`, whole. Don't parse it, and don't also send a bank code or bank name: Talescria fills in whatever the corridor needs. An empty `banks` list is normal for some countries (the UK routes on sort codes), so fall back to the typed fields.

## 4. Add the destination

```bash curl theme={null}
curl https://api.talescria.com/v1/recipients/$RECIPIENT_ID/destinations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: dest-ola-ngn" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "bank_transfer",
    "currency": "NGN",
    "country": "NG",
    "scheme": "nip",
    "accountHolderName": "Ola Nwosu",
    "bankId": "<bankId from List banks>",
    "fields": { "account_number": "0011381002" }
  }'
```

```python Python theme={null}
resp = requests.post(
    f"https://api.talescria.com/v1/recipients/{recipient['id']}/destinations",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "dest-ola-ngn"},
    json={
        "method": "bank_transfer",
        "currency": "NGN",
        "country": "NG",
        "scheme": "nip",
        "accountHolderName": "Ola Nwosu",
        "bankId": bank["bankId"],
        "fields": {"account_number": "0011381002"},
    },
    timeout=30,
)
destination = resp.json()["destination"]
```

A field the network won't accept comes back as `422 UNSUPPORTED`, with `message` naming the field.

## What Talescria keeps

Account numbers, IBANs and phone numbers are passed to the payment network and **not stored by Talescria**. When you read a recipient, each destination shows:

| Field | Example |
| - | - |
| `label` | The bank's name, or the mobile money service. |
| `last4` | The last four digits of the account or phone number. |
| `routing` | A sort code or bank code, where it identifies a bank rather than an account. |

Keep your own copy of anything you need to show in full. Identity document numbers work the same way: you get back the document type, issuing country and last four.

## Reading recipients

* `GET /v1/recipients` lists recipients without their destinations.
* `GET /v1/recipients/{id}` includes `destinations`. If it's **absent**, they couldn't be loaded just now: retry. An **empty** array means the recipient has none yet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.