Enrich transaction descriptors

Transaction enrichment uses the same Brand endpoint as domain and email lookups. Send one raw descriptor and, when available, include merchant category and location hints.

The response does not include a public confidence score. Use high_confidence_only when a wrong match is more costly than an unresolved transaction, and keep an explicit unresolved state in your product.

Identify a merchant

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

curl https://api.context.dev/v1/brand/retrieve \
  --request POST \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "by_transaction",
    "transaction_info": "SQ *CORNER CAFE LONDON GB",
    "mcc": "5812",
    "country_gl": "gb",
    "city": "London",
    "high_confidence_only": true
  }'

import ContextDev from "context.dev";

const client = new ContextDev({
  apiKey: process.env.CONTEXT_DEV_API_KEY,
});

const response = await client.brand.retrieve({
  type: "by_transaction",
  transaction_info: "SQ *CORNER CAFE LONDON GB",
  mcc: "5812",
  country_gl: "gb",
  city: "London",
  high_confidence_only: true,
});

if (response.brand) {
  console.log(response.brand.title, response.brand.domain);
}

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve(
    type="by_transaction",
    transaction_info="SQ *CORNER CAFE LONDON GB",
    mcc="5812",
    country_gl="gb",
    city="London",
    high_confidence_only=True,
)

if response.brand:
    print(response.brand.title, response.brand.domain)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(
  api_key: ENV.fetch("CONTEXT_DEV_API_KEY")
)

response = client.brand.retrieve(
  body: {
    type: :by_transaction,
    transaction_info: "SQ *CORNER CAFE LONDON GB",
    mcc: "5812",
    country_gl: "gb",
    city: "London",
    high_confidence_only: true,
  }
)

puts response.brand&.title

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.Get(
        context.Background(),
        contextdev.BrandGetParams{
            OfByTransaction: &contextdev.BrandGetParamsBodyByTransaction{
                TransactionInfo: "SQ *CORNER CAFE LONDON GB",
                Mcc: contextdev.BrandGetParamsBodyByTransactionMccUnion{
                    OfString: contextdev.String("5812"),
                },
                CountryGl: contextdev.String("gb"),
                City: contextdev.String("London"),
                HighConfidenceOnly: contextdev.Bool(true),
            },
        },
    )
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Brand.Title)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

// Use the SDK's low-level request method until the Brand helper is fixed.
$raw = $client->request(
    method: 'post',
    path: 'brand/retrieve',
    body: [
        'type' => 'by_transaction',
        'transaction_info' => 'SQ *CORNER CAFE LONDON GB',
        'mcc' => '5812',
        'country_gl' => 'gb',
        'city' => 'London',
        'high_confidence_only' => true,
    ],
);

$response = json_decode((string) $raw->getBody(), true, flags: JSON_THROW_ON_ERROR);
echo $response['brand']['title'] ?? 'No brand found', PHP_EOL;

The PHP tab uses the SDK’s low-level request method because the 2.14.0 Brand helper requires conflicting lookup fields. See the PHP guide for details.

The endpoint costs 10 credits. It returns the shared Brand response, whose nested fields are independently optional.

Add matching hints

Field	When to send it
`transaction_info`	Always. Send the descriptor as received; it must contain 3 to 500 characters.
`mcc`	When the processor supplies a Merchant Category Code. String and numeric values are accepted.
`country_gl`	When you know the transaction country. Send the country-code hint provided by your source system.
`city`	When city-level context can separate local businesses with similar names.
`phone`	When a phone number appears in the transaction data and can help verify the merchant.
`high_confidence_only`	When abstaining is safer than returning a less certain match.
`maxSpeed`	When latency matters more than a comprehensive Brand profile.
`timeoutOpts`	When the lookup must fit within a bounded request budget.

Do not invent missing MCC, geography, or phone values. Incorrect hints can be worse than omitted hints.

Model unresolved transactions

Merchant descriptors are noisy and some cannot be mapped reliably. Treat that as a normal product state:

type EnrichedTransaction =
  | { status: "matched"; brandDomain: string; brandTitle: string }
  | { status: "unresolved"; displayDescriptor: string }
  | { status: "retryable_error"; displayDescriptor: string };

Keep the original descriptor for auditability.
Distinguish an unresolved merchant from a timeout or service error.
Provide a neutral category fallback instead of assigning an unverified logo.
Do not display high_confidence_only as a numeric score. It is a request mode, not a score returned by the API.

Cache matches

Cache successful matches in your application when repeated descriptors are common. Include any matching context that can change the result:

sha256(JSON.stringify([normalized_descriptor, mcc, country, city, phone, high_confidence_only]))

Normalize casing and whitespace for the cache key, but send the original descriptor to Context.dev. Use a shorter negative-cache window than your successful-match window so previously unresolved merchants can be retried.

Review uncertain matches

For expense, compliance, or financial-reporting workflows, semantic validation belongs in your application:

Compare the returned domain and title with the raw descriptor and transaction context.
Keep human review for consequential or ambiguous matches.
Store the input, result, and lookup time needed for your audit trail.
Never infer that a returned address is a legal entity or headquarters address unless you verify it separately.

Next steps

Merchant transaction feeds

Add readable merchant rows, unresolved states, and saved corrections.

Retrieve brand data

Understand the shared brand response model.

Troubleshooting

Handle lookup failures and decide when to retry.

Brand API reference

Review the complete transaction lookup contract.

Use timeouts and partial results to choose the deadline behavior. Partial Brand profiles omit fields that have not completed; retain partial: true instead of treating an incomplete profile as a complete cached record.

Get started

Web data

Brand data

Automation

Account and billing

Production

Enrich transaction descriptors

Identify a merchant

Add matching hints

Model unresolved transactions

Cache matches

Review uncertain matches

Next steps

Merchant transaction feeds

Retrieve brand data

Troubleshooting

Brand API reference

​Identify a merchant

​Add matching hints

​Model unresolved transactions

​Cache matches

​Review uncertain matches

​Next steps

Merchant transaction feeds

Retrieve brand data

Troubleshooting

Brand API reference

Identify a merchant

Add matching hints

Model unresolved transactions

Cache matches

Review uncertain matches

Next steps