---
title: "Start a claim"
method: POST
path: "/api/entity/{vhid}/claims"
tags: ["Claiming an entry"]
---

# Start a claim

`POST /api/entity/{vhid}/claims`

## Request

- Base URL: `https://verifiedhandles.org`
- URL: `https://verifiedhandles.org/api/entity/{vhid}/claims`
- Auth: HTTP bearer

Starts proving that you run the person or organisation an entry is about. It answers a token: publish it on a page the entry lists (`url`), in a DNS TXT record of its website’s domain (`dns`); or, for `email`, no token is needed: your account’s verified email must be an address the entry lists, or admin@, administrator@, webmaster@, hostmaster@ or postmaster@ at a domain it lists. The site then checks it for itself. An entry closed to claims is refused. An entry someone else holds can be claimed too: its proof asks an administrator for a transfer.

## Path parameters

- `vhid` string, required

## Request body

- object
  - `method` 'url' | 'dns' | 'email', required
  - `target` string: For `url`, the page; for `dns`, the domain. Not used for `email`.

## Response `200`

The claim, with its token.

- ClaimStarted: A claim waiting for its proof. Asking again while it waits answers the same claim and token.
  - `ok` true, required
  - `claimId` string, required: The claim’s id, to check it with.
  - `token` string, required: The token to publish where the method says.
  - `expires_at` string, date-time, required: When the token stops working: a week from now.
  - `method` 'url' | 'dns' | 'email', required
  - `instructions` string, required: Where to put the token, in words.

## Other responses

- `400`: The body is not JSON, the method is not one of the three, or `url`/`dns` came without a target. Or the request sent a key and a session cookie together (`bearer_with_cookie`): send one.
- `401`: No key was sent (`auth_required`), or the key was refused: unknown, revoked or expired, its holder may no longer use keys, or this instance takes none. Carries `WWW-Authenticate: Bearer`. After 60 refused keys from one IP address in a minute, every key from there is answered `429` (text, with `Retry-After`) until the minute is up.
- `403`: The entry takes no claims (`closed`). A read-only key tried to change something (`read_only_key`), or the account is blocked (`forbidden`).
- `404`: No public entry has that VHID.
- `413`: The body is over 16 KiB.
- `429`: Too many changes in the last minute: counted per IP address, per account and per key (an admin key’s per key alone, at the limit set on Console → Rate limits). Wait the number of seconds `Retry-After` gives.
- `503`: The site is down for maintenance. The body is the maintenance page, as HTML. Try again later: `Retry-After` gives the seconds.

---

[API](https://skmtc.dev/verifiedhandles/apis/verified-handles-api.md) · [All operations](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/llms.txt) · [OpenAPI document](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/revisions/40720de2e0ec?raw)