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

List Recipients

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

Get Recipient by ID

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

Create Recipient

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

Update Recipient

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

Delete Recipient

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