BrightshoalDocsOpen console
MenuProjects

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

  • archivedboolean

    true: only archived projects. Absent: only active ones.

Returns

200 OK

Response attributes
  • dataarray of Projectrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • namestringrequired

    • default_phone_countrystring | null

      ISO 3166 alpha-2 country for phones typed without a country code; null when not set.

    • timezonestring | null

      IANA time zone the contact hours are read in, such as Asia/Kolkata; null when not set.

    • contact_hoursContactHours | null

      When outreach may contact people; null: only the country rules apply.

      One of 2 shapes

      ContactHours

      • weeklyarray of objectrequiredup to 28 items

        3 attributes
        • dayintegerrequired0 to 6

          0 is Sunday.

        • openstringrequired

          HH:MM

        • closestringrequired

          HH:MM, after open; 24:00 is midnight.

      • holidaysarray of stringup to 366 items

      Option 2

    • is_defaultbooleanrequired

      The organization's default project. Exactly one active project per organization is the default.

    • archived_atstring | nullrequiredISO 8601 timestamp

      When the project was archived, which pauses everything it runs; null while active.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/projects
curl "https://api.brightshoal.com/api/projects" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
  • dataProjectrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • namestringrequired

    • default_phone_countrystring | null

      ISO 3166 alpha-2 country for phones typed without a country code; null when not set.

    • timezonestring | null

      IANA time zone the contact hours are read in, such as Asia/Kolkata; null when not set.

    • contact_hoursContactHours | null

      When outreach may contact people; null: only the country rules apply.

      One of 2 shapes

      ContactHours

      • weeklyarray of objectrequiredup to 28 items

        3 attributes
        • dayintegerrequired0 to 6

          0 is Sunday.

        • openstringrequired

          HH:MM

        • closestringrequired

          HH:MM, after open; 24:00 is midnight.

      • holidaysarray of stringup to 366 items

      Option 2

    • is_defaultbooleanrequired

      The organization's default project. Exactly one active project per organization is the default.

    • archived_atstring | nullrequiredISO 8601 timestamp

      When the project was archived, which pauses everything it runs; null while active.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
