Preview access
The listing check is in preview for Scale accounts. Until it is turned on for your account, both endpoints answer 403 and nothing counts against your quota. Each listing you check counts as one monthly request, the same as a search.
1. Send a listing
Post the listing as JSON with your API key. Only title is required, but the brand field and a class make the result much more useful.
curl https://api.markbase.co/listing/check \
-H "x-api-key: $MARKBASE_API_KEY" \
-H "content-type: application/json" \
-d '{
"title": "Running Shoes for Men, Nike Style Lightweight Breathable Sneakers",
"brand": "Quillstride",
"classes": ["25"],
"limit": 3
}'| Field | What it does |
|---|---|
| title | Required. The title as it will appear on the marketplace, up to 500 characters. |
| brand | The brand you will enter in the marketplace's brand field. Generic and Unbranded are ignored. |
| keywords | Backend search terms or tags, up to 20. |
| description | Bullet points or description, up to 2,000 characters. Only brand-like words in it are searched. |
| classes | Up to five Nice classes, such as ["25"] for apparel. Only marks in these classes are reported. |
| status | live, the default, reports pending and registered marks. all adds dead, canceled, and expired marks at low risk. |
| phonetic | true also reports marks that sound like a brand-like word in the listing. |
| limit | Marks returned per listing, 1–50. Defaults to 20. |
2. Read the result
This is the response from the live index, trimmed to its first match. The title names Nike, so live NIKE registrations in class 25 match. The brand field found nothing.
{
"title": "Running Shoes for Men, Nike Style Lightweight Breathable Sneakers",
"classes": ["025"],
"status": "live",
"risk": "high",
"matched_words": [
{ "words": "Nike", "field": "title", "risk": "high", "marks": 8 }
],
"phrases": [
{
"text": "Quillstride",
"field": "brand",
"reasons": ["brand_field"],
"searched": true
},
{
"text": "Nike",
"field": "title",
"reasons": ["before_cue", "leading"],
"searched": true
}
],
"matches": [
{
"serial_number": "72414176",
"word_mark": "NIKE",
"owner_name": "NIKE, INC.",
"status_code": "800",
"status": "registered",
"live": true,
"international_codes": ["025"],
"match": "in_listing",
"listing_words": "Nike",
"field": "title",
"reasons": ["before_cue", "leading"],
"similarity": 1,
"risk": "high"
}
],
"matching": {
"mode": "spelling",
"phrases_searched": 2,
"phrases_skipped": 0,
"truncated": false
}
}Start with risk and matched_words. They cover every matched mark, even the ones past your limit, so a tool can highlight the words to change. Each entry in matches is one filing, with its owner, so you can tell your own registration from someone else's.
| match | Meaning |
|---|---|
| in_listing | The mark's words appear in the listing, ignoring case, spaces, and punctuation. HYDRO FLASK matches "Hydro Flask" and "HydroFlask". |
| similar_spelling | A brand-like word is one letter away from a mark of five to seven letters, or two letters from a longer one, and starts with the same letter. |
| sounds_like | With phonetic, a brand-like word shares a Double Metaphone encoding with the mark. |
A live mark is high risk when it spans more than one word of the listing, or when the word looked like a brand: the brand field, the opening words of a title segment, a word after "for" or "compatible with" or before "style", mixed case such as iPhone, all caps, or a ™ or ® symbol. An ordinary title word, a near spelling, or a sound-alike is medium. Dead marks are always low.
3. How phrases are chosen
Product words such as colors, sizes, materials, and "shirt" or "bottle" are never searched on their own, and a mark made only of them is never reported. Everything else is searched in this order, up to ten phrases per listing:
- The brand field.
- Brand-like words in the title, and the words around cues like "for", "works with", and "style".
- The first words of each part of the title, split at commas, dashes, and bars.
- Your keywords.
- Every other title word.
- Brand-like words in the description.
phrases lists each one with its reasons and whether it was searched. When a listing has more than ten, phrases_skipped counts the rest and truncated is true.
4. Check a catalog
POST /listing/check/batch takes 1–25 listings, each with its own classes, and returns results in the same order. Each listing counts as one request. A batch that would go past your monthly quota is rejected whole with 429. Once a batch is admitted it counts in full, even if a search fails, so don't retry it automatically.
const response = await fetch("https://api.markbase.co/listing/check/batch", {
method: "POST",
headers: {
"x-api-key": process.env.MARKBASE_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
listings: [
{ title: "Protective Case for Apple iPhone 15 Pro Max", classes: ["9"] },
{ title: "Stainless Steel Water Bottle - Hydro Flask Style Tumbler", classes: ["21"] },
],
limit: 5,
}),
});
const { results, usage } = await response.json();
for (const result of results) {
console.log(result.risk, result.matched_words.map((w) => w.words));
}
console.log("Requests used:", usage.listings);5. Know what it doesn't cover
The check covers US records only. It searches each phrase for at most 30 candidate marks, so a clean result means nothing close turned up in that search, not that the listing is clear. Logos, design marks, and trade dress aren't checked, and a class filter narrows the search without settling which goods are related.
The listing itself isn't stored. Like the rest of Markbase, this is a first-pass signal, not legal advice. Talk to a trademark attorney before you rely on a result. For a single proposed name, use name screening instead.