Skip to main content
This guide walks you from an API key to your first successful response.
1

Get an API key

API keys are issued by Hamlet. Reach out to your account contact to obtain a key for your organization. Keys are prefixed with hmlt_ and grant access to a specific set of locations (your entitlements).
Treat your API key like a password. Send it only over HTTPS, never embed it in client-side code, and store it in a secret manager rather than source control.
2

Make your first request

Every /v1 endpoint requires an Authorization: Bearer <key> header. List the locations your key is entitled to:
curl https://api.myhamlet.com/v1/locations \
  -H "Authorization: Bearer hmlt_your_api_key"
3

Read the response

List endpoints return a cursor-paginated envelope — a data array plus a next_cursor:
{
  "data": [
    {
      "uuid": "5f2b0c3a-1d4e-4a8b-9f6d-2a1c3e4b5d6f",
      "type": "CITY",
      "name": "Palo Alto",
      "state_name": "California",
      "state_abbreviation": "CA",
      "county_names": ["Santa Clara"],
      "created_at": "2025-01-10T00:00:00.000Z",
      "updated_at": "2026-05-01T18:22:10.000Z"
    }
  ],
  "next_cursor": "eyJ1IjoiMjAyNi0wNS0wMSAxODoyMjoxMCIsImkiOjQyfQ"
}

​
What’s next

Authentication

How Bearer keys and entitlements work.

Rate limits

Per-key limits, budget headers, and handling 429s.

Pagination

Page through large result sets with opaque cursors.

Incremental sync

Pull only what changed since your last run.

Errors

The error envelope and the codes your client should branch on.

API reference

Every endpoint with request and response schemas.