List stored recipient search filters

List all the filters available for stored recipient searches, including each filter’s identifier, data type and, where applicable, allowed values. Use a filter’s Id when adding structured criteria to the Query parameter in Search stored recipients.

Endpoints

EnvironmentMethod and URL
StagingGET https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients/search/filters
Production – UK HubGET https://api.vitesse.io/v1/payment-initiation/storedRecipients/search/filters
Production – US HubGET https://api.us.vitesse.io/v1/payment-initiation/storedRecipients/search/filters

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.

Send the request

This example uses the Staging environment:

curl --request GET \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients/search/filters' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json'

Replace <access-token> with an access token that contains the required scope.

Example response

A successful request returns 200 OK with a SearchFilters array. Each entry includes an Id, Name and Type. AllowedValues is included when the filter has a set of allowed values. The example shows common filters. Depending on your integration, the endpoint can return additional entries.

{
  "SearchFilters": [
    {
      "Id": "Country",
      "Name": "Country",
      "Type": "string",
      "AllowedValues": [
        "GB",
        "US"
      ]
    },
    {
      "Id": "Name",
      "Name": "Name",
      "Type": "string"
    },
    {
      "Id": "Type",
      "Name": "Type",
      "Type": "enum",
      "AllowedValues": [
        "Person",
        "Business"
      ]
    },
    {
      "Id": "Status",
      "Name": "Status",
      "Type": "enum",
      "AllowedValues": [
        "Active",
        "Inactive",
        "Archived"
      ]
    }
  ]
}

Country values depend on the stored recipients available to the merchant. Use the returned Id and, where provided, AllowedValues when building a structured Query. For nested fields, use the complete property path returned in Id, such as Address.TownName.

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 the returned filter IDs and values in the Query parameter when you Search stored recipients.