Skip to content
English
  • There are no suggestions because the search field is empty.

API Reference - V1

The Locable API is organized around REST and returns JSON Responses.

Contact the Locable Support team to enable API access on your account.

Updated 11.06.2026

The Locable API uses API keys to authenticate requests. You can view and manage your API keys in your Locable Account by going to Account Settings > API Keys.

NOTE: All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

 

Authentication

Send your key in either header - both are equivalent:

curl -H "X-API-Key: YOUR_API_KEY" https://impact.locable.com/api/v1/events

curl -H "Authorization: Bearer YOUR_API_KEY" https://impact.locable.com/api/v1/events

 

Your full API key is shown once, when it is created. Only last four characters are visible afterwards, so store it somewhere safe. If you lose it, rotate the key on the API Keys page and update your integration with the new value - the old one stops working immediately.

A key belongs to one business (account) and reads only that business's data.

Permissions

Each key is issued with one or more permissions, which control the endpoints it can call.

Permission

Grants access to

read:events

GET /api/v1/events

read:calendars

GET /api/v1/calendars and GET /api/v1/calendars/{calendar_id}/events

A request outside your key's permissions returns 403 naming what is missing. If you need an endpoint your key cannot reach, contact Locable Support to have the permission added. Keys issued before permissions existed continue to work for /api/v1/events.


Rate limits

Requests are capped per key:

60 requests per minute

1,000 requests per hour

Exceeding either returns 429 with retryable set to true. Wait and try again; the per-minute window clears within a minute. The limits are high enough that a normal integration never reaches them - they exist to stop a runaway script.


Errors

Every error returns the same shape:

{

"error": {

"code": "forbidden",

"message": "API key missing required scope: read:calendars",

"hint": "Add the read:calendars scope to this key in Settings > API Keys",

"details": { "reason": "missing_scope" },

"retryable": false

}

}

 

code - stable and machine-readable. Switch on this, not on the message.

message - plain English, safe to log or show to a person.

hint - what to do about it, when there is something to do.

details - structured extras, such as which field failed validation. May be null.

retryable - whether trying the same request again can succeed.

 

Status

code

Meaning

400

bad_request

A parameter is malformed - for example, a date that isn't YYYY-MM-DD

401

unauthenticated

Key missing, unrecognized, revoked, or expired

403

forbidden

The key is valid but lacks the permission for this endpoint

404

not_found

No such record, or it belongs to another business

422

validation_failed

The request was understood but the values were rejected

429

rate_limited

Too many requests; wait and retry

500

internal

Something went wrong on our side


Pagination

Results are paginated. Every list response includes:

"pagination": {

"previous_page": null,

"next_page": null,

"total_pages": 1,

"current_page": 1

}

Request a page with the page parameter:

curl -H "X-API-Key: YOUR_API_KEY" https://impact.locable.com/api/v1/events?page=2

 

Endpoints

GET /api/v1/events

Your business's published, public, upcoming events. Requires read:events.

Parameter

Description

page

Page number. 20 events per page.

Example request

curl -H "X-API-Key: YOUR_API_KEY" https://impact.locable.com/api/v1/events

Example response

{

"status": "success",

"message": "",

"events": [

{

"event_id": 40415,

"title": "A Main Street or Downtown Website That Delivers",

"subtitle": "",

"description": "<p>Whether you're considering a new website…</p>",

"meta_description": "Ensure your main street website is reaching its potential.",

"type": "Event",

"published": true,

"start_date": "2024-05-15",

"start_time": "12:00 PM CDT",

"end_time": "12:45 PM CDT",

"time_zone": "America/Chicago",

"repetition": "",

"end_date": null,

"upcoming_occurences": [

{

"date": "2024-05-15",

"canonical_url": "//www.locable.com/2024/05/15/197222/a-main-street-website"

}

],

"virtual": true,

"location": {},

"price": "Free",

"url": "https://us02web.zoom.us/webinar/register/WN_example",

"ticket_url": "",

"facebook_url": "",

"phone": null,

"image": "//impact-production.s3.amazonaws.com/_originals/6cead22d/main-street.png",

"event_categories": [

{ "category_id": 2344, "category_name": "Main Streets" },

{ "category_id": 1869, "category_name": "Anchors" }

]

}

],

"pagination": {

"previous_page": null,

"next_page": null,

"total_pages": 1,

"current_page": 1

}

}

 

Notes on individual fields

