Listings APIListings API
Get API keySign in

Make your first API call

Authenticate, list your locations, read the response envelope, page through results, and learn how IDs work. About five minutes.

This guide assumes you have an account and an API key from Getting started. Every request runs against the live API at https://listingsapi.com. There is no sandbox, so a write call changes real data.

1. Set your API key

Copy the key from API Keys in the dashboard and export it once in your shell:

bash
export LISTINGSAPI_KEY="your-api-key"

Keys carry an access level. A Read key covers every lookup and report in these guides. Creating or updating anything, replying to a review, or publishing a post needs a Write key. Sending a Read key to a write endpoint returns HTTP 400 with error code SY90016.

2. List your locations

Locations are the master record everything else hangs off, so the first call is to list them. The REST header is the literal word API, a space, then the key.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Read the envelope

The REST API returns a GraphQL-style envelope, so the payload is nested rather than a bare array. The operation name sits under data, list results are a connection of edges, and each edge wraps a node:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

The SDKs unwrap this for you: Python hands back an iterable page of objects, and Node hands back locations plus pageInfo. When you call REST directly, read data.allLocations.edges[].node.

4. Page through results

List endpoints on locations and reviews use cursor pagination. Ask for a page with first, then pass pageInfo.endCursor back as after to get the next one. The SDKs can walk every page for you.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

Not every endpoint paginates this way. Connected accounts, duplicate rollups, and posts use plain page and perPage numbers with a records array. Each guide says which style its endpoints use.

5. Two kinds of ID

Every record has two identifiers. id is a base64 string such as TG9jYXRpb246MTgwMDI4OQ==, which decodes to Location:1800289. databaseId is the plain number, 1800289.

Store the base64 id. Every write endpoint wants it, and it is what appears in webhook payloads. Many read endpoints that take a location in the path also accept the raw number, and both SDKs accept either form and encode for you.

6. Errors and rate limits

Failures return the matching HTTP status with an errors array. The message starts with an SY code you can look up in Error codes:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

Rate limits are per plan and counted per minute, hour, and day. Launch allows 10 requests a minute. When you exceed a limit the API answers 429 with a Retry-After header; wait that many seconds rather than retrying at once. The SDKs raise RateLimitError and expose the same value. Full detail is in Rate limits.

Next steps