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"
    }
  ],
  "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"
}

---

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"
    }
  ]
}