curl --request POST \
--url https://www.logo.dev/api/transaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"transaction": "Starbucks",
"country_code": "US"
}
'{
"domain": "starbucks.com",
"name": "Starbucks",
"entity_id": "2f0a6d2e-4c19-4a7b-9f31-8c6e0b4d7a52",
"logo_url": "https://img.logo.dev/starbucks.com",
"parent": null,
"intermediary": null,
"status": "matched",
"match_type": "resolved_entity",
"confidence": 0.8
}Identify a merchant
Identify a merchant domain and brand record. Private beta with 1,000 requests per day.
curl --request POST \
--url https://www.logo.dev/api/transaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"transaction": "Starbucks",
"country_code": "US"
}
'{
"domain": "starbucks.com",
"name": "Starbucks",
"entity_id": "2f0a6d2e-4c19-4a7b-9f31-8c6e0b4d7a52",
"logo_url": "https://img.logo.dev/starbucks.com",
"parent": null,
"intermediary": null,
"status": "matched",
"match_type": "resolved_entity",
"confidence": 0.8
}Authorizations
Transaction-only beta key, issued with your beta access and always visible in the Transaction Playground. Existing Logo.dev secret keys do not authenticate this beta.
Body
Merchant name or card descriptor. Leading and trailing whitespace is removed.
1 - 1024"Starbucks"
Optional ISO 3166-1 alpha-2 country hint, case-insensitive. Omit for no country preference. AQ, AX, TF, and VA are unsupported when transaction_context is supplied.
2"US"
Optional as a group. All four transaction fields are required when supplied. Use actual values; no defaults are inferred.
Show child attributes
Show child attributes
Response
A matched merchant or a cleaned descriptor. Every non-empty transaction returns a row. Illustrative response examples; fields vary by lookup.
Identified merchant domain, or null on a cleaned row.
Display name for the row, populated for every non-empty transaction. The Brand API's name where it resolves a brand for the domain, the name the transaction lookup returned for the long tail, and the descriptor tidied into a display name where nothing was identified.
"Starbucks"
The merchant's Logo.dev brand id, the same id the Brand API uses for that brand, or null when the Brand API resolves no brand for the domain and null on a cleaned row. It holds still when a company changes its domain: key your own records off it rather than off domain, and a rebrand leaves one merchant rather than two. It is also the corroboration test, since a row carrying an id is one two sources agree on: a stage of the pipeline identified the merchant, and the Brand API resolves a brand for the same domain. Branch on it rather than on the score.
"2f0a6d2e-4c19-4a7b-9f31-8c6e0b4d7a52"
img.logo.dev URL for the merchant's logo, or null on a cleaned row. It carries no token: append your own publishable key before rendering it, as https://img.logo.dev/starbucks.com?token=LOGO_DEV_PUBLISHABLE_KEY.
"https://img.logo.dev/starbucks.com"
The company that owns the merchant, returned beside the merchant rather than instead of it: a lookup for facebook.com comes back as Facebook with Meta here. It is never the merchant, and never replaces it in domain. Use it as a grouping key: totalling spend on parent.entity_id adds a company's brands up to one line, and that id is the company's own entity_id when it turns up as a merchant itself. It names the nearest owner Logo.dev records rather than the top of the chain, so jaguar.com returns JLR and a lookup for JLR returns Tata Motors. Coverage is thin: Logo.dev records 194 hand-verified ownership pairs across 108 companies, against the more than 50 million companies the Brand API covers, so most rows return null. Null means Logo.dev records no owner for this merchant. It does not mean the merchant is independent. Null also when the Brand API resolves no brand for the owner's domain, since no owner is published that cannot be named, and null on a cleaned row. One case it does not cover: a company that rebrands onto a new domain can come back as a new identity, and this joins it to the old one only when both domains are in the ownership list. The fields are the same four as intermediary, so one shape covers both.
Show child attributes
Show child attributes
The platform the purchase ran through, returned beside the merchant rather than instead of it. It is never the merchant: the merchant is domain. Null when nothing stood between the account holder and the merchant, and null when the platform sold the thing itself: a DashPass subscription names DoorDash in domain and leaves this null. A descriptor that starts with a platform prefix fills it without context: the text after the prefix is resolved as its own lookup, so the seller is the merchant and the platform stands beside it. A cleaned row can still carry one: a purchase that ran through a platform whose merchant could not be identified. The platform gets the same identity treatment as the merchant, from the same lookup, keyed by its own domain: its name, its Logo.dev brand id, and a tokenless logo URL. It carries no role; the lookup states none.
Show child attributes
Show child attributes
matched when a merchant domain was identified. cleaned when the descriptor was tidied into a display name and no merchant was identified. A non-empty transaction returns one of the two. There is no not-found result.
matched, cleaned Which stage of the Logo.dev pipeline produced the row, strongest first. enriched_context: identified from the full transaction, where entry type and account holder are available. descriptor_domain: the descriptor printed the merchant's own domain, resolved like any other merchant domain. resolved_entity: identified from the descriptor alone, with no transaction context. searched_name: the Logo.dev brand corpus of more than 50 million companies recognized the cleaned name. cleaned_descriptor: nothing was identified, and name carries the descriptor, tidied. descriptor_domain and searched_name are new values on rows that returned cleaned_descriptor before; nothing was removed.
enriched_context, descriptor_domain, resolved_entity, searched_name, cleaned_descriptor How sure Logo.dev is about this row, from 0 to 1. Two inputs move it: which stage of the pipeline produced the row, and whether the Brand API resolves a brand for the same domain. Corroboration is the input that does not come from the transaction lookup itself, so the score is not a restatement of match_type. A quality rule firing sends the row to the floor. The same input scores the same number every time. Logo.dev publishes no cut-off: rank and triage on this number, and branch on entity_id. The corroboration input outlived the verified flag that was removed from this response: that flag restated entity_id !== null, while the score combines corroboration with the match path.
0 <= x <= 1Returned only when transaction_context is supplied. The enrichment provider's classification of the party it identified, or null when the provider classified nobody. A null value is not proof that no merchant was found: a later step can identify one, so a matched row with a domain may still carry null here. A person never returns a merchant domain; the row comes back cleaned. Unrelated to intermediary, which describes the platform a purchase ran through.
person, organization, null Was this page helpful?