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
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/programmes/search |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/programmes/search |
| Production – US Hub | GET 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 scope | Identity client role |
|---|---|
programmes | programmes.viewer |
programmes | programmes.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.
| Parameter | Type | Description |
|---|---|---|
name | String | Filter results by programme name. |
status | String | Filter 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.
Updated 17 days ago