Recipients

Recipient APIs expose the Recipients service: intra-FI saved payees for the authenticated user. Use them to list, create, update, and delete recipients (and to validate a recipient before posting a transfer). They complement the Transfers APIs—define who can be paid, then initiate movement to that payee.

End-user benefits

• Manage a list of trusted recipients for quick transfers.

Integration capabilities

• Manage transfer recipients (create, retrieve, update, delete).
• Validate recipients before initiating transfers.

Scopes

Scope	Description
recipients:read	Read recipient information
recipients:write	Create, update, and delete recipients
recipients:delete	Delete recipients

Required headers

Header	Description
Authorization	Bearer token (V2 authentication)
transactionId	Unique identifier for request tracking

Error codes (REC_*)

Code	Message	HTTP Status Code
REC_10005	User not found at host	400
REC_10006	Invalid passcode	400
REC_10007	Invalid account	400
REC_10008	Test lucky transfer failed	500
REC_10009	Invalid query param	400
REC_11001	Full authentication was not provided in the request	401
REC_11002	The authentication token is invalid	401
REC_11003	The authentication does not authorize this request	403
REC_11004	InstitutionId is invalid or incorrectly configured	400
REC_12001	Request should only contain printable ASCII characters	400
REC_12002	Request is missing a transactionId header	400
REC_12003	Request transactionId header is too long	400
REC_12004	Required fields are not provided or not valid	400
REC_12005	Request cannot be blank	400
REC_12006	Recipient id cannot be blank	400
REC_12007	Provider type cannot be blank	400
REC_12008	Invalid provider type	400
REC_12009	Invalid email	400
REC_12010	Recipient ids from request and URL do not match	400
REC_12011	Request field length exceeds max length	400
REC_12012	Account type is not from the list of allowed types	400
REC_12013	Sender account id cannot be blank	400
REC_12014	Request header is too long	400
REC_12015	Some fields in the request body are not supported for the configured provider type	400
REC_13001	This recipient already exists	400
REC_13002	This recipient nickname already exists	400
REC_14001	Recipient not added to the database successfully	500
REC_14002	Recipient not deleted successfully	500
REC_14003	Error while fetching recipients from database	500
REC_14004	Recipient not found	400
REC_14005	Error while updating recipient information	400, 401, or 500
REC_22001	Internal validation error	500
REC_99997	Client error	400
REC_99998	Server cannot handle this request	400, 404, or 405
REC_99999	Server error	500

Endpoints

Create Recipient

Creates a new recipient record and optionally validates the provided information. Use this

Delete Recipient

Removes a recipient from the user's list of saved payees. This action cannot be undone.

Get Recipient by ID

Retrieves the details of a specific recipient using their unique identifier. Use this

List Recipients

Retrieves all recipients associated with the authenticated user's account. Recipients are

Update Recipient

Updates an existing recipient's information. After updating, the recipient record may need