Quickstart - Hamlet API

Get Started with the API

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"
}