API reference
Projects
Projects group assistants, numbers and keys inside an organization.
List projects
GET/api/projects
Projects in the organization, newest first. A project-scoped key sees only its own project. Archived projects are left out unless archived=true.
Secret API key. How it works
Query parameters
archivedbooleantrue: only archived projects. Absent: only active ones.
Returns
200 OK
Response attributes
dataarray of Projectrequired10 attributes
idstringrequiredorg_idstringrequirednamestringrequireddefault_phone_countrystring | nullISO 3166 alpha-2 country for phones typed without a country code; null when not set.
timezonestring | nullIANA time zone the contact hours are read in, such as
Asia/Kolkata; null when not set.contact_hoursContactHours | nullWhen outreach may contact people; null: only the country rules apply.
One of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
is_defaultbooleanrequiredThe organization's default project. Exactly one active project per organization is the default.
archived_atstring | nullrequiredISO 8601 timestampWhen the project was archived, which pauses everything it runs; null while active.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/projects" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"default_phone_country": "+14155550123",
"timezone": "string",
"contact_hours": {
"weekly": [
{}
],
"holidays": [
{}
]
},
"is_default": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
]
}Create a project
POST/api/projects
A new project to hold assistants, numbers, keys and webhooks. It becomes the default when the organization has none. Needs an org-wide key: a project-scoped key gets 403 invalid_request ("A project-scoped key cannot create projects.").
Secret API key, not a viewer key, org-wide (not pinned to a project). How it works
Request body
namestringrequirednot empty
Returns
201 OK
Response attributes
dataProjectrequired10 attributes
idstringrequiredorg_idstringrequirednamestringrequireddefault_phone_countrystring | nullISO 3166 alpha-2 country for phones typed without a country code; null when not set.
timezonestring | nullIANA time zone the contact hours are read in, such as
Asia/Kolkata; null when not set.contact_hoursContactHours | nullWhen outreach may contact people; null: only the country rules apply.
One of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
is_defaultbooleanrequiredThe organization's default project. Exactly one active project per organization is the default.
archived_atstring | nullrequiredISO 8601 timestampWhen the project was archived, which pauses everything it runs; null while active.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/projects" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk"
}'{
"data": {
"id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"default_phone_country": "+14155550123",
"timezone": "string",
"contact_hours": {
"weekly": [
{
"day": {},
"open": {},
"close": {}
}
],
"holidays": [
"2026-10-28"
]
},
"is_default": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Get a project
GET/api/projects/{id}
One project, archived or not.
Secret API key. How it works
Path parameters
idstringrequiredProject id,
proj_....
Returns
200 OK
Response attributes
dataProjectrequired10 attributes
idstringrequiredorg_idstringrequirednamestringrequireddefault_phone_countrystring | nullISO 3166 alpha-2 country for phones typed without a country code; null when not set.
timezonestring | nullIANA time zone the contact hours are read in, such as
Asia/Kolkata; null when not set.contact_hoursContactHours | nullWhen outreach may contact people; null: only the country rules apply.
One of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
is_defaultbooleanrequiredThe organization's default project. Exactly one active project per organization is the default.
archived_atstring | nullrequiredISO 8601 timestampWhen the project was archived, which pauses everything it runs; null while active.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/projects/PROJECT_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"default_phone_country": "+14155550123",
"timezone": "string",
"contact_hours": {
"weekly": [
{
"day": {},
"open": {},
"close": {}
}
],
"holidays": [
"2026-10-28"
]
},
"is_default": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Update a project
PATCH/api/projects/{id}
Rename a project, set its default phone country (the ISO 3166 alpha-2 country a lead's phone typed without a country code is read in when the visitor's own country is unknown), or set its timezone and contact hours (when outreach may message and call people). null clears any of the last three. Needs the admin role.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredProject id,
proj_....
Request body
namestringnot emptydefault_phone_countrystring | nulltimezonestring | nullAn IANA time zone, such as
Asia/Kolkata.contact_hoursContactHours | nullOne of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
Returns
200 OK
Response attributes
dataProjectrequired10 attributes
idstringrequiredorg_idstringrequirednamestringrequireddefault_phone_countrystring | nullISO 3166 alpha-2 country for phones typed without a country code; null when not set.
timezonestring | nullIANA time zone the contact hours are read in, such as
Asia/Kolkata; null when not set.contact_hoursContactHours | nullWhen outreach may contact people; null: only the country rules apply.
One of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
is_defaultbooleanrequiredThe organization's default project. Exactly one active project per organization is the default.
archived_atstring | nullrequiredISO 8601 timestampWhen the project was archived, which pauses everything it runs; null while active.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PATCH "https://api.brightshoal.com/api/projects/PROJECT_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Travel UK"
}'{
"data": {
"id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"default_phone_country": "+14155550123",
"timezone": "string",
"contact_hours": {
"weekly": [
{
"day": {},
"open": {},
"close": {}
}
],
"holidays": [
"2026-10-28"
]
},
"is_default": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Archive a project
POST/api/projects/{id}/archive
Pauses everything the project runs: its assistants stop answering chats and calls, its website chat, forms and booking pages stop taking visitors, follow-ups stop sending, Search starts no checks, and its webhooks and alerts stop. Its live calls are ended. Its records stay readable, phone numbers stay on the account, and nothing is deleted. It leaves the projects list (see archived=true). Archiving an archived project is a no-op. Needs the admin role and an org-wide key (a project-scoped key gets 403 invalid_request); audited as project.archived.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredProject id,
proj_....
Returns
200 OK
Response attributes
dataProjectrequired10 attributes
idstringrequiredorg_idstringrequirednamestringrequireddefault_phone_countrystring | nullISO 3166 alpha-2 country for phones typed without a country code; null when not set.
timezonestring | nullIANA time zone the contact hours are read in, such as
Asia/Kolkata; null when not set.contact_hoursContactHours | nullWhen outreach may contact people; null: only the country rules apply.
One of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
is_defaultbooleanrequiredThe organization's default project. Exactly one active project per organization is the default.
archived_atstring | nullrequiredISO 8601 timestampWhen the project was archived, which pauses everything it runs; null while active.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409
is_default: make another project the default first.last_business: the organization's only active project. - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/projects/PROJECT_ID/archive" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"default_phone_country": "+14155550123",
"timezone": "string",
"contact_hours": {
"weekly": [
{
"day": {},
"open": {},
"close": {}
}
],
"holidays": [
"2026-10-28"
]
},
"is_default": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Make a project the default
POST/api/projects/{id}/default
Makes this project the organization's default. The flag moves from the old default in one step; making the default the default again is a no-op. Needs the admin role and an org-wide key (a project-scoped key gets 403 invalid_request); audited as project.default_set.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredProject id,
proj_....
Returns
200 OK
Response attributes
dataProjectrequired10 attributes
idstringrequiredorg_idstringrequirednamestringrequireddefault_phone_countrystring | nullISO 3166 alpha-2 country for phones typed without a country code; null when not set.
timezonestring | nullIANA time zone the contact hours are read in, such as
Asia/Kolkata; null when not set.contact_hoursContactHours | nullWhen outreach may contact people; null: only the country rules apply.
One of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
is_defaultbooleanrequiredThe organization's default project. Exactly one active project per organization is the default.
archived_atstring | nullrequiredISO 8601 timestampWhen the project was archived, which pauses everything it runs; null while active.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409
archived: restore the project first. - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/projects/PROJECT_ID/default" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"default_phone_country": "+14155550123",
"timezone": "string",
"contact_hours": {
"weekly": [
{
"day": {},
"open": {},
"close": {}
}
],
"holidays": [
"2026-10-28"
]
},
"is_default": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Restore an archived project
POST/api/projects/{id}/restore
Everything the project runs starts again. Restoring an active project is a no-op. Needs the admin role and an org-wide key (a project-scoped key gets 403 invalid_request); audited as project.restored.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredProject id,
proj_....
Returns
200 OK
Response attributes
dataProjectrequired10 attributes
idstringrequiredorg_idstringrequirednamestringrequireddefault_phone_countrystring | nullISO 3166 alpha-2 country for phones typed without a country code; null when not set.
timezonestring | nullIANA time zone the contact hours are read in, such as
Asia/Kolkata; null when not set.contact_hoursContactHours | nullWhen outreach may contact people; null: only the country rules apply.
One of 2 shapes
ContactHours
weeklyarray of objectrequiredup to 28 items3 attributes
dayintegerrequired0 to 60 is Sunday.
openstringrequiredHH:MM
closestringrequiredHH:MM, after open; 24:00 is midnight.
holidaysarray of stringup to 366 items
Option 2
is_defaultbooleanrequiredThe organization's default project. Exactly one active project per organization is the default.
archived_atstring | nullrequiredISO 8601 timestampWhen the project was archived, which pauses everything it runs; null while active.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/projects/PROJECT_ID/restore" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"default_phone_country": "+14155550123",
"timezone": "string",
"contact_hours": {
"weekly": [
{
"day": {},
"open": {},
"close": {}
}
],
"holidays": [
"2026-10-28"
]
},
"is_default": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}