Listings APIListings API
Get API keySign in

Make your first API call

Authenticate, list your locations, read the response shape, page through results, and learn how IDs work.

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

Other endpoints reference a location by its ID, so start by listing the ones you have. The REST Authorization header uses the API scheme, followed by a space and your API key: Authorization: API <YOUR_API_KEY>.

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

3. Read the response

The REST API returns a nested response rather than a bare array. The operation name is under data, list results are returned as a connection of edges, and each edge contains 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 Python SDK returns an iterable page of objects. The Node SDK returns locations and pageInfo. When you call the REST API directly, read data.allLocations.edges[].node.

4. Page through results

List endpoints on locations and reviews use cursor pagination. Request a page with first, then pass pageInfo.endCursor as after to retrieve the next page. The SDKs can read 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 page and perPage with a records array. Each guide states which pagination format 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 requires base64 encoded ids, and they are the values returned 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

Failed responses return the matching HTTP status with an errors array. The message is prefixed with an SY error code, listed 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