---
title: "Find agreement by ID"
method: GET
path: "/v1/agreement/{agreementExternalId}"
tags: ["Agreements"]
---

# Find agreement by ID

`GET /v1/agreement/{agreementExternalId}`

## Request

- Base URL: `http://ledger_url`
- URL: `http://ledger_url/v1/agreement/{agreementExternalId}`
- Auth: none declared

## Path parameters

- `agreementExternalId` string, required

## Query parameters

- `account_id` string
- `service_id` string
- `override_account_or_service_id_restriction` boolean

## Headers

- `X-Consistent` boolean

## Response `200`

OK

- Agreement
  - `cancelled_by_user_email` string
  - `cancelled_date` string, date-time
  - `created_date` string, date-time
  - `description` string
  - `external_id` string
  - `live` boolean
  - `payment_instrument` PaymentInstrument
    - `agreement_external_id` string
    - `card_details` CardDetails
      - `billing_address` Address
        - `city` string
        - `country` string
        - `county` string
        - `line1` string
        - `line2` string
        - `postcode` string
      - `card_brand` string
      - `card_type` 'CREDIT' | 'DEBIT'
      - `cardholder_name` string
      - `expiry_date` string
      - `first_digits_card_number` string
      - `last_digits_card_number` string
    - `created_date` string, date-time
    - `external_id` string
    - `type` 'CARD'
  - `reference` string
  - `service_id` string
  - `status` 'CREATED' | 'ACTIVE' | 'INACTIVE' | 'CANCELLED'
  - `user_identifier` string

## Other responses

- `404`: Not found
- `422`: Invalid parameters. One of service_id or account_id fields is required unless override_account_or_service_id_restriction=true

## Changes

- **2023-06-14** `6db167531dc6`: 2 info
  - added the optional property `cancelled_by_user_email` to the response with the `200` status
  - added the optional property `cancelled_date` to the response with the `200` status
- **2023-05-16** `778012a6f93d`: 1 info
  - removed the `EXPIRED` enum value from the `status` response property for the response status `200`
- **2023-05-10** `de3413436a22`: 1 warning
  - added the new `INACTIVE` enum value to the `status` response property for the response status `200`
- **2023-01-25** `c30436fa346d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/government-digital-service/apis/ledger-api/changes/v1/agreement/:agreementExternalId/get.md)

---

[API](https://skmtc.dev/government-digital-service/apis/ledger-api.md) - [All operations](https://skmtc.dev/government-digital-service/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/government-digital-service/apis/ledger-api/revisions/450e568b5b08?raw)