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

EnvironmentMethod and URL
StagingGET https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients/search
Production – UK HubGET https://api.vitesse.io/v1/payment-initiation/storedRecipients/search
Production – US HubGET 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 scopeIdentity client roleRequired for
stored-recipientsstored-recipients.viewerListing and searching stored recipients and stored recipient search filters, and retrieving their details with read-only access.
stored-recipientsstored-recipients.managerManaging 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.

ParameterTypeWhen to use it
FreeTextStringSearch for text, such as Thornton. You can combine this with Query to narrow the results.
QueryStringApply 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​.
SortQueryStringSort 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).
PageSizeIntegerSet the maximum number of results per page. The default is 10.
ContinuationTokenStringRetrieve 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.