Search stored recipients
Search stored recipients by free text, structured filters, or both. Use this endpoint to find matching recipients without retrieving every page of the full list.
Endpoints
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients/search |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/storedRecipients/search |
| Production – US Hub | GET https://api.us.vitesse.io/v1/payment-initiation/storedRecipients/search |
For help choosing an environment, see Environment.
Access requirements
Configure at least one of the following access combinations:
| OAuth scope | Identity client role | Required for |
|---|---|---|
stored-recipients | stored-recipients.viewer | Listing and searching stored recipients and stored recipient search filters, and retrieving their details with read-only access. |
stored-recipients | stored-recipients.manager | Managing stored recipients, including listing, searching, retrieving details and history, retrieving search filters, creating and updating recipients, and activating, deactivating and archiving them. |
For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.
Search parameters
Add these query parameters to the /search request to choose which recipients to return, how to sort them, and how to page through results. You can use FreeText and Query separately or together.
| Parameter | Type | When to use it |
|---|---|---|
FreeText | String | Search for text, such as Thornton. You can combine this with Query to narrow the results. |
Query | String | Apply structured filters, such as (Country: "GB") or (Address.City: "London"). You can combine this with FreeText to narrow the results.For more information, see Retrieve stored recipient search filters. |
SortQuery | String | Sort the results by field, such as Country desc, which will sort by Country in descending order. If you omit the direction, it defaults to asc (ascending). |
PageSize | Integer | Set the maximum number of results per page. The default is 10. |
ContinuationToken | String | Retrieve the next page. Use the token returned in the previous response. |
Send the request
This example uses the Staging environment. It searches for recipients matching Thornton in London, sorts by Country descending, and returns up to 10 results:
curl --get \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients/search' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--data-urlencode 'FreeText=Thornton' \
--data-urlencode 'Query=(Address.TownName: "London")' \
--data-urlencode 'SortQuery=Country desc' \
--data-urlencode 'PageSize=10'Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.
Example response
A successful request returns 200 OK with a Data array and pagination details. This example returns Emma Thornton, the matching recipient in London:
{
"Data": [
{
"StoredRecipientId": "7d978f47-1907-4d5d-8f85-8f40a96d21c8",
"Status": "Active",
"Country": "GB",
"Currency": "GBP",
"Type": "Person",
"Name": "Emma Thornton",
"Email": "[email protected]",
"PhoneNumber": "+442079460123",
"ExternalStoredRecipientId": null,
"PaymentMethod": "BankAccount",
"Address": {
"StreetName": "High Street",
"BuildingNumber": "10",
"PostCode": "SW1A 1AA",
"TownName": "London",
"CountrySubDivision": "Greater London",
"Country": "GB",
"AddressLine1": "Flat 2",
},
"BankAccountDetails": {
"AccountNumber": "88877665",
"SortCode": "112233"
},
"Person": null,
"Business": null
}Troubleshoot requests
If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.
For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.
Next steps
Use Retrieve stored recipient search filters to build structured searches. Use a returned StoredRecipientId to retrieve a specific recipient’s details.
Updated 15 days ago