Search programmes

Search programmes by name or status to find matching programmes and their IDs. Use the ProgrammeId from the results to retrieve a programme or search its eligible accounts.

Endpoints

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

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

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

Search parameters

Use these query parameters to filter the programmes returned. You can search by name, status, or both.

ParameterTypeDescription
nameStringFilter results by programme name.
statusStringFilter results by status: Draft, Active, Inactive or Deleted.

For example, set name to UK Motor Claims and status to Active to find matching active programmes.

Send the request

This example uses the Staging environment:

curl --get \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/search' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --data-urlencode 'name=UK' \
  --data-urlencode 'status=Active'

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 Programmes array. Each result contains the programme’s ProgrammeId and Name.

{
  "Programmes": [
    {
      "ProgrammeId": "4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61",
      "Name": "UK Motor Claims"
    },
    {
      "ProgrammeId": "a12b3c45-6789-4abc-8def-0123456789ab",
      "Name": "UK Property Claims"
    }
  ]
}

Troubleshoot requests

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

Check that the status value is valid and that the name and status filters match the programmes you expect to find. If no programmes match, remove or adjust the filters.

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

Next steps

Use a returned ProgrammeId to view the programme’s configuration with Retrieve a programme. To find accounts associated with a programme, see Search programme accounts.