---
title: "Search agreements for recurring payments"
method: GET
path: "/v1/agreements"
tags: ["Agreements"]
---

# Search agreements for recurring payments

`GET /v1/agreements`

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

---

[API](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api.md) · [All operations](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/government-digital-service/gov-uk-pay-api/revisions/4dc2d80f453a/schema)