POST /api/projects
curl -X POST "https://api.brightshoal.com/api/projects" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk"
}'
Response 201
{
  "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

  • idstringrequired

    Project id, proj_....

Returns

200 OK

Response attributes
  • dataProjectrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • namestringrequired

    • default_phone_countrystring | null

      ISO 3166 alpha-2 country for phones typed without a country code; null when not set.

    • timezonestring | null

      IANA time zone the contact hours are read in, such as Asia/Kolkata; null when not set.

    • contact_hoursContactHours | null

      When outreach may contact people; null: only the country rules apply.

      One of 2 shapes

      ContactHours

      • weeklyarray of objectrequiredup to 28 items

        3 attributes
        • dayintegerrequired0 to 6

          0 is Sunday.

        • openstringrequired

          HH:MM

        • closestringrequired

          HH:MM, after open; 24:00 is midnight.

      • holidaysarray of stringup to 366 items

      Option 2

    • is_defaultbooleanrequired

      The organization's default project. Exactly one active project per organization is the default.

    • archived_atstring | nullrequiredISO 8601 timestamp

      When the project was archived, which pauses everything it runs; null while active.

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
GET /api/projects/{id}
curl "https://api.brightshoal.com/api/projects/PROJECT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Project id, proj_....

Request body

  • namestringnot empty

  • default_phone_countrystring | null

  • timezonestring | null

    An IANA time zone, such as Asia/Kolkata.

  • contact_hoursContactHours | null

    One of 2 shapes

    ContactHours

    • weeklyarray of objectrequiredup to 28 items

      3 attributes
      • dayintegerrequired0 to 6

        0 is Sunday.

      • openstringrequired

        HH:MM

      • closestringrequired

        HH:MM, after open; 24:00 is midnight.

    • holidaysarray of stringup to 366 items

    Option 2

Returns

200 OK

Response attributes
  • dataProjectrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • namestringrequired

    • default_phone_countrystring | null

      ISO 3166 alpha-2 country for phones typed without a country code; null when not set.

    • timezonestring | null

      IANA time zone the contact hours are read in, such as Asia/Kolkata; null when not set.

    • contact_hoursContactHours | null

      When outreach may contact people; null: only the country rules apply.

      One of 2 shapes

      ContactHours

      • weeklyarray of objectrequiredup to 28 items

        3 attributes
        • dayintegerrequired0 to 6

          0 is Sunday.

        • openstringrequired

          HH:MM

        • closestringrequired

          HH:MM, after open; 24:00 is midnight.

      • holidaysarray of stringup to 366 items

      Option 2

    • is_defaultbooleanrequired

      The organization's default project. Exactly one active project per organization is the default.

    • archived_atstring | nullrequiredISO 8601 timestamp

      When the project was archived, which pauses everything it runs; null while active.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
PATCH /api/projects/{id}
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"
}'
Response 200
{
  "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

  • idstringrequired

    Project id, proj_....

Returns

200 OK

Response attributes
  • dataProjectrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • namestringrequired

    • default_phone_countrystring | null

      ISO 3166 alpha-2 country for phones typed without a country code; null when not set.

    • timezonestring | null

      IANA time zone the contact hours are read in, such as Asia/Kolkata; null when not set.

    • contact_hoursContactHours | null

      When outreach may contact people; null: only the country rules apply.

      One of 2 shapes

      ContactHours

      • weeklyarray of objectrequiredup to 28 items

        3 attributes
        • dayintegerrequired0 to 6

          0 is Sunday.

        • openstringrequired

          HH:MM

        • closestringrequired

          HH:MM, after open; 24:00 is midnight.

      • holidaysarray of stringup to 366 items

      Option 2

    • is_defaultbooleanrequired

      The organization's default project. Exactly one active project per organization is the default.

    • archived_atstring | nullrequiredISO 8601 timestamp

      When the project was archived, which pauses everything it runs; null while active.

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
POST /api/projects/{id}/archive
curl -X POST "https://api.brightshoal.com/api/projects/PROJECT_ID/archive" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Project id, proj_....

Returns

200 OK

Response attributes
  • dataProjectrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • namestringrequired

    • default_phone_countrystring | null

      ISO 3166 alpha-2 country for phones typed without a country code; null when not set.

    • timezonestring | null

      IANA time zone the contact hours are read in, such as Asia/Kolkata; null when not set.

    • contact_hoursContactHours | null

      When outreach may contact people; null: only the country rules apply.

      One of 2 shapes

      ContactHours

      • weeklyarray of objectrequiredup to 28 items

        3 attributes
        • dayintegerrequired0 to 6

          0 is Sunday.

        • openstringrequired

          HH:MM

        • closestringrequired

          HH:MM, after open; 24:00 is midnight.

      • holidaysarray of stringup to 366 items

      Option 2

    • is_defaultbooleanrequired

      The organization's default project. Exactly one active project per organization is the default.

    • archived_atstring | nullrequiredISO 8601 timestamp

      When the project was archived, which pauses everything it runs; null while active.

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
POST /api/projects/{id}/default
curl -X POST "https://api.brightshoal.com/api/projects/PROJECT_ID/default" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Project id, proj_....

Returns

200 OK

Response attributes
  • dataProjectrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • namestringrequired

    • default_phone_countrystring | null

      ISO 3166 alpha-2 country for phones typed without a country code; null when not set.

    • timezonestring | null

      IANA time zone the contact hours are read in, such as Asia/Kolkata; null when not set.

    • contact_hoursContactHours | null

      When outreach may contact people; null: only the country rules apply.

      One of 2 shapes

      ContactHours

      • weeklyarray of objectrequiredup to 28 items

        3 attributes
        • dayintegerrequired0 to 6

          0 is Sunday.

        • openstringrequired

          HH:MM

        • closestringrequired

          HH:MM, after open; 24:00 is midnight.

      • holidaysarray of stringup to 366 items

      Option 2

    • is_defaultbooleanrequired

      The organization's default project. Exactly one active project per organization is the default.

    • archived_atstring | nullrequiredISO 8601 timestamp

      When the project was archived, which pauses everything it runs; null while active.

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
POST /api/projects/{id}/restore
curl -X POST "https://api.brightshoal.com/api/projects/PROJECT_ID/restore" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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"
  }
}