Identity graph runs, reprocessing queues and run statistics.
openapi: 3.0.0
info:
title: Hightouch Identity Resolution API
description: Hightouch Public Rest API to access syncs, models, sources and destinations
version: 1.0.0
contact:
name: Hightouch
url: https://hightouch.com
x-harvested-from: https://api.hightouch.io/api/swagger.json
x-harvested-on: '2026-08-13'
x-source-document: openapi/_original/hightouch-api-openapi.json
servers:
- url: https://api.hightouch.com/api/v1
tags:
- name: Identity Resolution
paths:
/idr/{graphId}/trigger:
post:
operationId: TriggerIdrRun
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunIdrOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: Trigger a new IDR run for a graph
summary: Trigger IDR run
security:
- bearerAuth: []
parameters:
- in: path
name: graphId
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunIdrInput'
tags:
- Identity Resolution
/idr/{graphId}/runs:
get:
operationId: ListIdrRuns
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/ListIdrRunsOutput'
examples:
Example 1:
value:
data:
- id: 715eba82-2097-4c1b-91c0-ae7c279c763a
graphId: e9037b3e-2401-48f9-85eb-8c6e75e3a813
status: SUCCESS
createdAt: '2025-06-01T00:00:00.000Z'
startedAt: '2025-06-01T00:00:01.000Z'
finishedAt: '2025-06-01T00:00:02.000Z'
fullRerun: false
stats:
deterministic:
numUniqueProfiles: 100
numNewUniqueProfiles: 50
numSourceRows: 1000
hasMore: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List runs for a given IDR graph
summary: List IDR runs
security:
- bearerAuth: []
parameters:
- description: Required. ID of the graph to list runs for.
in: path
name: graphId
required: true
schema:
type: string
- description: Run ID to query for.
in: query
name: runId
required: false
schema:
type: string
- description: Select runs that started on or after this ISO timestamp.
in: query
name: after
required: false
schema:
format: date-time
type: string
- description: Select runs that started on or before this ISO timestamp.
in: query
name: before
required: false
schema:
format: date-time
type: string
- description: Maximum number of runs to return.
in: query
name: limit
required: false
schema:
default: 20
format: double
type: number
- description: Offset to start at for pagination.
in: query
name: offset
required: false
schema:
default: 0
format: double
type: number
- description: Field to sort by.
in: query
name: orderBy
required: false
schema:
default: created_at
type: string
enum:
- created_at
- started_at
- finished_at
tags:
- Identity Resolution
/idr/{graphId}/queue-for-reprocessing:
post:
operationId: QueueForReprocessing
responses:
'200':
description: ID associated with the reprocessing request. This can be used to query the status
of the request.
content:
application/json:
schema:
$ref: '#/components/schemas/IdrQueueForReprocessingOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'Trigger an async job to queue identifier values for reprocessing, optionally adding
them to the blocklist.
If `block` is true (the default), identifier values will be added to the blocklist and ignored
in future runs.
Clusters containing these identifier values will be queued for reprocessing.'
summary: Queue identifier values for reprocessing
security:
- bearerAuth: []
parameters:
- description: Required. ID of the graph containing the identifiers.
in: path
name: graphId
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/IdrQueueForReprocessingInput'
example:
identifiers:
- identifier: email
value: a@b.com
- identifier: phone
value: '1234567890'
block: true
tags:
- Identity Resolution
/idr/{graphId}/reprocess-status/{requestId}:
get:
operationId: ReprocessStatus
responses:
'200':
description: The status of the reprocessing request.
content:
application/json:
schema:
$ref: '#/components/schemas/IdrReprocessStatusOutput'
examples:
queueing:
value:
status: queueing
queuedAt: null
reprocessedAt: null
reprocessedRunId: null
error: null
queued:
value:
status: queued
queuedAt: '2025-10-07T01:23:45.678Z'
reprocessedAt: null
reprocessedRunId: null
error: null
reprocessed:
value:
status: reprocessed
queuedAt: '2025-10-07T01:23:45.678Z'
reprocessedAt: '2025-10-07T01:23:45.678Z'
reprocessedRunId: 123e4567-e89b-12d3-a456-426614174000
error: null
failed:
value:
status: failed
queuedAt: null
reprocessedAt: null
reprocessedRunId: null
error: Failed to write identifiers to data warehouse
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: Get the status of a reprocessing request
security:
- bearerAuth: []
parameters:
- description: Required. ID of the graph for the reprocessing request.
in: path
name: graphId
required: true
schema:
type: string
- description: Required. ID of the reprocessing request.
in: path
name: requestId
required: true
schema:
type: string
tags:
- Identity Resolution
/id_graphs/{graphId}/trigger:
post:
operationId: TriggerRunIdGraph
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunIdrOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'DEPRECATED: use `/idr/{graphId}/trigger` instead'
deprecated: true
security:
- bearerAuth: []
parameters:
- in: path
name: graphId
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunIdrInput'
tags:
- Identity Resolution
components:
schemas:
IdrQueueForReprocessingInput:
properties:
identifiers:
items:
properties:
value:
type: string
identifier:
type: string
required:
- value
- identifier
type: object
type: array
description: 'e.g. [{ identifier: "email", value: "a@b.com" }]
Identifier values will be queued for reprocessing.
Clusters containing these identifiers will be reprocessed on the next run.'
block:
type: boolean
description: If true, identifier values will also be added to the blocklist and ignored in future
runs.
default: 'true'
required:
- identifiers
type: object
additionalProperties: false
IdrQueueForReprocessingOutput:
properties:
requestId:
type: string
description: ID associated with the reprocessing request. This can be used to query the status
of the request.
required:
- requestId
type: object
additionalProperties: false
IdrReprocessStatusOutput:
properties:
status:
type: string
enum:
- queueing
- queued
- reprocessed
- failed
- cancelled
description: '"queueing": The identifiers are being queued for reprocessing.
"queued": The identifiers have been queued and added to the blocklist. Their associated clusters
will be reprocessed next time the graph runs.
"reprocessed": The identifiers'' clusters have been reprocessed during a run.
"failed": We failed to queue the identifiers for reprocessing.
"cancelled": The reprocessing request has been cancelled.'
queuedAt:
type: string
format: date-time
nullable: true
description: Set if the status is "queued" or "reprocessed". The timestamp when the identifiers
were queued for reprocessing.
reprocessedAt:
type: string
format: date-time
nullable: true
description: Set if the status is "reprocessed". The timestamp when the identifiers' clusters
were reprocessed.
reprocessedRunId:
type: string
nullable: true
description: Set if the status is "reprocessed". The ID of the run that reprocessed the identifiers'
clusters.
error:
type: string
nullable: true
description: If available, the error message from failing to queue the identifiers for reprocessing.
required:
- status
- queuedAt
- reprocessedAt
- reprocessedRunId
- error
type: object
additionalProperties: false
IdrRun:
properties:
fullRerun:
type: boolean
stats:
$ref: '#/components/schemas/IdrRunStatsByThreshold'
description: If available, the stats at the end of a successful run.
finishedAt:
type: string
format: date-time
description: Timestamp of the run's completion. Only set for successful or failed runs.
startedAt:
type: string
format: date-time
description: Timestamp of the run's start. Not set for queued runs.
createdAt:
type: string
format: date-time
error:
type: string
description: If available, the error associated with a failed status.
status:
type: string
enum:
- QUEUED
- PROCESSING
- SUCCESS
- FAILURE
- CANCELLED
graphId:
type: string
id:
type: string
required:
- fullRerun
- createdAt
- status
- graphId
- id
type: object
IdrRunStats:
properties:
numSourceRows:
type: number
format: double
description: The exact number of rows processed from sources in this run.
numNewUniqueProfiles:
type: number
format: double
description: The exact number of unique profiles in the graph created during this run.
numUniqueProfiles:
type: number
format: double
description: The exact number of unique profiles in the graph at the end of the run.
required:
- numSourceRows
- numNewUniqueProfiles
- numUniqueProfiles
type: object
IdrRunStatsByThreshold:
properties:
probabilistic-loose:
$ref: '#/components/schemas/IdrRunStats'
probabilistic-strict:
$ref: '#/components/schemas/IdrRunStats'
deterministic:
$ref: '#/components/schemas/IdrRunStats'
additionalProperties:
$ref: '#/components/schemas/IdrRunStats'
type: object
ListIdrRunsOutput:
description: The output of a request to list runs for an IDR graph.
properties:
data:
items:
$ref: '#/components/schemas/IdrRun'
type: array
hasMore:
type: boolean
required:
- data
- hasMore
type: object
additionalProperties: false
TriggerRunIdrInput:
properties:
fullRerun:
type: boolean
description: Whether to resync the entire Identity Graph or process incrementally.
default: 'false'
type: object
description: The input of a trigger action to run IDR.
TriggerRunIdrOutput:
properties:
id:
type: string
description: The id of the triggered run.
required:
- id
type: object
additionalProperties: false
ValidateErrorJSON:
properties:
message:
type: string
enum:
- Validation failed
nullable: false
details:
properties: {}
additionalProperties: {}
type: object
required:
- message
- details
type: object
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Bearer
security:
- bearerAuth: []