# Appraising a domain via the Brandpa API

> Make a GET request with your API key to receive a .com domain’s estimated list price as JSON. Learn the restrictions, the response fields, errors and caching.

## Accessing the API

Access to API is only available to selected partners on request. Learn [how to get an API key](brandpa-api.md).

## Request format

Make a HTTP GET request to: `https://brandpa.com/partners/api/appraise-domain` with the following arguments:

- `key` – your API key
- `domain` – the domain you wish to appraise

## Restrictions

- You can only appraise .com domain names at this time, as Brandpa only accepts .com domains, and valuations for other domains would be significantly different.
- We don't appraise domains for household trademarks (e.g. “Nike.com”) or highly offensive terms, e.g. swear words.
- We record all API use and reserve the right to throttle or disable access if it is excessive.

## Response format

Responses return a JSON object:

```
{
  "domain": "BrandBot.com",
  "created": 1594568546,
  "version": "1.1",
  "state": "allowed",
  "special": "",
  "estListPrice": 4995,
  "word": "BrandBot",
  "tld": "com",
  "syllables": 2,
  "markov": 100,
  "words": [
    "brand",
    "bot"
  ],
  "error": null
}
```

For successful responses:

- `domain` – the domain name requested.
- `created` – when this appraisal was completed, as a UNIX timestamp. Responses can be cached, so this might be some time in the past.
- `version` – the version of BrandBot conducting the appraisal.
- `special` – a special state, which can be `tooLow` if the domain is valued less than what Brandpa would accept, `tooHigh` if the value is too high (over $50000 USD) to be reliably appraised, or empty for all other domains.
- `estListPrice` – our estimated listed price for this domain.
- `word` – the text part before the TLD.
- `tld` – the domain's TLD (e.g. “com”).
- `syllables` – the number of syllables in the domain's `word`.
- `words` – BrandBot's best guess for the word boundaries in the domain, e.g. for “brandbot” it might see “brand” and “bot”.
- `error` – always `null` if the request was successful, otherwise an object containing `title` and `body` (see below).

## Handling failures

If a request fails, not all properties may be present. A failing response will always contain an `error` object, containing a `title` and `body` property:

```
{
  "domain": "BrandBot.co.uk",
  "created": 1594569119,
  "version": "1.1",
  "state": "rejected",
  "special": null,
  "estListPrice": null,
  "word": "BrandBot",
  "tld": "couk",
  "syllables": null,
  "markov": null,
  "words": null,
  "error": {
    "title": "We only accept .com domains",
    "body": "The vast majority of our customers are looking for .com domain names."
  }
}
```

## Caching

All requests are cached at Brandpa's discretion. We will generally purge our cache after a significant BrandBot version increase.