Search programme accounts

Search for accounts associated with an active programme. Filter the results by account properties to find an eligible account for a payment request.

Endpoints

EnvironmentMethod and URL
StagingGET https://api.staging.vitesse.io/v1/payment-initiation/programmes/{id}/accounts/search
Production – UK HubGET https://api.vitesse.io/v1/payment-initiation/programmes/{id}/accounts/search
Production – US HubGET https://api.us.vitesse.io/v1/payment-initiation/programmes/{id}/accounts/search

Replace {id} with the programme’s ProgrammeId.

For help choosing an environment, see Environment.

Access requirements

Configure at least one of the following access combinations:

OAuth scopeIdentity client role
programmesprogrammes.viewer
programmesprogrammes.manager
payment-requestspayment-requests.manager

For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.

Search parameters

Use these parameters to page through accounts associated with a programme and optionally filter or sort them.

ParameterTypeDescription
idStringThe programme’s ProgrammeId.
limitIntegerMaximum number of accounts to return. Defaults to 10; must be between 1 and 100.

offset
IntegerNumber of matching accounts to skip. Defaults to 0; must be 0 or greater.
queryStringFilter accounts using AccountId, MerchantCode, Name, Code, Alias, Currency, UpperPaymentLimit, SubAccountType, UpdatedAt or AccountBalance. For example, (Currency: "GBP") finds GBP accounts.
Combine conditions to narrow results. For example Currency: "GBP" AND AccountBalance > 500 returns GBP accounts with a balance above 500. URL-encode the expression when sending the request.
sortQueryStringSort results by a supported account field, such as Name asc.

For example, use (Currency: "GBP") to find GBP accounts and Name desc to sort the results by name in descending order.

Before you begin

Get the programme’s ProgrammeId using Search programmes or List programmes. You can only search for accounts that are associated with an active programme.

Send the request

This example uses the Staging environment. It searches the specified programme’s eligible accounts for GBP accounts and sorts them by name:

curl --get \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/accounts/search' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --data-urlencode 'query=(Currency: "GBP")' \
  --data-urlencode 'sortQuery=Name asc' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'offset=0'

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 of matching accounts and pagination details.

{
  "Data": [
    {
      "AccountId": 3761,
      "MerchantCode": "northstar",
      "Name": "UK Motor Claims",
      "Code": "UK-MOTOR-GBP",
      "Alias": "UK motor",
      "Currency": "GBP",
      "AccountBalance": 125000.00,
      "UpperPaymentLimit": 50000.00,
      "UpperPaymentLimitCurrency": "GBP",
      "SubAccountType": "Standard",
      "FcpEnabled": false
    }
  ],
  "TotalCount": 1,
  "Limit": 10,
  "Offset": 0
}

Troubleshoot requests

If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.

Check that {id} is a valid ProgrammeId, that the programme is active, and that it has eligible accounts. Check that limit is between 1 and 100, offset is not negative, and the query and sortQuery use supported account fields. An empty Data array can mean the programme is inactive, has no eligible accounts, or none match the filters.

For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.

Next steps

Use an AccountId from the results as the SendAccountId when creating a payment request that uses the programme. For instructions on how to create the payment request, see Make a payment using Payee Choice.