Create a beneficiary record so you can attach payout destinations and use that recipient in later transaction flows.

⏱️
Time to integrate: Most teams can connect this endpoint in under 10 minutes after authentication is working and they understand which recipient data they need to collect.

What this endpoint does

Use this endpoint to create a beneficiary (a recipient profile your organization can send funds to).

A beneficiary is the parent record for payout details. You typically create the beneficiary first, then attach one or more beneficiary accounts such as bank accounts or wallets.

When to call this endpoint

Call this endpoint when you need to:

register a new recipient before sending funds
create a reusable recipient record for repeated payouts
store recipient details separately from a single transaction request
prepare a payout flow that supports validation, compliance review, and account management over time

In most integrations, this endpoint comes before adding a beneficiary account, generating a quote, and executing a transaction.

Why beneficiaries are a separate object

Keeping beneficiary data separate from the transaction lets your team:

reuse the same recipient across multiple payouts
update recipient information without rebuilding the full transaction flow
attach multiple destination accounts to one beneficiary
keep recipient management, compliance review, and transaction execution as separate steps

This structure is especially useful for enterprise teams that need stronger auditability and operational controls.

Authentication

Send your API key in the x-api-key header on every request.

Item	Value
Authentication method	API key
Required header	`x-api-key`
Rate limit scope	Per API key

Recommended workflow

Use this endpoint as part of the core recipient setup sequence:

Fetch organization accounts.
Check verification status.
Create a beneficiary.
Add a beneficiary account.
Resolve bank details if your payout flow requires pre-validation.
Generate a quote.
Execute the transaction.

What data to prepare before creating a beneficiary

Before sending the request, collect the recipient information your operating model requires.

At minimum, your team should confirm:

whether the recipient is an individual or a business
the recipient's legal or display name
the contact details you want to retain for operations or support
any compliance or onboarding metadata your workflow requires before funds can be sent

⚠️
Needs confirmation: The exact request fields, required properties, field formats, and whether beneficiary type is mandatory should be confirmed in the API definition.

Validation guidance

Before calling this endpoint, validate the input in your own application.

Recommended validation checks:

require the recipient name before submission
normalize email addresses and phone numbers if you collect them
avoid creating duplicate beneficiaries for the same recipient unless your operating model requires separate records
ensure required compliance metadata is collected before the beneficiary is used in a transaction flow

If your team expects high recipient volume, define an internal duplicate detection strategy before launch.

How to use the response

After the beneficiary is created, store the returned beneficiary ID in your backend.

You will use that ID to:

add or update beneficiary accounts
retrieve beneficiary details later
attach the correct recipient to transaction preparation flows
support internal operations, reconciliation, and customer support workflows

Common use cases

One-time recipient setup

Create a beneficiary once, attach the payout destination, generate a quote, and execute the transaction.

Reusable payout directory

Create beneficiaries as part of your customer or vendor onboarding flow so later transactions can reference existing recipient records.

Operations-managed recipient review

Create the beneficiary first, then let an internal operations or compliance team review the record before a payout destination is enabled.

Production notes

Before using this endpoint in production:

Define who is allowed to create beneficiaries.
Decide whether beneficiary creation happens automatically or after internal review.
Log the internal actor or service that created each beneficiary.
Prevent accidental duplicate creation during retries or repeated submissions.

This endpoint is often the first place where data quality issues create downstream payout failures, so validate carefully before launch.

Common failure cases

Authentication fails

Check these items first:

the x-api-key header is present
the API key belongs to the intended environment
the base URL is correct

Validation errors

If the API rejects the request:

verify all required beneficiary fields are present
check field formats before retrying
confirm your payload matches the expected beneficiary type

Duplicate or inconsistent recipient records

If your team sees multiple records for the same recipient:

add internal duplicate checks before calling the endpoint
define whether the same recipient should have one shared beneficiary or separate records by business context
make sure retries do not create multiple records unintentionally

The beneficiary is created but payouts still fail later

Creating the beneficiary does not guarantee the payout destination is valid or complete.

Next check:

beneficiary account creation
bank account resolution where applicable
quote generation inputs
transaction-specific validation

⚠️
Needs confirmation: Exact validation errors, duplicate handling behavior, and whether additional compliance checks occur at beneficiary creation time should be documented from the API schema and backend behavior.

Enterprise implementation notes

Access control

Restrict beneficiary creation to trusted backend services or approved internal operators.

Auditability

Record:

beneficiary ID
internal customer, vendor, or counterparty reference
creating service or user
creation timestamp

Data handling

Treat beneficiary data as sensitive operational data. Store only what your workflow needs, and align retention with your compliance requirements.

Troubleshooting checklist

Use this checklist if beneficiary setup is blocking your flow:

Confirm authentication with x-api-key.
Confirm the payload matches the intended recipient type.
Confirm all required fields are present and formatted correctly.
Confirm the returned beneficiary ID is stored for later steps.
Continue with beneficiary account setup before testing quote and execution flows.

Recommended next endpoints

After you create a beneficiary, continue with:

Related pages

Add Beneficiary Account

Attach a payout destination to the beneficiary you just created.

Resolve Bank Account

Validate payout account details before generating a quote or executing a transaction.

Onboard with us

Review the onboarding and compliance steps that affect beneficiary readiness in production.