--- title: "Search agreements for recurring payments" method: GET path: "/v1/agreements" tags: ["Agreements"] --- # Search agreements for recurring payments `GET /v1/agreements` ## Request - Base URL: `https://publicapi.payments.service.gov.uk` - URL: `https://publicapi.payments.service.gov.uk/v1/agreements` - Auth: HTTP bearer You can use this endpoint to search for recurring payments agreements. The agreements are sorted by date, with the most recently-created agreements appearing first. ## Query parameters - `reference` string - `status` 'created' | 'active' | 'cancelled' | 'inactive' - `page` string - `display_size` string ## Response `200` OK - your request was successful. - AgreementSearchResults - `_links` SearchNavigationLinks: Links to navigate through pages of your search. - `first_page` Link: A link related to a payment - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`. - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`. - `last_page` Link: A link related to a payment - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`. - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`. - `next_page` Link: A link related to a payment - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`. - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`. - `prev_page` Link: A link related to a payment - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`. - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`. - `self` Link: A link related to a payment - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`. - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`. - `count` integer: Number of agreements on the current page of search results. - `page` integer: The [page of agreements you’re viewing](https://docs.payments.service.gov.uk/api_reference/#pagination). To view other pages, make this request again using the `page` parameter. - `results` Agreement[]: Contains agreements matching your search criteria. - `agreement_id` string: The unique ID GOV.UK Pay automatically associated with this agreement when you created it. - `cancelled_date` string: The date and time this agreement was cancelled. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`. - `created_date` string: The date and time you created this agreement. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`. - `description` string: The description you sent when creating this agreement. - `payment_instrument` PaymentInstrument - `CardDetails` CardDetailsFromResponse - `billing_address` Address: A structure representing the billing address of a card - `city` string: The paying user's city. - `country` string: The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code. - `line1` string: The first line of the paying user’s address. - `line2` string: The second line of the paying user’s address. - `postcode` string: The paying user's postcode. - `card_brand` string - `card_type` string - `cardholder_name` string - `expiry_date` string - `first_digits_card_number` string - `last_digits_card_number` string - `created_date` string: The date and time you created this payment instrument. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`. - `type` 'card': The type of payment instrument. - `reference` string: The reference you sent when creating this agreement. - `status` 'created' | 'active' | 'cancelled' | 'inactive': The status of this agreement. You can [read more about the meanings of each agreement status.](https://docs.payments.service.gov.uk/recurring_payments/#understanding-agreement-status) - `user_identifier` string: The identifier you sent when creating this agreement. `user_identifier` helps you identify users in your records. - `total` integer: Total number of agreements matching your search criteria. ## Other responses - `401`: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication) - `404`: Not found - `422`: Your request failed. Check the `code` and `description` in the response to find out why your request failed. - `429`: Too many requests - `500`: Downstream system error ## Changes - **2025-01-21** `fdf8c84e093b`: 1 warning, 8 info - removed the optional property `results/items/payment_instrument/CardDetails/wallet_type` from the response with the `200` status - the response optional property `results/items/payment_instrument/CardDetails/card_brand` became not read-only for the status `200` - the response optional property `results/items/payment_instrument/CardDetails/card_type` became not read-only for the status `200` - the response optional property `results/items/payment_instrument/CardDetails/expiry_date` became not read-only for the status `200` - …5 more - **2023-09-26** `c030b46b3923`: 1 info - added the optional property `results/items/payment_instrument/CardDetails/wallet_type` to the response with the `200` status - **2023-06-15** `860f9048d3f6`: 1 info - added the optional property `results/items/cancelled_date` to the response with the `200` status - **2023-05-16** `ebde96e50a9d`: 1 breaking, 2 info - removed the enum value `expired` from the `query` request parameter `status` - added the new enum value `inactive` to the `query` request parameter `status` - removed the `expired` enum value from the `results/items/status` response property for the response status `200` - **2023-05-15** `171622b498a3`: 1 warning - added the new `inactive` enum value to the `results/items/status` response property for the response status `200` [Operation history](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/changes/v1/agreements/get.md) --- [API](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api.md) - [All operations](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/revisions/6dc4b2c91eb8?raw)