Identify a merchant

The merchant name or card descriptor. The API trims surrounding whitespace, then the value must be 1 to 1,024 characters.

ISO 3166-1 alpha-2 country code, such as US or GB. Lowercase is accepted. The code is a hint for ambiguous names. It does not restrict results to that country. An unknown code returns 400. With transaction_context, the codes AQ, AX, TF, and VA return 400.

The merchant's domain. null on a cleaned row.

The display name. Present for every non-empty transaction.

• When Brand resolves a brand for the domain, its name wins.
• Otherwise it is the name the transaction lookup returned.
• On a cleaned row it is the descriptor, tidied into a display name.

Descriptors arrive in one case, so a tidied name reads Fedex, not FedEx. When the Logo.dev brand corpus holds the same name, a cleaned row takes the company's own spelling. Only the name changes. The row stays cleaned at the same confidence.

Present only when the request includes transaction_context. person or organization, as the enrichment provider classified the other party, or null when it classified nobody.

A null does not mean the API found no merchant. A later stage can identify one, so a matched row can carry null here. A person always comes back as a cleaned row.

Without context, the API does not detect people. It treats a personal name as a merchant name, so Jane Doe can match an organization with a similar name.

The merchant's Logo.dev brand id, the same id Brand uses. A brand keeps its id when its domain changes, so key your records on entity_id, not domain.

A row with an id has two sources that agree: the pipeline identified the merchant, and Brand resolves a brand for the same domain. Branch on entity_id, not on confidence.

null on a cleaned row, and on a matched row when Brand resolves no brand for the domain. A domain that Logo.dev has not indexed yet also returns null. A later lookup can return an id after the first crawl finishes.

The Logo.dev CDN URL for the merchant's logo. null on a cleaned row. The URL has no token. Add your publishable key before you show it: https://img.logo.dev/starbucks.com?token=LOGO_DEV_PUBLISHABLE_KEY. The same applies to logo_url in parent and intermediary.

matched when the API identified a merchant domain. cleaned when it did not. There is no not-found result: a cleaned row is an answer, with a tidied display name and null in domain, entity_id, logo_url, and parent.

A row is cleaned for one of two reasons:

• Nothing identified the descriptor.
• A candidate domain failed a merchant check. The checks catch repeated hostnames, directory and profile hosts, a known platform in the merchant's place, and known descriptor conflicts. They run on saved results and on new lookups.

A failed check drops the domain and uses the tidied descriptor as the name. A platform that a check removes from the merchant's place still comes back in intermediary. An organization with no usable website also comes back cleaned. The API never puts a payment processor's or parent company's domain in place of the merchant's.

The pipeline stage that produced the row, strongest first. The set is closed.

• enriched_context: identified from the full transaction, with entry type and account holder.
• descriptor_domain: the descriptor printed the merchant's own domain.
• resolved_entity: identified from the descriptor alone, with no transaction context.
• searched_name: the Logo.dev brand corpus recognized the cleaned name.
• cleaned_descriptor: nothing identified the merchant. name holds the tidied descriptor.

descriptor_domain and searched_name are fallbacks. They run only when the enrichment provider identifies nobody. A descriptor that the provider recognizes never reaches them: CHEWY.COM XXX-XXX-7111 FL prints a domain and still returns resolved_entity. Both fallbacks face the same merchant checks, so a row that fails them comes back cleaned.

Read match_type from the row. Do not predict it from the descriptor, because the same string can take a different path as the provider's coverage changes.

A score from 0 to 1. Two inputs set it: the match_type that produced the row, and whether Brand resolves a brand for the same domain. A printed domain scores above a name resolved from the descriptor, and a corpus search scores below it. A failed merchant check sends the row to the floor. A matched row with no brand has a lower score and a null entity_id.

The same input always gets the same score, so two runs of a batch compare cleanly.

Logo.dev publishes no cut-off, because the right line depends on what the row feeds. Use the score to rank and triage, for example to sort a review queue. To branch, read entity_id. Logo.dev can recalibrate the score without changing which rows have an id. A high score does not guarantee accuracy.