# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chargebackstop.com/developer/api-documentation/lookups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.