Traits API

Traits are reusable computed properties attached to a parent entity model. They let you define aggregations, occurrences, lists, formulas, and custom SQL calculations that enrich your customer profiles and power audience segmentation.

Endpoints

Method	Path	Description
`GET`	`/api/v1/workspaces/{id}/traits`	List all traits
`POST`	`/api/v1/workspaces/{id}/traits`	Create a trait
`GET`	`/api/v1/workspaces/{id}/traits/{traitId}`	Get a trait
`PUT`	`/api/v1/workspaces/{id}/traits/{traitId}`	Update a trait
`DELETE`	`/api/v1/workspaces/{id}/traits/{traitId}`	Delete a trait
`GET`	`/api/v1/workspaces/{id}/models/{modelId}/traits`	List traits by model
`POST`	`/api/v1/workspaces/{id}/traits/{traitId}/trigger`	Trigger trait evaluation
`GET`	`/api/v1/workspaces/{id}/traits/{traitId}/runs`	List trait runs

List Traits

GET /api/v1/workspaces/{id}/traits

Returns all traits in the workspace.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "Total Purchases",
    "slug": "total_purchases",
    "description": "Total number of purchases per customer",
    "trait_type": "aggregation",
    "config": {
      "source_model_id": "880e8400-e29b-41d4-a716-446655440000",
      "relationship_id": "990e8400-e29b-41d4-a716-446655440000",
      "aggregation": "count",
      "column": "order_id"
    },
    "result_type": "number",
    "status": "active",
    "status_error": "",
    "created_by": "aae8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "last_computed_at": "2024-01-15T15:00:00Z"
  }
]

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/traits \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Create Trait

POST /api/v1/workspaces/{id}/traits

Creates a new trait definition.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name
`description`	string	No	Description
`parent_model_id`	string (UUID)	Yes	Parent entity model this trait attaches to
`trait_type`	string	Yes	`aggregation`, `occurrence`, `list`, `sql`, or `formula`
`config`	object	Yes	Trait-specific configuration (varies by type)
`result_type`	string	Yes	`text`, `number`, `boolean`, `timestamp`, or `array`

Trait Types

Aggregation

Computes an aggregate value (count, sum, avg, min, max) across a related model.

{
  "name": "Total Revenue",
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "trait_type": "aggregation",
  "config": {
    "source_model_id": "880e8400-e29b-41d4-a716-446655440000",
    "relationship_id": "990e8400-e29b-41d4-a716-446655440000",
    "aggregation": "sum",
    "column": "order_total"
  },
  "result_type": "number"
}

Occurrence

Detects whether or when an event occurred (first, last, exists).

{
  "name": "Last Purchase Date",
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "trait_type": "occurrence",
  "config": {
    "source_model_id": "880e8400-e29b-41d4-a716-446655440000",
    "relationship_id": "990e8400-e29b-41d4-a716-446655440000",
    "occurrence": "last",
    "column": "order_date"
  },
  "result_type": "timestamp"
}

List

Collects distinct values into an array.

{
  "name": "Product Categories",
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "trait_type": "list",
  "config": {
    "source_model_id": "880e8400-e29b-41d4-a716-446655440000",
    "relationship_id": "990e8400-e29b-41d4-a716-446655440000",
    "column": "category"
  },
  "result_type": "array"
}

SQL

Custom SQL expression evaluated per entity.

{
  "name": "Customer Tier",
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "trait_type": "sql",
  "config": {
    "sql_expression": "CASE WHEN lifetime_value > 10000 THEN 'platinum' WHEN lifetime_value > 1000 THEN 'gold' ELSE 'standard' END"
  },
  "result_type": "text"
}

Formula

Combines other traits using arithmetic or logic.

{
  "name": "Average Order Value",
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "trait_type": "formula",
  "config": {
    "expression": "{total_revenue} / NULLIF({total_purchases}, 0)"
  },
  "result_type": "number"
}

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/traits \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Total Purchases",
    "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
    "trait_type": "aggregation",
    "config": {
      "source_model_id": "880e8400-e29b-41d4-a716-446655440000",
      "relationship_id": "990e8400-e29b-41d4-a716-446655440000",
      "aggregation": "count",
      "column": "order_id"
    },
    "result_type": "number"
  }'

Get Trait

GET /api/v1/workspaces/{id}/traits/{traitId}

Returns a single trait by ID.

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/traits/{traitId} \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Update Trait

PUT /api/v1/workspaces/{id}/traits/{traitId}

Updates an existing trait definition.

Request Body

Same fields as create. Only include fields you want to change.

Example

curl -X PUT https://your-instance.signalsmith.io/api/v1/workspaces/{id}/traits/{traitId} \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Total Purchases (All Time)",
    "description": "Count of all orders per customer"
  }'

Delete Trait

DELETE /api/v1/workspaces/{id}/traits/{traitId}

Deletes a trait. Cannot be deleted if audiences reference it in their filter trees.

Response

{
  "status": "deleted"
}

List Traits by Model

GET /api/v1/workspaces/{id}/models/{modelId}/traits

Returns all traits attached to a specific parent model.

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/models/{modelId}/traits \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Trigger Trait Evaluation

POST /api/v1/workspaces/{id}/traits/{traitId}/trigger

Manually triggers a trait evaluation run. The trait’s computed values are recalculated against the latest source data.

Response

Returns the created trait run object with status 201 Created.

List Trait Runs

GET /api/v1/workspaces/{id}/traits/{traitId}/runs

Returns the evaluation history for a trait.

Trait Object

Field	Type	Description
`id`	string (UUID)	Unique identifier
`workspace_id`	string (UUID)	Owning workspace
`parent_model_id`	string (UUID)	Parent entity model
`name`	string	Display name
`slug`	string	URL-safe identifier
`description`	string	Description
`trait_type`	string	`aggregation`, `occurrence`, `list`, `sql`, or `formula`
`config`	object	Type-specific configuration
`result_type`	string	`text`, `number`, `boolean`, `timestamp`, or `array`
`status`	string	`draft`, `active`, or `error`
`status_error`	string	Error message when status is `error`
`created_by`	string (UUID)	Account that created the trait
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp
`last_computed_at`	string (ISO 8601) or null	Last successful evaluation time

Syncs Audiences