Identity Graphs API

Identity graphs unify customer profiles across data sources by matching records on shared identifiers (email, phone, customer ID, etc.). Once resolved, identity graphs power cross-model audience segmentation and provide a unified view of each customer.

Endpoints

List Identity Graphs

GET /api/v1/workspaces/{id}/identity-graphs

Returns all identity graphs in the workspace.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "Customer Identity Graph",
    "description": "Unified view of customers across CRM, web, and transactional data",
    "status": "active",
    "status_error": "",
    "created_by": "770e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Example

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

Create Identity Graph

POST /api/v1/workspaces/{id}/identity-graphs

Creates a new identity graph.

Request Body

{
  "name": "Customer Identity Graph",
  "description": "Unified view of customers across all data sources"
}

Response

Returns the created identity graph with status 201 Created.

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/identity-graphs \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Identity Graph",
    "description": "Unified customer profiles"
  }'

Get Identity Graph

GET /api/v1/workspaces/{id}/identity-graphs/{graphId}

Returns a single identity graph by ID.

Update Identity Graph

PUT /api/v1/workspaces/{id}/identity-graphs/{graphId}

Updates an existing identity graph.

Delete Identity Graph

DELETE /api/v1/workspaces/{id}/identity-graphs/{graphId}

Deletes an identity graph. Cannot be deleted if audiences reference it.

Response

{
  "status": "deleted"
}

Model Management

Models are the data sources that feed into the identity graph. Each model contributes identifier columns for matching.

List Graph Models

GET /api/v1/workspaces/{id}/identity-graphs/{graphId}/models

Returns all models associated with the identity graph.

Add Model

POST /api/v1/workspaces/{id}/identity-graphs/{graphId}/models

Adds a model to the identity graph.

Request Body

Remove Model

DELETE /api/v1/workspaces/{id}/identity-graphs/{graphId}/models/{igModelId}

Removes a model from the identity graph.

Identifiers

Identifiers define which columns from each model are used for matching records. An identifier has a type (email, phone, customer_id, etc.) and a priority that determines which value takes precedence during resolution.

List Identifiers

GET /api/v1/workspaces/{id}/identity-graphs/{graphId}/identifiers

Returns all identifiers configured for the graph.

Upsert Identifiers

PUT /api/v1/workspaces/{id}/identity-graphs/{graphId}/identifiers

Creates or updates the identifier configuration. This is a full replacement — send the complete set of identifiers.

Request Body

{
  "identifiers": [
    {
      "ig_model_id": "550e8400-e29b-41d4-a716-446655440000",
      "column_name": "email",
      "identifier_type": "email",
      "priority": 1
    },
    {
      "ig_model_id": "550e8400-e29b-41d4-a716-446655440000",
      "column_name": "phone",
      "identifier_type": "phone",
      "priority": 2
    }
  ]
}

Merge Rules

Merge rules define how conflicting attribute values are resolved when multiple records are merged into a single profile.

List Merge Rules

GET /api/v1/workspaces/{id}/identity-graphs/{graphId}/merge-rules

Upsert Merge Rules

PUT /api/v1/workspaces/{id}/identity-graphs/{graphId}/merge-rules

Request Body

{
  "rules": [
    {
      "identifier_type": "email",
      "match_type": "exact",
      "case_sensitive": false
    }
  ]
}

Limit Rules

Limit rules prevent identity graph explosion by capping the number of identifiers per profile or the cluster size.

List Limit Rules

GET /api/v1/workspaces/{id}/identity-graphs/{graphId}/limit-rules

Upsert Limit Rules

PUT /api/v1/workspaces/{id}/identity-graphs/{graphId}/limit-rules

Request Body

{
  "rules": [
    {
      "identifier_type": "email",
      "max_per_profile": 10
    },
    {
      "identifier_type": "phone",
      "max_per_profile": 5
    }
  ]
}

Resolution Runs

Trigger Run

POST /api/v1/workspaces/{id}/identity-graphs/{graphId}/trigger

Triggers an identity resolution run.

Request Body

Response

Returns the created run object with status 201 Created.

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/identity-graphs/{graphId}/trigger \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{"run_type": "full"}'

List Runs

GET /api/v1/workspaces/{id}/identity-graphs/{graphId}/runs

Returns the resolution run history.

Get Run

GET /api/v1/workspaces/{id}/identity-graphs/{graphId}/runs/{runId}

Returns details of a specific resolution run.

Cancel Run

POST /api/v1/workspaces/{id}/identity-graphs/{graphId}/runs/{runId}/cancel

Cancels a running resolution process.

Response

{
  "status": "cancelled"
}

Identity Graph Object