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: []