> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prefetch.io/llms.txt
> Use this file to discover all available pages before exploring further.
# GET /transaction
> Turn a card transaction descriptor into the merchant behind it — name, website, logo, processor and location. Costs 3 credits, 1 for a line seen in the last week.
## Overview
Bank statement lines are written for card networks, not people: `SQ *BLUE BOTTLE COFFE OAKLAND CA`, `PAYPAL *SPOTIFYAB`, `AMZN Mktp US*2K4LX9B12`. `/transaction` reads one and tells you who was paid:
| Descriptor | Merchant | Website | Processor | Where |
| - | - | - | - | - |
| `SQ *BLUE BOTTLE COFFE OAKLAND CA` | Blue Bottle Coffee | bluebottlecoffee.com | Square | Oakland, CA |
| `PAYPAL *SPOTIFYAB` | Spotify | spotify.com | PayPal | |
| `AMZN Mktp US*2K4LX9B12` | Amazon | amazon.com | | |
| `CHECKCARD 0412 STARBUCKS STORE 12345 SEATTLE WA` | Starbucks | starbucks.com | | Seattle, WA |
| `VENMO *JOHN SMITH` | — a payment to a **person** | | Venmo | |
| `MONTHLY MAINTENANCE FEE` | — a bank **fee** | | | |
Truncated words are completed (descriptors are cut at 22 characters), processor prefixes and store numbers are dropped, and lines that are not purchases say so in `kind`: `person`, `transfer`, `fee`, `atm` or `refund`.
The merchant's name is then resolved to its website exactly as [`/resolve`](/api-reference/endpoint/resolve) does it — the name index first, then a live lookup that verifies each candidate against its own homepage, using the line's city to tell local businesses apart. `logo_url` points at the merchant's logo on the [logo CDN](/api-reference/endpoint/logo-cdn), with your publishable token, ready for an `![]()
` tag. `include_brand=true` adds the merchant's full brand (logos, colors, fonts), as [`/brand`](/api-reference/endpoint/brand) returns it.
## Example requests
```bash cURL theme={"theme":"css-variables"}
curl -G "https://api.prefetch.io/transaction" \
--data-urlencode "descriptor=SQ *BLUE BOTTLE COFFE OAKLAND CA" \
--data-urlencode "country=US" \
-H "X-API-Key: $PREFETCH_API_KEY"
```
```bash POST, with the brand theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/transaction" \
-H "X-API-Key: $PREFETCH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "descriptor": "PAYPAL *SPOTIFYAB", "mcc": "5815", "include_brand": true }'
```
```javascript Node.js — enrich a statement theme={"theme":"css-variables"}
const lines = ["SQ *BLUE BOTTLE COFFE OAKLAND CA", "NETFLIX.COM 866-579-7172 CA", "VENMO *JOHN SMITH"];
for (const descriptor of lines) {
const res = await fetch("https://api.prefetch.io/transaction", {
method: "POST",
headers: { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ descriptor, country: "US" }),
});
const { data } = await res.json();
console.log(descriptor, "→", data.kind === "merchant" ? `${data.merchant.name} (${data.merchant.domain ?? "no site"})` : data.kind);
}
```
## Example response
```json theme={"theme":"css-variables"}
{
"success": true,
"data": {
"descriptor": "SQ *BLUE BOTTLE COFFE OAKLAND CA",
"kind": "merchant",
"merchant": {
"name": "Blue Bottle Coffee",
"domain": "bluebottlecoffee.com",
"url": "https://bluebottlecoffee.com",
"confidence": 0.88,
"source": "live"
},
"candidates": [
{ "name": "Blue Bottle Coffee", "domain": "bluebottlecoffee.com", "url": "https://bluebottlecoffee.com", "confidence": 0.88, "source": "live" }
],
"payment_processor": "Square",
"location": { "city": "Oakland", "region": "CA", "country": "US" },
"category": "Coffee shop",
"logo_url": "https://logo.prefetch.io/bluebottlecoffee.com?token=pk_4f1c9e2b7a0d4c3e8b6a1f2d3c4b5a69",
"parsed_by": "model",
"warnings": []
},
"meta": { "requestId": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "durationMs": 1577 }
}
```
## Reading the response
| Field | Meaning |
| - | - |
| `kind` | `merchant`, or what else the line is. Only a `merchant` has a `merchant`. |
| `merchant.name` | The trading name, even when no website was found — many local businesses have none. |
| `merchant.domain` | The website, when one was found with confidence of at least 0.6. At 0.8 or above, treat it as the answer. Below 0.6 it is only in `candidates`. |
| `candidates` | Every domain considered, best first, including low-confidence ones. |
| `logo_url` | Null when no website was found, or for keys without a logo token (RapidAPI). |
| `parsed_by` | `rules` when the language model was unavailable and the line was read by pattern alone — a less reliable reading, flagged in `warnings`. |
`country` (where the card was used) and `mcc` (the merchant category code from your card data) are optional hints that help with ambiguous lines.
## Credits
| Outcome | Credits |
| - | - |
| A line read and resolved | 3 |
| The same line, country and MCC looked up in the last 7 days | 1 |
| `include_brand=true`, and a brand was returned | +10 |
| Failures | 0 |
Statements repeat the same merchants every month, so most of a statement's lines are served at 1 credit after the first month.
How fast unknown merchants resolve depends on the name index. Lines whose merchant the index knows answer in about a second; others run a live lookup, typically 2–5 seconds.
## Related
The `logo_url` behind every merchant. Free, with a monthly quota.
A name you already have → its domain. **1 credit.**
## OpenAPI
````yaml GET /transaction
openapi: 3.1.0
info:
title: Prefetch API
description: >-
Extract brand identity, company data, screenshots, IAB classifications, and
clean page content from any URL.
version: 1.0.0
contact:
email: support@prefetch.io
servers:
- url: https://api.prefetch.io
description: Production
security:
- apiKey: []
tags:
- name: Endpoints
description: Data extraction endpoints. All require authentication and consume credits.
- name: Health
description: Health and readiness probes. No authentication required.
paths:
/transaction:
get:
tags:
- Endpoints
summary: Identify a transaction's merchant
description: >-
Reads a card transaction descriptor — a bank statement line — and names
the merchant behind it: "SQ *BLUE BOTTLE COFFE OAKLAND CA" → Blue Bottle
Coffee, `bluebottlecoffee.com`, paid through Square, in Oakland.
Truncated words are completed, processor prefixes and store numbers
dropped, and lines that are not purchases are said to be so (`person`,
`transfer`, `fee`, `atm`, `refund`). The merchant's name is resolved to
its website the way `/resolve` does it, and `logo_url` points at its
logo on the logo CDN. `include_brand=true` adds its brand as `GET
/brand` returns it.
**Credit cost: 3 per lookup, 1 when the same line (with the same country
and MCC) was looked up in the last 7 days**, plus 10 when
`include_brand` returns a brand. Failures are never charged.
operationId: lookupTransaction
parameters:
- schema:
type: string
description: >-
The transaction line as the bank statement or card network shows
it (1–200 characters).
example: SQ *BLUE BOTTLE COFFE OAKLAND CA
required: true
description: >-
The transaction line as the bank statement or card network shows it
(1–200 characters).
name: descriptor
in: query
- schema:
type: string
description: >-
Two-letter code of the country the card was used in. Helps tell
local merchants apart.
example: US
required: false
description: >-
Two-letter code of the country the card was used in. Helps tell
local merchants apart.
name: country
in: query
- schema:
type: string
description: The four-digit merchant category code, if your card data has it.
example: '5814'
required: false
description: The four-digit merchant category code, if your card data has it.
name: mcc
in: query
- schema:
type: string
description: >-
Also return the merchant's brand — logos, colors, fonts — exactly
as GET /brand would, when its website is found. Adds the /brand
price (10 credits), charged only when a brand is returned. Can
take several seconds for a site not seen before. Pass "true".
required: false
description: >-
Also return the merchant's brand — logos, colors, fonts — exactly as
GET /brand would, when its website is found. Adds the /brand price
(10 credits), charged only when a brand is returned. Can take
several seconds for a site not seen before. Pass "true".
name: include_brand
in: query
responses:
'200':
description: The merchant, or what else the line is.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- true
data:
$ref: '#/components/schemas/TransactionData'
meta:
$ref: '#/components/schemas/Meta'
required:
- success
- data
- meta
example:
success: true
data:
descriptor: SQ *BLUE BOTTLE COFFE OAKLAND CA
kind: merchant
merchant:
name: Blue Bottle Coffee
domain: bluebottlecoffee.com
url: https://bluebottlecoffee.com
confidence: 0.88
source: live
candidates:
- name: Blue Bottle Coffee
domain: bluebottlecoffee.com
url: https://bluebottlecoffee.com
confidence: 0.88
source: live
payment_processor: Square
location:
city: Oakland
region: CA
country: US
category: Coffee shop
logo_url: >-
https://logo.prefetch.io/bluebottlecoffee.com?token=pk_4f1c9e2b7a0d4c3e8b6a1f2d3c4b5a69
parsed_by: model
warnings: []
meta:
requestId: 6f1d2c3b-4a5e-4f60-8b7a-9c0d1e2f3a4b
durationMs: 1840
'400':
description: Invalid or missing parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Revoked key, expired key, blocked URL, or credit limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate or concurrency limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service temporarily unavailable — retry shortly.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
TransactionData:
type: object
properties:
descriptor:
type: string
example: SQ *BLUE BOTTLE COFFE OAKLAND CA
kind:
type: string
enum:
- merchant
- person
- transfer
- fee
- atm
- refund
- unknown
description: >-
What the line is: a payment to a `merchant`, to a `person` (Venmo,
Zelle…), a `transfer` between accounts, a bank `fee`, an `atm`
withdrawal, a `refund`, or `unknown`.
merchant:
type: object
nullable: true
properties:
name:
type: string
nullable: true
description: >-
The merchant's trading name, with words the descriptor truncated
completed.
example: Blue Bottle Coffee
domain:
type: string
nullable: true
description: >-
Its website, when found with enough confidence; ready for every
other endpoint's `url`.
example: bluebottlecoffee.com
url:
type: string
nullable: true
confidence:
type: number
nullable: true
description: 0–1, for the domain. At 0.8 or above treat it as the answer.
example: 0.93
source:
type: string
nullable: true
enum:
- curated
- index
- live
- null
required:
- name
- domain
- url
- confidence
- source
description: Null unless `kind` is `merchant`.
candidates:
type: array
items:
$ref: '#/components/schemas/ResolveResultItem'
description: >-
Every domain considered, best first — including ones below the
confidence bar.
payment_processor:
type: string
nullable: true
description: >-
The processor or wallet that prefixed the line (Square, Toast,
PayPal…).
example: Square
location:
type: object
properties:
city:
type: string
nullable: true
region:
type: string
nullable: true
country:
type: string
nullable: true
required:
- city
- region
- country
description: Where the line says the payment was made, when it says.
example:
city: Oakland
region: CA
country: US
category:
type: string
nullable: true
example: Coffee shop
logo_url:
type: string
nullable: true
description: >-
The merchant's logo on the Prefetch logo CDN, with your publishable
token: put it straight in an ![]()
. Null when no website was found.
brand:
type: object
properties:
colors:
$ref: '#/components/schemas/ColorsBlock'
fonts:
type: object
properties:
families:
type: array
items:
type: string
required:
- families
example:
families:
- Inter
- Roboto
logos:
$ref: '#/components/schemas/LogosBlock'
images:
$ref: '#/components/schemas/ImagesBlock'
design_tokens:
$ref: '#/components/schemas/DesignTokens'
social_links:
type: object
additionalProperties:
type: string
example:
twitter: https://twitter.com/stripe
linkedin: https://linkedin.com/company/stripe
description: >-
With `include_brand=true` and a website found: the same block GET
/brand returns.
parsed_by:
type: string
enum:
- model
- rules
description: >-
`rules` when the language model was unavailable and the line was
read by pattern alone.
warnings:
type: array
items:
type: string
required:
- descriptor
- kind
- merchant
- candidates
- payment_processor
- location
- category
- logo_url
- parsed_by
- warnings
Meta:
type: object
properties:
requestId:
type: string
format: uuid
description: Unique identifier for this request.
example: a3f2c1d4-7b6e-4f2a-9c1d-8e3f2a1b4c5d
durationMs:
type: integer
nullable: true
description: Time taken to process the request in milliseconds.
example: 1842
required:
- requestId
- durationMs
ErrorResponse:
type: object
properties:
success:
type: boolean
enum:
- false
description: >-
Always false. Absent, like `meta`, on authentication and rate-limit
errors, which are answered before a request is processed.
error:
type: string
description: >-
Human-readable error message. The wording can change: branch on
`error_code`.
example: Credit limit exceeded
error_code:
type: string
enum:
- INVALID_REQUEST
- PAYLOAD_TOO_LARGE
- NOT_FOUND
- CONFLICT
- UNAUTHORIZED
- FORBIDDEN
- CREDITS_EXHAUSTED
- RATE_LIMITED
- CONCURRENCY_LIMITED
- URL_BLOCKED
- URL_NOT_PERMITTED
- DNS_RESOLUTION_FAILED
- TARGET_BLOCKED
- TARGET_CONNECTION_FAILED
- TARGET_TIMEOUT
- TARGET_SSL_ERROR
- TARGET_SERVER_ERROR
- TARGET_CLIENT_ERROR
- TARGET_NOT_A_PAGE
- TARGET_UNLOADABLE
- RESEARCH_INCONCLUSIVE
- TIMEOUT
- SERVICE_BUSY
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
description: >-
What went wrong, for machines. Stable: a code keeps its meaning once
published. See [Error handling](/concepts/errors).
example: CREDITS_EXHAUSTED
retryable:
type: boolean
description: >-
Whether the same request can succeed if sent again after a short
wait (honour `Retry-After` when present). False for problems with
the request or the target.
example: false
retryAfterSeconds:
type: integer
description: 'On `RATE_LIMITED`: seconds until a request will be accepted.'
limit:
type: integer
description: >-
On `CONCURRENCY_LIMITED`: how many requests this key may have in
flight.
meta:
$ref: '#/components/schemas/Meta'
required:
- error
- error_code
- retryable
ResolveResultItem:
type: object
properties:
name:
type: string
example: Stripe
domain:
type: string
description: Bare host, ready for the `url` parameter of every other endpoint.
example: stripe.com
url:
type: string
example: https://stripe.com
confidence:
type: number
description: >-
0–1. Only `results[0]` can reach 0.8; at or above it, that result is
the answer. Below it, a candidate to check.
example: 0.97
source:
type: string
enum:
- curated
- index
- live
description: >-
`curated`: reviewed brand data. `index`: the name index. `live`:
verified against the site during this request.
required:
- name
- domain
- url
- confidence
- source
ColorsBlock:
type: object
properties:
brand_colors:
type: array
items:
$ref: '#/components/schemas/ColorItem'
description: >-
The brand palette, built from the logo and brand assets. Always
present.
code_colors:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/CodeColorItem'
description: >-
Colors scraped from the page's code, keyed by nearest named color.
Present only when `css=true`, `html=true`, or `javascript=true`.
Sources are merged into one map, not split per source.
example:
blueviolet:
- color: '#635bff'
group: blueviolet
distance: 0
name: blueviolet-100
screenshot_colors:
type: array
items:
$ref: '#/components/schemas/ColorItem'
description: >-
Dominant colors sampled from the screenshot. Present only when
`screenshotColors=N` is passed.
required:
- brand_colors
LogosBlock:
type: object
properties:
primary:
$ref: '#/components/schemas/LogoObject'
description: Best candidate for the primary logo.
secondary:
type: array
items:
$ref: '#/components/schemas/LogoObject'
description: Other logo candidates found on the page.
favicon_url:
type: string
format: uri
nullable: true
description: URL to the site favicon.
example: https://stripe.com/favicon.ico
icon_url:
type: string
format: uri
nullable: true
description: URL to the site icon.
apple_touch_icon:
type: string
format: uri
nullable: true
description: URL to the Apple Touch Icon.
required:
- primary
- secondary
- favicon_url
- icon_url
- apple_touch_icon
ImagesBlock:
type: object
properties:
og_image:
type: string
format: uri
nullable: true
description: OpenGraph image URL.
twitter_image:
type: string
format: uri
nullable: true
description: Twitter card image URL.
assets:
type: array
items:
$ref: '#/components/schemas/BrandAssetItem'
description: Additional brand imagery found on the site and its social profiles.
screenshot_url:
type: string
format: uri
nullable: true
description: URL to the page screenshot stored in cloud storage.
required:
- og_image
- twitter_image
- screenshot_url
DesignTokens:
type: object
description: >-
The site's design system by role, read from the rendered page. Present
only when the request sets `designTokens=true`. Best effort: a field the
page gives no reliable answer for is `null`.
properties:
color_scheme:
type: string
enum:
- light
- dark
nullable: true
description: Whether the page background is light or dark.
example: light
colors:
type: object
properties:
primary:
type: string
nullable: true
description: >-
The main action color: the fill of the most prominent button, or
a colored link when no button is filled.
example: '#533AFD'
secondary:
type: string
nullable: true
description: >-
The fill of the next most prominent button, when it is a
distinct color.
background:
type: string
nullable: true
description: The page background.
example: '#FFFFFF'
text:
type: string
nullable: true
description: Body text.
example: '#50617A'
heading:
type: string
nullable: true
description: The color most headings share.
example: '#061B31'
link:
type: string
nullable: true
description: The most common color of in-content links.
example: '#533AFD'
typography:
type: object
properties:
body:
type: object
properties:
font_family:
type: string
nullable: true
description: The first family in the stack.
example: sohne-var
font_stack:
type: array
items:
type: string
description: The full `font-family` list, in order.
example:
- sohne-var
- Helvetica Neue
- Arial
- sans-serif
font_size:
type: string
nullable: true
example: 16px
font_weight:
type: number
nullable: true
example: 400
line_height:
type: string
nullable: true
description: '`null` when the site leaves it at `normal`.'
example: 24px
heading:
type: object
properties:
font_family:
type: string
nullable: true
description: The lead heading's first family.
example: sohne-var
font_stack:
type: array
items:
type: string
font_weight:
type: number
nullable: true
example: 500
sizes:
type: object
description: >-
Font size of the first visible heading at each level, and of
body text.
properties:
h1:
type: string
nullable: true
example: 48px
h2:
type: string
nullable: true
example: 32px
h3:
type: string
nullable: true
example: 26px
body:
type: string
nullable: true
example: 16px
components:
type: object
properties:
button_primary:
$ref: '#/components/schemas/ButtonTokens'
button_secondary:
$ref: '#/components/schemas/ButtonTokens'
input:
type: object
nullable: true
description: The first visible text field.
properties:
background:
type: string
nullable: true
example: '#FFFFFF'
text_color:
type: string
nullable: true
example: '#061B31'
border_color:
type: string
nullable: true
example: '#E5EDF5'
border_radius:
type: string
nullable: true
example: 4px
border_radius:
type: string
nullable: true
description: >-
The primary button's corner radius, a good proxy for the site's
rounding.
example: 4px
ColorItem:
type: object
properties:
color:
type: string
description: The color in `rgb()` form.
example: rgb(99, 91, 255)
hex:
type: string
description: The color as a hex triplet.
example: '#635BFF'
name:
type: string
description: Nearest human-readable color name.
example: Blue Violet
source:
type: string
description: >-
Where the color came from. Present on `screenshot_colors` entries
only.
example: screenshot
required:
- color
- hex
- name
CodeColorItem:
type: object
description: One color scraped from the page's CSS, HTML, or JavaScript.
properties:
color:
type: string
description: The raw value as written on the page.
example: '#635bff'
group:
type: string
description: Nearest named color, used as the group key.
example: blueviolet
distance:
type: number
description: Distance to that named color. 0 is an exact match.
example: 0
name:
type: string
description: Tint label within the group, ordered nearest-first.
example: blueviolet-100
required:
- color
- group
- distance
- name
LogoObject:
type: object
nullable: true
properties:
url:
type: string
format: uri
nullable: true
description: Public URL to the logo asset.
example: https://cdn.example.com/logo.svg
width:
type: number
nullable: true
description: Intrinsic width of the logo in pixels.
height:
type: number
nullable: true
description: Intrinsic height of the logo in pixels.
required:
- url
BrandAssetItem:
type: object
description: >-
An image harvested from the site or its social profiles, such as a
Twitter banner.
properties:
url:
type: string
format: uri
alt:
type: string
nullable: true
width:
type: number
nullable: true
height:
type: number
nullable: true
required:
- url
ButtonTokens:
type: object
nullable: true
properties:
background:
type: string
nullable: true
description: Fill color. `null` for an outlined or text-only button.
example: '#533AFD'
text_color:
type: string
nullable: true
description: Label color.
example: '#FFFFFF'
border_color:
type: string
nullable: true
description: Border color, when the button has a visible border.
border_radius:
type: string
nullable: true
description: Corner radius. `9999px` means fully rounded (a pill).
example: 4px
font_weight:
type: number
nullable: true
description: Label weight.
example: 400
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
description: Your Prefetch API key. Obtain one from the dashboard.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.