Quickstart

From a staging key to a working call in a few minutes.

You need a staging PMS credential. If you don’t have one yet, request access.

1. Set two environment variables

export TATALLO_BASE_URL="https://staging.api.tatallo.com"
export TATALLO_API_KEY="tat_stg_sk_<credential-id>_<secret>"   # your staging key

Every example in these docs reads these two variables. To move to production later, change TATALLO_BASE_URL to https://api.tatallo.com and use your production key.

2. Check your key

curl -s "$TATALLO_BASE_URL/v1/me" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

You see which key you used, your PMS, the environment and the scopes:

{
  "credential_id": "5d4e040b-61c1-44a4-a4ca-9a751dc05133",
  "pms_name": "Test PMS",
  "environment": "staging",
  "scopes": [
    "properties:read"
  ]
}

credential_id is your key’s own ID, so yours may differ from the example. environment must say staging, and scopes must include properties:read.

3. List your properties

curl -s "$TATALLO_BASE_URL/v1/properties" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

On staging you get the fixture properties connected to your PMS, exactly these:

{
  "data": [
    {
      "id": "6cfa992d-1805-4de6-892c-23785031aba0",
      "name": "Fixture Loft Kreuzberg",
      "timezone": "Europe/Berlin",
      "status": "active",
      "country": "Germany",
      "city": "Berlin",
      "max_guests": 2,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "934f807c-39d6-45de-b107-d5c9e03cb041",
      "name": "Fixture House Alfama",
      "timezone": "Europe/Lisbon",
      "status": "inactive",
      "country": "Portugal",
      "city": "Lisbon",
      "max_guests": 6,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
      "name": "Fixture Apartment Trastevere",
      "timezone": "Europe/Rome",
      "status": "active",
      "country": "Italy",
      "city": "Rome",
      "max_guests": 4,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    }
  ],
  "page": {
    "next_cursor": null
  }
}

page.next_cursor is null, so this is the whole list. With more properties than fit on a page, follow the cursor: see Property discovery on staging.

4. Read one property

curl -s "$TATALLO_BASE_URL/v1/properties/bef2859f-2444-47ec-b5f4-f1e6701f087f" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

{
  "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
  "name": "Fixture Apartment Trastevere",
  "timezone": "Europe/Rome",
  "status": "active",
  "country": "Italy",
  "city": "Rome",
  "max_guests": 4,
  "currency": "EUR",
  "updated_at": "2026-10-01T09:00:00.000Z"
}

Store each property’s id in your mapping table: it never changes. What every field means: Properties.

Troubleshooting

Every error has the same shape, { "error": { "code", "message", "request_id" } }. Branch on code.

401 unauthorized

The key is missing, malformed, for the other environment, expired or revoked. Check that TATALLO_API_KEY starts with tat_stg_sk_ when TATALLO_BASE_URL is staging, that the header is exactly Authorization: Bearer <key>, and that nothing was cut when you copied it. See Authentication.

403 insufficient_scope

The key is valid but lacks properties:read. GET /v1/me shows its scopes. Ask [e-mail] for a key with the scope you need.

404 property_not_found

The property is not connected to your PMS, or does not exist. Tatallo answers both the same way on purpose. List your properties first and use their ids. See why an unconnected property is a 404.

429 rate_limited

More than 60 requests in a minute with this key. Wait for the number of seconds in the Retry-After header, then try again.

When you write to support, quote the X-Request-Id header of the failing response.