start_time and end_time are formatted in the business's time zone, and are null when the event has no such time set.

location is {} for a virtual event, or for an in-person event with no address saved, and null when the event is set to hide its address. When present it carries name, city, state, zip, latitude, longitude, and - unless the event shows its city only - address_line_1 and address_line_2.

upcoming_occurences lists the future dates of a repeating event, each with the public URL for that date.

repetition is a human-readable description of the recurrence rule, or an empty string for a one-off event.


GET /api/v1/calendars

Access the calendars on your account to find the ID to request events for. Requires read:calendars.

Example request

curl -H "X-API-Key: YOUR_API_KEY" https://impact.locable.com/api/v1/calendars

 

Example response

{

"status": "success",

"calendars": [

{

"calendar_id": 1189,

"uuid": "229bb8d3-994c-4f53-b995-48c6a4be9869",

"name": "Community Calendar",

"includes_own_events": true,

"event_categories": [

{ "category_id": 2344, "category_name": "Music" }

]

}

]

}

includes_own_events - whether the calendar shows your own events alongside events from the businesses it follows.

event_categories - the calendar's category filter. Empty means no filter.


GET /api/v1/calendars/{calendar_id}/events

The upcoming events on one calendar -provides the same set the embedded calendar widget shows, including events syndicated from other businesses moderation and filter settings are respected. Requires read:calendars.

The {calendar_id} segment accepts either the numeric calendar_id or the uuid - both from GET /api/v1/calendars. The uuid is the one that already appears in your calendar's embed code.

https://impact.locable.com/api/v1/calendars/1189/events

https://impact.locable.com/api/v1/calendars/229bb8d3-994c-4f53-b995-48c6a4be9869/events

 

Parameter

Description

start_date

Only occurrences on or after this date. YYYY-MM-DD.

end_date

Only occurrences on or before this date. YYYY-MM-DD.

category_id

Only events in this category.

page

Page number.

per_page

Events per page. Default 20, maximum 50.

Example request

curl -H "X-API-Key: YOUR_API_KEY" \

"https://impact.locable.com/api/v1/calendars/1189/events?start_date=2027-01-01&end_date=2027-01-31"

Example response

{

"status": "success",

"calendar": {

"calendar_id": 1189,

"uuid": "229bb8d3-994c-4f53-b995-48c6a4be9869",

"name": "Community Calendar"

},

"events": [

{

"event_id": 131900,

"event_definition_id": 26713,

"title": "Monthly Wednesday Walking Club",

"subtitle": "",

"description": "<p>Meet at the trailhead.</p>",

"meta_description": "A monthly walk, open to all.",

"type": "Event",

"date": "2027-01-06",

"start_time": "9:00 AM EST",

"end_time": "10:00 AM EST",

"time_zone": "America/New_York",

"virtual": false,

"location": {

"name": "Riverfront Park",

"address_line_1": "100 Main St",

"address_line_2": "",

"city": "Coloma",

"state": "MI",

"zip": "49038",

"latitude": 42.1875,

"longitude": -86.3072

},

"price": "Free",

"url": "",

"ticket_url": "",

"facebook_url": "",

"phone": null,

"image": "//impact-production.s3.amazonaws.com/_originals/abc123/walking-club.png",

"source": {

"business_id": 93,

"name": "Blue Door Bakery",

"syndicated": true

},

"event_categories": [

{ "category_id": 2344, "category_name": "Recreation" }

],

"canonical_url": "https://bluedoorbakery.com/2027/1/6/131900/walking-club"

}

],

"pagination": {

"previous_page": null,

"next_page": null,

"total_pages": 1,

"current_page": 1

}

}

How this differs from /api/v1/events

One row per occurrence. A repeating event appears once per date, with date and event_id for that occurrence, plus event_definition_id for the series. There is no upcoming_occurences array.

Other businesses' events are included, where the calendar follows them and you or your calendar's settings have approved the event. Source tells you who posted it; syndicated is true when the event belongs to another business.

Categories are yours, not theirs. For a syndicated event, event_categories shows the categories available in your specific calendar and which your moderator filed it under (or approved if pre-selected by the original event poster) - these are limited to what your calendar displays.

canonical_url points at the public page for that occurrence: the posting business's own website when they have one, and a Locable-hosted page when they don't, so the link always resolves.

location is null for a virtual event, for an event with no address saved, and for one set to hide its address - where /api/v1/events returns {} for the first two. When present the fields match /api/v1/events.