> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acelabusa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals API

> Load every signal for your brands into your CRM or data warehouse, then keep it in sync, with one REST endpoint.

The **Signals API** gives you the same signals as the [CRM Integration](https://docs.acelabusa.com/partner-help-center/integrations/crm-integration.md), through one REST endpoint that you or your integrator call. Load your full history once, then call again to pick up new and changed signals.

For what each signal type and field means, see the [Signals API Data Dictionary](https://docs.acelabusa.com/partner-help-center/integrations/signals-api-data-dictionary.md).

## Before You Start

The Signals API uses the same API key as Zapier. An **Org Admin** of your organization creates it in Acelab under **My Account → Integrations** (see [Connecting Zapier](https://docs.acelabusa.com/partner-help-center/integrations/crm-integration.md#connecting-zapier) for the steps). Keys start with `ak_`.

* **One key covers all of your organization's brands.** For a distributor or rep firm, that's each brand you carry (see [One Key for All Your Brands](https://docs.acelabusa.com/partner-help-center/integrations/crm-integration.md#one-key-for-all-your-brands)). Every signal carries its `brandId`, so route by brand on your side.
* **Working with an integrator?** Create a key and give it to them. Deleting the key stops their access.

## Making a Request

| | |
| - | - |
| **Address** | `GET https://signals.acelabusa.com/v1/signals` |
| **Authentication** | Your API key in the `X-Api-Key` header |
| **Format** | JSON over HTTPS. Field names are camelCase, ids are UUIDs, and timestamps are UTC (ISO 8601). |
| **Rate limit** | 60 requests per minute per key |

```bash theme={null}
curl "https://signals.acelabusa.com/v1/signals?limit=100" \
  -H "X-Api-Key: ak_your_key"
```

> [!WARNING]
>
> Send the key only in the `X-Api-Key` header. A URL ends up in logs and browser history, so a key in the URL is refused with a `400`.

### Parameters

All parameters are optional.

| Parameter | Type | What it does |
| - | - | - |
| `cursor` | string | The `nextCursor` from your previous response. Leave it out to start from the oldest signal. |
| `limit` | integer | Signals per page, from 1 to 100. Defaults to 100. |
| `type` | string | Return only this signal type. Repeat it for several types: `?type=info-request&type=added-to-spec`. Leave it out for every type. |

### The Response

Each response is one page of signals, oldest change first:

```json theme={null}
{
  "data": [
    { "id": "6f1c2a4e-8b3d-4c7a-9e21-0a5b7c9d1e2f", "signalType": "viewed-product-page", "...": "..." }
  ],
  "nextCursor": "djE6MTI4NDU",
  "hasMore": true
}
```

| Field | What it means |
| - | - |
| `data` | The signals in this page. Empty when there's nothing new. Each signal is described in the [data dictionary](https://docs.acelabusa.com/partner-help-center/integrations/signals-api-data-dictionary.md). |
| `nextCursor` | Pass it as `cursor` on your next call. It's always present, even on an empty page. Treat it as an opaque string. |
| `hasMore` | `true` when more signals are ready now. `false` when you're caught up. |

## Syncing Your Signals

**1. Load your history**

Call without a `cursor`. You get your oldest signals first.

**2. Store each page, then save its cursor**

Upsert the page's signals, then save its `nextCursor`. Saving the cursor last means an interrupted run picks up where it left off.

**3. Keep calling while hasMore is true**

Call again right away with the saved cursor until `hasMore` is `false`.

**4. Sync on a schedule**

Once you're caught up, keep the cursor and call again later, for example every 15 minutes. Signals from the last few seconds are held back until they settle, so a new signal can take a moment to appear.

### Keeping Records Up to Date

* **Upsert on `id`.** Several signal types update the same record when the activity repeats (see [How often it fires](https://docs.acelabusa.com/partner-help-center/integrations/signals-api-data-dictionary.md#signal-types)). An updated signal comes back on a later page with the same `id`. That's expected: update the row you already have.
* **Key Registered for Event on `consumerCompanyId` + `eventKey`.** There's one record per firm per event, and its `id` changes with each new registrant. Update `participantCount` and `participants` from the newest record.
* **Match firms on `consumerCompanyId`**, not the firm's name. It's stable.
* **Key projects on `projectId`.** When a hidden project becomes visible, a later signal carries its name, description and architect. Don't overwrite a value you already have with `null`.

### What Isn't Re-sent

The API sends a signal again when the signal itself changes. A few changes in Acelab don't change the signals you already received, so nothing is re-sent for them:

* **A hidden project becoming visible.** Signals you received while it was hidden keep their `null` name, description and architect. Only signals recorded after that carry them.
* **A firm leaving your accounts.** When the brand removes a firm, or the firm stops qualifying for leads, the signals you already received from it aren't withdrawn.
* **A project the brand removes.** Its earlier signals stay as you received them.
* **A signal moved to another brand.** If Acelab re-attributes a signal to a different brand, the copy you received under the old brand isn't withdrawn.
* **Account deletions.** If a conversation starter or event registrant deletes their Acelab account, their name stays in the records you already synced.

## Errors

| Status | When | What you get |
| - | - | - |
| `400` | The `cursor` isn't one this API issued | `Invalid cursor. Pass the nextCursor from a previous response, or leave it out to start from the beginning.` |
| `400` | A `type` isn't one of the 12 signal types | `Unsupported type '…'. Supported values: …`, listing every type |
| `400` | An `api_key` parameter is in the URL of a request with a valid key | `Send the API key in the X-Api-Key header, not in the URL.` |
| `400` | `limit` isn't a number | A JSON validation error (`application/problem+json`) |
| `401` | The key is missing, unknown, expired or deleted | No body |
| `429` | The key made more than 60 requests in a minute | A `Retry-After` header with the seconds to wait |
| `502`, `504` | The service is temporarily unavailable or timed out | A short message. Try again later. |

The `400` messages are text, except the `limit` validation error, which is JSON.

## API Key Expiry

Keys expire **one year after they're created**, and an expired key gets a `401`. An Org Admin can extend a key only after it expires: on **My Account → Integrations**, click **Extend** on the expired key. Until then, your sync stops.

After the extension, the same key works again. Your next call with the saved cursor picks up every signal recorded in the meantime.

If your plan stops including API access, all of your organization's keys expire.

## OpenAPI Spec

The OpenAPI 3.1 spec for the endpoint is at [`https://signals.acelabusa.com/openapi.json`](https://signals.acelabusa.com/openapi.json). Import it into your integration tool or API client to get the parameters and response schema.

## Related

> [card] [Signals API Data Dictionary](https://docs.acelabusa.com/partner-help-center/integrations/signals-api-data-dictionary.md)
>
> Every signal type and field the API returns.

> [card] [CRM Integration](https://docs.acelabusa.com/partner-help-center/integrations/crm-integration.md)
>
> Send signals to your CRM through Zapier instead.
