> ## 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 Data Dictionary

> Every signal type and field the Signals API returns, with example payloads and what stays private.

A **signal** is one record of an architecture or design firm engaging with your brand or products on Acelab. Each signal says which firm, which brand, what happened and when, and for project activity, which project.

This page describes each signal the [Signals API](https://docs.acelabusa.com/partner-help-center/integrations/signals-api.md) returns.

## Signal Types

There are 12 signal types. Firm-level types tell you about the firm. Project-level types also tell you the project. The `signalType` field holds the value in the first column.

Treat the set as open: Acelab can add types later, so your mapping should accept a type it doesn't know.

| `signalType` | Level | What happened | `label` holds | How often it fires |
| - | - | - | - | - |
| `viewed-brand-page` | Firm | Someone at the firm viewed your brand page | Brand name | Once per person, per page, per UTC day |
| `viewed-product-page` | Firm | Someone at the firm viewed one of your product pages | Product name | Once per person, per product, per UTC day |
| `file-downloaded` | Firm | Someone at the firm downloaded one of your files | File name | Once per person, per file, per UTC day |
| `appeared-in-search` | Firm | Your products appeared in the results of a search someone at the firm ran | The search text, as typed | Once per person, per brand, per distinct search, per UTC day. The busiest type by far. |
| `saved-to-library` | Firm | One of your products was saved to the firm's library | Product name | Each time |
| `saved-to-general-research` | Firm | One of your products was saved to the firm's General Research | Product name | Each time |
| `general-inquiry` | Firm | A conversation with your team started that isn't about a specific project | `null` | Once per conversation, when it starts |
| `registered-for-event` | Firm | One or more people at the firm registered for your event or webinar | Event name | Once per new registrant, on one record per firm per event |
| `saved-to-project` | Project | One of your products was saved to a project | Product name | Each time |
| `added-to-spec` | Project | One of your products was added to a project's spec | Product name | One record per product, per project. Never updated, and adding it again creates nothing. |
| `mapped-to-revit-model` | Project | One of your products was mapped to a project's Revit model | Product name | One record per product, per project. Never updated, and mapping it again creates nothing. |
| `info-request` | Project | A conversation with your team started about a specific project | `null` | Once per conversation, when it starts |

The types that fire "once per" a window update the same record when the activity repeats inside it: the `id` stays the same and `occurredAt` moves forward. See [Keeping Records Up to Date](https://docs.acelabusa.com/partner-help-center/integrations/signals-api.md#keeping-records-up-to-date).

## Fields

Each signal is one JSON object. Every field is always present, and a field that doesn't apply is `null`.

| Field | Type | Can be null | What it holds |
| - | - | - | - |
| `id` | UUID | Never | The signal's id. Upsert on it. |
| `signalType` | string | Never | One of the [signal types](#signal-types). |
| `occurredAt` | timestamp (UTC) | Rarely | When the activity happened. For types that update in place, the most recent activity. |
| `brandId` | UUID | Never | The brand the signal is about. One key covers several brands, so route on this. |
| `brandName` | string | Never | The brand's display name. |
| `label` | string | Yes | What the signal is about. It depends on the type (see [Signal Types](#signal-types)). On `appeared-in-search` it's free text someone typed, not a catalog name. |
| `consumerCompanyId` | UUID | Never | The architecture or design firm. Stable: use it to match the account in your CRM. On project-level signals, it's always the firm that owns the project. |
| `consumerCompanyName` | string | Never | The firm's display name. |
| `actorUserId` | UUID | Yes | `info-request` and `general-inquiry` only: who sent the first recorded message. This can be someone at the firm, your own rep or Acelab staff. For conversations from before mid-August 2026, it can be the sender of a later message. `null` on every other type. |
| `actorFirstName` | string | Yes | Same rule as `actorUserId`. |
| `actorLastName` | string | Yes | Same rule as `actorUserId`. |
| `projectId` | UUID | Yes | Project-level types: always present. Firm-level types: `null`. |
| `projectHidden` | boolean | Never | `true` while the project isn't visible to your brand yet. `projectName`, `project.description` and `project.architectName` are then `null`. Always `false` on firm-level types. |
| `projectName` | string | Yes | The project's name, once it's visible to your brand. |
| `project` | object | Yes | The project's details, as on the Project Detail page in Acelab. `null` on firm-level types. |
| `project.description` | string | Yes | The project's description, once it's visible to your brand. |
| `project.architectName` | string | Yes | Display only: a person's name, with no id. It's the value your brand entered in Acelab, or else the name of the person who created the project. `null` while the project is hidden, unless your brand entered one. To identify the firm, use `consumerCompanyId`. |
| `project.status` | string | Yes | Project status. |
| `project.phase` | string | Yes | Design or construction phase. |
| `project.type` | string | Yes | Building use. |
| `project.budget` | string | Yes | Budget range, as a display value. |
| `project.location` | string | Yes | City, state and country. |
| `project.sizeGsf` | integer | Yes | Gross floor area in square feet. |
| `project.constructionStartDate` | date | Yes | Planned construction start (`YYYY-MM-DD`). |
| `project.constructionType` | string | Yes | Construction type. |
| `project.ibcConstructionType` | string | Yes | IBC construction type. |
| `project.climateZone` | string | Yes | Climate zone. |
| `project.energyCode` | string | Yes | Energy code. |
| `project.occupancyClassifications` | array of strings | Never | Occupancy classifications. Empty when there are none. |
| `project.sustainabilityCertifications` | array of strings | Never | Sustainability certifications the project targets. Empty when there are none. |
| `eventKey` | string | Yes | `registered-for-event` only: identifies the event. With `consumerCompanyId`, the stable key of the record. |
| `participantCount` | integer | Yes | `registered-for-event` only: how many people at the firm registered. |
| `participants` | array | Yes | `registered-for-event` only: every registrant from the firm. |
| `participants[].userId` | UUID | Never | The registrant's Acelab id. |
| `participants[].firstName` | string | Yes | The registrant's first name. |
| `participants[].lastName` | string | Yes | The registrant's last name. |
| `participants[].photoUrl` | string (URL) | Yes | The registrant's profile photo. |

## Example Payloads

The values below are illustrative.

> [accordion] Firm level: viewed-product-page
>
> ```json theme={null}
> {
>   "id": "6f1c2a4e-8b3d-4c7a-9e21-0a5b7c9d1e2f",
>   "signalType": "viewed-product-page",
>   "occurredAt": "2026-11-06T18:42:10Z",
>   "brandId": "3b8e1d22-7c4f-4a90-b6e5-2d1f0c9a8b77",
>   "brandName": "Sample Brand",
>   "label": "Acoustic Ceiling Tile",
>   "consumerCompanyId": "9a7d5c3b-1e2f-4a6b-8c0d-4e5f6a7b8c9d",
>   "consumerCompanyName": "Smith Architecture",
>   "actorUserId": null,
>   "actorFirstName": null,
>   "actorLastName": null,
>   "projectId": null,
>   "projectHidden": false,
>   "projectName": null,
>   "project": null,
>   "eventKey": null,
>   "participantCount": null,
>   "participants": null
> }
> ```

> [accordion] Project level: added-to-spec, project visible to your brand
>
> ```json theme={null}
> {
>   "id": "0c2e4a6b-8d1f-4b3a-a5c7-e9f1a3b5c7d9",
>   "signalType": "added-to-spec",
>   "occurredAt": "2026-11-05T15:03:44Z",
>   "brandId": "3b8e1d22-7c4f-4a90-b6e5-2d1f0c9a8b77",
>   "brandName": "Sample Brand",
>   "label": "Acoustic Ceiling Tile",
>   "consumerCompanyId": "9a7d5c3b-1e2f-4a6b-8c0d-4e5f6a7b8c9d",
>   "consumerCompanyName": "Smith Architecture",
>   "actorUserId": null,
>   "actorFirstName": null,
>   "actorLastName": null,
>   "projectId": "5e7a9c1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b",
>   "projectHidden": false,
>   "projectName": "Riverside Medical Center",
>   "project": {
>     "description": "New 4-story outpatient clinic.",
>     "architectName": "Jane Smith",
>     "status": "Active",
>     "phase": "Design Development",
>     "type": "Healthcare",
>     "budget": "$10M - $50M",
>     "location": "Portland, OR, USA",
>     "sizeGsf": 85000,
>     "constructionStartDate": "2027-04-01",
>     "constructionType": "New Construction",
>     "ibcConstructionType": "Type I-B",
>     "climateZone": "4C",
>     "energyCode": "Oregon Energy Code 2021",
>     "occupancyClassifications": ["B - Business"],
>     "sustainabilityCertifications": ["LEED Silver"]
>   },
>   "eventKey": null,
>   "participantCount": null,
>   "participants": null
> }
> ```
>
> If the project were hidden from your brand, `projectHidden` would be `true`, and `projectName`, `project.description` and `project.architectName` would be `null`. `projectId` and the other project details stay the same.

> [accordion] Event: registered-for-event
>
> ```json theme={null}
> {
>   "id": "b4d6f8a1-c3e5-4f7a-9b1d-3f5a7c9e1b3d",
>   "signalType": "registered-for-event",
>   "occurredAt": "2026-11-04T20:15:00Z",
>   "brandId": "3b8e1d22-7c4f-4a90-b6e5-2d1f0c9a8b77",
>   "brandName": "Sample Brand",
>   "label": "Designing for Acoustic Comfort",
>   "consumerCompanyId": "9a7d5c3b-1e2f-4a6b-8c0d-4e5f6a7b8c9d",
>   "consumerCompanyName": "Smith Architecture",
>   "actorUserId": null,
>   "actorFirstName": null,
>   "actorLastName": null,
>   "projectId": null,
>   "projectHidden": false,
>   "projectName": null,
>   "project": null,
>   "eventKey": "webinar-2026-03-acoustics",
>   "participantCount": 2,
>   "participants": [
>     { "userId": "2f4a6c8e-1b3d-4f5a-8c7e-9a1b3c5d7e9f", "firstName": "Jane", "lastName": "Smith", "photoUrl": null },
>     { "userId": "7c9e1a3b-5d7f-4b9a-a1c3-e5f7a9b1c3d5", "firstName": "Ravi", "lastName": "Patel", "photoUrl": null }
>   ]
> }
> ```

## What Stays Private

The Signals API returns the same data your brand sees on the Accounts and Projects pages in Acelab, and no more.

* **People.** Signals from browsing, downloads, searches and saves name the firm, not the person. Names are sent only where Acelab shows them to your brand: whoever started a conversation (`info-request`, `general-inquiry`), event registrants, and the architect of a visible project.
* **Hidden projects.** Until a project is visible to your brand, its name, description and architect are `null`. The API still sends its `projectId` and other details, with `projectHidden: true`.
* **Firms outside your accounts.** You only get signals from firms that qualify for your brand's Accounts page.

Not included:

| Data | Status |
| - | - |
| Names of the people behind views, downloads, searches and saves | Not available |
| Email addresses or phone numbers of anyone | Not available |
| Name, description or architect of a hidden project | Not available until the project is visible |
| Plan room, drawings or specification documents | Not available |
| Signals for brands your organization doesn't own or carry | Not available |
