Batch lookups

Request#

POSThttps://brandidentityapi.com/v1/brands/batch

Needs a secret key. Send a JSON body with an identifiers array. Each identifier can be a domain, a URL or an email address, as for the Brand API.

curl https://brandidentityapi.com/v1/brands/batch \
  -H "Authorization: Bearer $BRAND_IDENTITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifiers":["stripe.com","https://www.linear.app/pricing","jane@notion.so","not a domain"]}'

{
  "identifiers": [
    "stripe.com",
    "https://www.linear.app/pricing",
    "jane@notion.so",
    "not a domain"
  ]
}

Batch size#

How many identifiers one request may hold depends on your plan, up to 100. A larger batch is refused with invalid_request; split it.

Response#

The request answers 200 whenever the batch itself was valid. Each identifier gets one result, in the order you sent them, with the status it would have had as a single lookup and either a brand or an error.

{
  "results": [
    {
      "identifier": "stripe.com",
      "domain": "stripe.com",
      "status": 200,
      "brand": {
        "id": "0b7e9a52-3c1d-4f6e-8a2b-5d9c1e7f4a30",
        "name": "Stripe",
        "domain": "stripe.com",
        "...": "the full record"
      }
    },
    {
      "identifier": "https://www.linear.app/pricing",
      "domain": "linear.app",
      "status": 200,
      "brand": {
        "name": "Linear",
        "domain": "linear.app",
        "...": "the full record"
      }
    },
    {
      "identifier": "jane@notion.so",
      "domain": "notion.so",
      "status": 200,
      "brand": {
        "name": "Notion",
        "domain": "notion.so",
        "...": "the full record"
      }
    },
    {
      "identifier": "not a domain",
      "domain": null,
      "status": 400,
      "error": {
        "code": "invalid_domain",
        "message": "Not a domain, URL or email address with a public domain."
      }
    }
  ]
}

What counts#

• Each brand found counts one lookup. Errors cost nothing.
• Identifiers that name the same domain (stripe.com and https://stripe.com/about) share one lookup and count once.
• When your credits cover fewer domains than you sent, the ones that fit are looked up and the rest come back as insufficient_credits, uncharged.

Timing#

Domains are looked up five at a time. Indexed brands come back at once; unknown ones are crawled live. A batch has a time budget of under a minute in total, so a large batch of unknown domains may answer some of them from the index only. Those come back with an error and are not counted: retry them on their own, or in a later batch.

Errors#

The whole batch is refused, and nothing counted, when: