# Lookups

List and retrieve digital receipt lookups for accessible organisations.

**Base URL:** `https://api.chargebackstop.com/v1/lookups/`

**Authentication:** Bearer token via API key.

Required abilities:

* `lookups:read` for GET endpoints

Access scope model:

* Organisation-level keys can access lookups for their own organisation only.
* Admin partner-group keys can access lookups across all organisations for their partner.
* Non-admin partner-group keys can access lookups only for organisations assigned to their group.

## GET /v1/lookups - list lookups

Returns a paginated list of lookup records accessible to the authenticated key.

**API level:** Organisation-level and partner-level\
**Authentication:** `lookups:read`

### Query parameters

| Parameter           | Type     | Description                                                                    |
| ------------------- | -------- | ------------------------------------------------------------------------------ |
| `organisation_id`   | string   | Filter by organisation ID                                                      |
| `enrollment_id`     | string   | Filter by enrollment ID                                                        |
| `type`              | string   | Filter by lookup type                                                          |
| `parent_lookup_id`  | string   | Filter by parent lookup ID                                                     |
| `lookup_status`     | string   | Filter by lookup status: `PENDING`, `SUCCEEDED`, `FAILED`, `TIMEOUT`           |
| `deflection_status` | string   | Filter by deflection status: `NOT_ATTEMPTED`, `PENDING`, `SUCCEEDED`, `FAILED` |
| `created_at_gte`    | datetime | Include lookups created at or after this timestamp (ISO 8601, inclusive)       |
| `created_at_lte`    | datetime | Include lookups created at or before this timestamp (ISO 8601, inclusive)      |
| `sort`              | string   | Sort field: `-created_at` (default) or `created_at`                            |
| `limit`             | integer  | Number of results per page                                                     |
| `offset`            | integer  | Number of results to skip                                                      |

### Important behaviour

* If both `created_at_gte` and `created_at_lte` are sent, `created_at_gte` must be less than or equal to `created_at_lte`.
* Default sort order is newest lookup first (`-created_at`).
* Responses use the same lookup object shape as lookup webhooks.

### Example request

```bash
curl -X GET "https://api.chargebackstop.com/v1/lookups/?organisation_id=org_xyz456&lookup_status=SUCCEEDED&sort=-created_at&limit=20&offset=0" \
  -H "Authorization: Bearer <api_key>"
```

### Example response

```json
{
  "items": [
    {
      "id": "lkup_abc123",
      "organisation_id": "org_xyz456",
      "enrollment_id": "enrl_def456",
      "type": "ETHOCA_CONSUMER_CLARITY",
      "parent_lookup_id": null,
      "lookup_status": "SUCCEEDED",
      "deflection_status": "NOT_ATTEMPTED",
      "transaction_card_bin": "424242",
      "transaction_card_last4": "4242",
      "transaction_arn": "74027012345678901234567",
      "transaction_auth_code": "AUTH123",
      "transaction_amount": 4999,
      "transaction_currency": "USD",
      "transaction_date": "2026-02-10T10:30:00Z",
      "transaction_statement_descriptor": "EXAMPLE STORE",
      "transaction_network_id": "network_123",
      "integration_id": "int_abc123",
      "integration_transaction_id": "txn_123",
      "created_at": "2026-02-11T10:30:00Z",
      "updated_at": "2026-02-11T10:30:00Z",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/lookups/lkup_abc123"
        }
      ]
    }
  ],
  "count": 1
}
```

***

## GET /v1/lookups/{lookup\_id} - get lookup by ID

Returns one lookup if it is visible to the authenticated key.

**API level:** Organisation-level and partner-level\
**Authentication:** `lookups:read`

### URL parameters

| Parameter   | Type   | Description |
| ----------- | ------ | ----------- |
| `lookup_id` | string | Lookup ID   |

### Important behaviour

* The same access rules as list lookups apply.
* Non-existent or inaccessible lookups return `404 Not found`.

### Example request

```bash
curl -X GET "https://api.chargebackstop.com/v1/lookups/lkup_abc123" \
  -H "Authorization: Bearer <api_key>"
```

### Example response

```json
{
  "id": "lkup_abc123",
  "organisation_id": "org_xyz456",
  "enrollment_id": "enrl_def456",
  "type": "ETHOCA_CONSUMER_CLARITY",
  "parent_lookup_id": null,
  "lookup_status": "SUCCEEDED",
  "deflection_status": "NOT_ATTEMPTED",
  "transaction_card_bin": "424242",
  "transaction_card_last4": "4242",
  "transaction_arn": "74027012345678901234567",
  "transaction_auth_code": "AUTH123",
  "transaction_amount": 4999,
  "transaction_currency": "USD",
  "transaction_date": "2026-02-10T10:30:00Z",
  "transaction_statement_descriptor": "EXAMPLE STORE",
  "transaction_network_id": "network_123",
  "integration_id": "int_abc123",
  "integration_transaction_id": "txn_123",
  "created_at": "2026-02-11T10:30:00Z",
  "updated_at": "2026-02-11T10:30:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/lookups/lkup_abc123"
    }
  ]
}
```

***

## Error examples

<details>

<summary>Example: unauthorised</summary>

```json
{
  "errors": [
    {
      "code": "UNAUTHORISED",
      "message": "Unauthorised"
    }
  ]
}
```

</details>

<details>

<summary>Example: forbidden</summary>

```json
{
  "errors": [
    {
      "code": "FORBIDDEN",
      "message": "Forbidden"
    }
  ]
}
```

</details>

<details>

<summary>Example: not found</summary>

```json
{
  "errors": [
    {
      "code": "NOT_FOUND",
      "message": "Not found"
    }
  ]
}
```

</details>

<details>

<summary>Example: invalid date range</summary>

```json
{
  "errors": [
    {
      "code": "INVALID_DATE_RANGE",
      "message": "created_at_gte cannot be greater than created_at_lte"
    }
  ]
}
```

</details>