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

# Managing recipients

> Create and manage payment recipients

## Overview

Recipients are the businesses or individuals you send payments to. When you create a recipient, Teel automatically provisions them across all of your active payment providers, so you can pay them through any available rail.

Request bodies are **camelCase** (`businessName`, `transferType`, `paymentMethods`); responses are snake\_case at the top level, with camelCase fields inside nested payment-method objects.

## Destination types

A recipient's `transferType` sets where their funds land:

| `transferType` | Recipient receives     | Payment method                                     |
| -------------- | ---------------------- | -------------------------------------------------- |
| `fiat`         | Fiat in a bank account | Bank details (account number, routing/SWIFT, etc.) |
| `stablecoin`   | Stablecoin in a wallet | Wallet address + network                           |

Whether a `stablecoin` recipient is paid via a **Stablecoin payout** (you fund with fiat) or a **Crypto payout** (you fund with stablecoin) is decided when you execute the payout — not on the recipient.

## Step 1: Get recipient requirements

Fetch the fields required to create a recipient, based on your active providers and currencies. The response is a dynamic schema you can render as a form.

```bash theme={null}
curl https://api.teel.finance/recipients/requirements \
  -H "Authorization: Bearer $TEEL_API_KEY"
```

The schema adapts to your account — fields and required documents differ by currency and rail. Treat it as the source of truth for what to send in step 3 rather than hard-coding fields.

## Step 2: Get wallet networks

If your recipient will receive stablecoins, fetch the supported wallet networks. The response is a JSON array:

```bash theme={null}
curl https://api.teel.finance/recipients/wallet-networks \
  -H "Authorization: Bearer $TEEL_API_KEY"
```

```json theme={null}
[
  { "name": "ethereum", "displayName": "Ethereum", "chainId": 1 },
  { "name": "polygon", "displayName": "Polygon", "chainId": 137 },
  { "name": "arbitrum", "displayName": "Arbitrum", "chainId": 42161 },
  { "name": "base", "displayName": "Base", "chainId": 8453 }
]
```

Use the `name` value (e.g. `polygon`) as the `rail` on a wallet payment method.

## Step 3: Create a recipient

### Fiat recipient (bank account)

```bash theme={null}
curl -X POST https://api.teel.finance/recipients \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "businessName": "Vendor Co",
    "email": "payments@vendorco.com",
    "country": "US",
    "transferType": "fiat",
    "paymentMethods": [
      {
        "type": "bank",
        "currency": "USD",
        "rail": "ach",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "accountType": "checking"
      }
    ]
  }'
```

### Stablecoin recipient (wallet)

```bash theme={null}
curl -X POST https://api.teel.finance/recipients \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "businessName": "Crypto Vendor",
    "email": "treasury@cryptovendor.com",
    "country": "SG",
    "transferType": "stablecoin",
    "paymentMethods": [
      {
        "type": "wallet",
        "currency": "USDC",
        "rail": "polygon",
        "walletAddress": "0xRecipientWalletAddress"
      }
    ]
  }'
```

A recipient can carry **multiple payment methods** — e.g. wallets on several chains, or a bank account plus a wallet. Add more objects to `paymentMethods`. Save the `id` (a UUID) from the response — that's your `recipientId`.

The `Idempotency-Key` header is optional but recommended: a timeout-retry with the same key replays the cached response (24h window) instead of creating a duplicate recipient.

## Step 4: Auto-provisioning

When a recipient is created, Teel provisions them across all of your active payment providers in the background, so the recipient is ready to receive payments through any rail your providers support — no extra setup needed.

## Step 5: Retry failed provisioning

If provisioning fails for a provider (e.g. a transient error), retry it:

```bash theme={null}
curl -X POST https://api.teel.finance/recipients/{recipientId}/retry \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Step 6: Get recipient details

Retrieve a recipient with their per-provider counterparty status:

```bash theme={null}
curl https://api.teel.finance/recipients/{recipientId}/with-counterparty \
  -H "Authorization: Bearer $TEEL_API_KEY"
```

```json theme={null}
{
  "id": "8f3c2a91-4e5b-4d8c-9a1f-3e2b1c4d5e6f",
  "business_name": "Vendor Co",
  "email": "payments@vendorco.com",
  "country": "US",
  "transfer_type": "fiat",
  "status": "accepted",
  "created_at": "2026-03-10T10:00:00Z"
}
```

## Adding and removing payment methods

You can add payment methods to an existing recipient, or remove one, without recreating the recipient.

### Add a payment method

```bash theme={null}
curl -X POST https://api.teel.finance/recipients/{recipientId}/payment-methods \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "wallet",
    "currency": "USDC",
    "rail": "arbitrum",
    "walletAddress": "0xArbitrumAddress"
  }'
```

The new payment method is provisioned across your active providers in the background, the same way it is at recipient creation.

### Remove a payment method

```bash theme={null}
curl -X DELETE https://api.teel.finance/recipients/{recipientId}/payment-methods/{paymentMethodId} \
  -H "Authorization: Bearer $TEEL_API_KEY"
```

Both routes require the `recipients:write` scope.