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
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients/search/filters |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/storedRecipients/search/filters |
| Production – US Hub | GET 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 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.
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.
Updated 2 days ago