Identity resolution

Start identity resolution

Starts the identity-resolution process for the workspace. It identifies and connects related identities to create unified profiles.

The call returns immediately. However, the time needed to complete the identity-resolution process depends on the number of identities in the workspace and on the performance of the workspace's data warehouse.

Request

No parameters.

Response

No response.
POST /v1/identity-resolution/start
curl -X POST https://example.com/v1/identity-resolution/start \
-H "Authorization: Bearer api_xxxxxxx"
Errors
404
workspace does not exist
422
data warehouse is in inspection mode
422
data warehouse is in maintenance mode
422
another operation is already executing

Get latest identity resolution info

Returns information about the latest identity resolution.

Depending on the returned values:

  • If neither startTime nor endTime are returned, it means that no identity resolutions have ever been performed for the workspace.
  • If only startTime is returned, it means that the workspace is currently running an identity resolution.
  • If both startTime and endTime are returned, it means that an identity resolution has been performed and there are no identity resolutions currently running.

Request

No parameters.

Response

  • startTime

    nullable datetime

    Start timestamp (UTC) of the latest identity resolution, either running or completed.

    If null, no identity resolutions have ever been executed for the workspace.

  • endTime

    nullable datetime

    End timestamp (UTC) for the latest identity resolution.

    If null, it means that the identity resolution is still in progress, or that no identity resolution has ever been executed on the workspace.
GET /v1/identity-resolution/latest
curl https://example.com/v1/identity-resolution/latest \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "startTime": "2025-01-12T09:37:22",
  "endTime": "2025-01-12T09:42:51"
}
Errors
404
workspace does not exist

Update identity resolution settings

Request

  • runOnBatchImport

    boolean

    Indicates if identity resolution is automatically run when a batch import is completed. The default is false.

  • identifiers

    nullable array of string

    The identifiers of the identity resolution, ordered from the highest precedence to the lowest precedence.

    An identifier must be a property path that refers to a property of the profile schema of the workspace. The referred property must have type string, int, uuid, ip, or decimal with zero scale. Identifiers cannot be repeated.

    Not specifying any identifier means performing identity resolution without comparing any identifiers.

Response

No response.
PUT /v1/identity-resolution/settings
curl -X PUT https://example.com/v1/identity-resolution/settings \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"runOnBatchImport": true,
"identifiers": [
"customer_id",
"email"
]
}'
Errors
404
workspace does not exist
422
alter schema is in execution so the identifiers cannot be updated
422
identity resolution is in execution so the identifiers cannot be updated
422
property does not exist in the profile schema
422
a property has a type which is not allowed for identifiers

Get identity resolution settings

Request

No parameters.

Response

  • runOnBatchImport

    boolean

    Indicates if identity resolution is automatically run when a batch import is completed. The default is false.

  • identifiers

    array of string

    The identifiers of the identity resolution, ordered from the highest precedence to the lowest precedence.

    If no identifiers are returned, it means that the identity resolution is performed without comparing any identifiers.
GET /v1/identity-resolution/settings
curl https://example.com/v1/identity-resolution/settings \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "runOnBatchImport": true,
  "identifiers": [
    "customer_id",
    "email"
  ]
}
Errors
404
workspace does not exist