REST API | Installation | Spectacle Docs

Spectacle REST API

The Spectacle HTTP Tracking API allows you to record analytics data from any website or application.

Authentication

You can authenticate with the API using your workspace id by including it in the request body.

curl --location 'https://api.spectaclehq.com/tracking/track' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event": "Trial Started",
    "email": "user@example.org",
    "userId": "123",
    "workspaceId": "ws_example"
}'

Content-Type

All data sent to Spectacle’s HTTP API must set a content-type header to 'application/json'.

Identify

Identify links a user to actions they perform and records user traits like email, name, or industry.

Spectacle recommends calling Identify once when a user account is created, and only again if traits change.

Example Identify Call:

POST https://api.spectaclehq.com/tracking/identify

{
  "userId": "user_123",
  "anonymousId": "1234-5678-8910",
  "traits": {
    "email": "user@example.org",
    "name": "John Doe",
    "industry": "Technology"
  },
  "timestamp": "2024-12-09T00:30:08.276Z",
  "workspaceId": "YOUR_WORKSPACE_ID"
}

Fields

userId: The unique identifier for the user in your database. (String, required)
anonymousId: Can be obtained from JS. Please reach out to support to help you set this up. (String, required)
workspaceId: Can be found in your workspace settings. (String, required)
timestamp: Optional. Defaults to current time in ISO-8601 format. (Date)
traits: Optional. User details like email or name. (Object)

Special Traits

email: Email address of the user
firstName: First name of the user
lastName: Last name of the user
companyId: Company ID of the user
companyName: Company name of the user

Track

The Track method lets you capture specific actions users perform. Each action is recorded as an “event” and may include properties associated with that event, such as revenue or name.

Example Track Call:

POST https://api.spectaclehq.com/tracking/track

{
  "userId": "user_123",
  "event": "Charged",
  "properties": {
    "revenue": 1599
  },
  "timestamp": "2012-12-02T00:30:12.984Z",
  "workspaceId": "YOUR_WORKSPACE_ID"
}

Fields

userId: The unique identifier for the user in your database. (String, required)
event: The name of the action performed by the user. (String, required)
workspaceId: Can be found in your workspace settings. (String, required)
timestamp: Optional, defaults to current time in ISO-8601 format. (Date)
properties: Custom data associated with the event (e.g., revenue). (Object)

Special properties

revenue: Revenue in the smallest currency unit.
currency: The three-letter ISO code of the revenue's currency
plan: The customer's plan.
mrr: The current mrr for the customer. Every time mrr is passed, it overwrites the previous mrr.
arr: The current arr for the customer. Every time arr is passed, it overwrites the previous arr.

Group

The Group method allows you to associate an individual user with a group, such as a company, organization, or account.

Example Group Call:

POST https://api.spectaclehq.com/tracking/group

{
  "userId": "user_123",
  "groupId": "0e8c78ea9d97a7b8185e8632",
  "traits": {
    "name": "Initech",
    "plan": "enterprise",
    "anythingElse": "Can be added here"
  },
  "timestamp": "2024-12-02T00:30:08.276Z",
  "workspaceId": "YOUR_WORKSPACE_ID"
}

Fields

userId: The unique identifier for the user in your database. (String, required)
groupId: A unique identifier for the group in your database. (String, required)
workspaceId: Can be found in your workspace settings. (String, required)
timestamp: Optional, defaults to current time in ISO-8601 format. (Date)
traits: Optional. Group details. (Object)

Special Traits

name: Name of the group/company
email: An email address for the group
plan: Current plan of the group

Page

The Page method allows you to record page views on a website, along with optional data about the page being viewed, such as URL and title.

Example Page Call:

POST https://api.spectaclehq.com/tracking/page

{
  "userId": "user_123",
  "timestamp": "2012-12-02T00:31:29.738Z",
  "workspaceId": "YOUR_WORKSPACE_ID",
  "url": "https://www.example.com/page?utm_campaign=cool_campaign",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
  "referrer": "https://www.example.com/referrer"
}

Fields

anonymousId: Required if userId is not set. A unique identifier for users without a userId. Spectacle recommends using a UUIDv4 (String)
userId: Required if anonymousId is not set. The unique identifier for the user in your database. (String)
workspaceId: Can be found in your workspace settings. (String, required)
url: The URL of the page being viewed. (String, required)
userAgent: The user agent of the browser used to view the page. (String, required)
referrer: The http referrer for of the page. important This property should be set if a referrer was set for the page view to ensure proper attribution (String, required if available)
timestamp: Optional, defaults to current time in ISO-8601 format. (Date)

Bot Filtering

When using the REST API, bot filtering is not as sophisticated as it is with Spectacle's Javascript library. This is because the REST API does not have access to the same number of data points used in Spectacle's bot filtering. Spectacle does however inspect the userAgent property to filter out any self-identifying bots.