Recipients (payers)

GET /v1/recipients returns the people and businesses that have paid you. There is no recipients table to maintain: payers are derived on the fly by grouping inbound transactions by counterparty name and account number.

Do not confuse payers with beneficiaries: payers are money in, beneficiaries are saved money-out destinations.

Endpoint

Method	Path	Scope	Success
`GET`	`/v1/recipients`	`read`	`200`

curl https://api.nuansis.co/v1/recipients \
  -H "Authorization: Bearer $NUANSIS_API_KEY"

{
  "data": [
    {
      "name": "ADAEZE OKAFOR",
      "email": null,
      "account_number": "0123456789",
      "currency": "NGN",
      "channels": ["collection_va", "reserved_va"],
      "total_in": 475000,
      "count": 3,
      "last_at": "2026-10-18T10:26:07.412Z"
    }
  ],
  "meta": { "request_id": "1f2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c" }
}

Fields

Field	Meaning
`name`	Counterparty name from the ledger, or `Unknown`
`email`	Best available counterparty email, or `null`
`account_number`	Counterparty account
`currency`	Currency of the grouped transactions
`channels`	Distinct channels that produced the inbound rows
`total_in`	Sum of inbound amounts
`count`	Number of inbound transactions
`last_at`	Timestamp of the most recent inbound payment

Grouping rules

A payer row is produced from transactions where:

type = 'credit'
direction = 'in', or direction is null (legacy rows)
category != 'convert'
counterparty_account is not null
status is completed, pending, or processing

Rows are grouped by (counterparty_name, counterparty_account, currency) and ordered by last_at descending. Because grouping happens at query time, the list reflects the ledger immediately — there is no sync delay and no separate id. There is also no pagination: the full grouped set for the workspace is returned.

If two different people pay from the same account number under different names, they appear as two rows. If the same person pays from two accounts, they appear as two rows as well.

Common errors

Status	Code	Cause
`401`	`unauthorized`	Missing or invalid API key
`403`	`insufficient_scope`	Key lacks `read` and holds no `*:write` scope
`429`	`rate_limited`	Request budget exhausted