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

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

{
  "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

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

Example response

{
  "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

Example: unauthorised

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

Example: forbidden

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

Example: not found

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

Example: invalid date range

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