Affinity logo

personMerges

Operations about person merges

Get All Person Merges

Retrieve paginated person merges for the organization.

Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the filter query parameter. The filter parameter is a string that you can specify conditions based on the following properties:

Property Type Operators Values Examples
status enum = in-progress, success, failed status=failed
taskId string = taskId=789e0123-e45b-67c8-d901-234567890123

Person merges are returned in reverse chronological order (most recent first).

Requires the "Manage duplicates" permission and organization admin role.

SecuritybearerAuth
Request
query Parameters
cursor
string

Cursor for the next or previous page

Example: cursor=ICAgICAgYmVmb3JlOjo6Nw
limit
integer <int32> [ 1 .. 100 ]
Default: 25

Number of items to include in the page

Example: limit=25
filter
string

Filter person merges using Affinity Filtering Language

Example: filter=status=failed | taskId=789e0123-e45b-67c8-d901-234567890123
Responses
200

OK

Response Headers
X-Ratelimit-Limit-User
integer

Number of requests allowed per minute for the user

X-Ratelimit-Limit-User-Remaining
integer

Number of requests remaining for the user

X-Ratelimit-Limit-User-Reset
integer

Time in seconds before the limit resets for the user

X-Ratelimit-Limit-Org
integer

Number of requests allowed per month for the account

X-Ratelimit-Limit-Org-Remaining
integer

Number of requests remaining for the account

X-Ratelimit-Limit-Org-Reset
integer

Time in seconds before the limit resets for the account

Response Schema: application/json
required
Array of objects (PersonMergeState) <= 100 items

Array of person merge states

Array (<= 100 items)
id
required
integer <int64> [ 1 .. 9007199254740991 ]

The unique identifier for the merge

status
required
string

Current status of the merge

Enum: "in-progress" "success" "failed"
taskId
required
string <uuid>

Identifier for the task this merge belongs to

startedAt
required
string <date-time>

Timestamp when the merge started

primaryPersonId
required
integer <int64> [ 1 .. 9007199254740991 ]

ID of the primary person that other profiles were merged into

duplicatePersonId
required
integer <int64> [ 1 .. 9007199254740991 ]

ID of the duplicate person that was merged into the primary person

completedAt
required
string or null <date-time>

Timestamp when the merge completed (success or failure)

errorMessage
required
string or null

Error message if the merge failed

required
object (Pagination)
prevUrl
string or null <uri>

URL for the previous page

nextUrl
string or null <uri>

URL for the next page

400

Bad Request

403

Forbidden

default

Errors

get/v2/person-merges
Request samples 
Response samples 
application/json
Example response showing multiple person merges with different statuses


{
  • "data": [
    ],
  • "pagination": {}
}
Initiate Person Merge
Initiate a person merge to combine a duplicate person profile into a primary person profile.


This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned task URL.


Requires the "Manage duplicates" permission and organization admin role.


SecuritybearerAuth 
Request 
Request Body schema: application/json
required
primaryPersonId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The ID of the person profile that will be kept after the merge. All data from the duplicate person will be merged into this person.


 
duplicatePersonId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The ID of the person profile that will be merged and then deleted. All data from this person will be transferred to the primary person.


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


default
Errors


post/v2/person-merges
Request samples 
application/json
Example request to merge a duplicate person profile into a primary person profile. The primary person (ID 12345) will be kept and all data from the duplicate person (ID 67890) will be merged into it.


{
  • "primaryPersonId": 12345,
  • "duplicatePersonId": 67890
}
Response samples 
application/json
Response when a person merge task has been accepted for processing. The task ID can be used to track the progress of the merge task.


{}
Get Person Merge
Retrieve the status and details of a specific person merge.


Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed.


The mergeId can be obtained from the response of the Get All Person Merges endpoint, or by filtering person merges by task ID using /v2/person-merges?filter=taskId={taskId} after initiating a merge.


Requires the "Manage duplicates" permission and organization admin role.


SecuritybearerAuth 
Request 
path Parameters
mergeId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
Person merge ID


 
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
id
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The unique identifier for the merge


 
status
required
string
Current status of the merge


 Enum: "in-progress" "success" "failed"  
taskId
required
string <uuid> 
Identifier for the task this merge belongs to


 
startedAt
required
string <date-time> 
Timestamp when the merge started


 
primaryPersonId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
ID of the primary person that other profiles were merged into


 
duplicatePersonId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
ID of the duplicate person that was merged into the primary person


 
completedAt
required
string or null <date-time> 
Timestamp when the merge completed (success or failure)


 
errorMessage
required
string or null
Error message if the merge failed


 
400
Bad Request


403
Forbidden


404
Not Found


default
Errors


get/v2/person-merges/{mergeId}
Request samples 
Response samples 
application/json
Example of a successful person merge


{
  • "id": 12345,
  • "status": "success",
  • "taskId": "1b9684ad-e954-46d7-9684-ade95436d7dd",
  • "startedAt": "2025-06-03T10:30:00Z",
  • "primaryPersonId": 12345,
  • "duplicatePersonId": 67890,
  • "completedAt": "2025-06-03T10:32:15Z",
  • "errorMessage": null
}
Get All Person Merge Tasks
Retrieve paginated person merge tasks for the organization.


Returns all merge tasks initiated by users in your organization, including their current status,
the persons involved, and task details.


You can filter tasks using the filter query parameter. The filter parameter is a string that you can specify conditions based on the following properties:






Property
Type
Operators
Values
Examples





status
enum
=
in-progress, success, failed
status=failed





Tasks are returned in reverse chronological order (most recent first).


Requires the "Manage duplicates" permission and
organization admin role.


SecuritybearerAuth 
Request 
query Parameters
cursor
string
Cursor for the next or previous page


 
 Example:  cursor=ICAgICAgYmVmb3JlOjo6Nw
limit
integer <int32>   [ 1 .. 100 ] 
 Default:  25
Number of items to include in the page


 
 Example:  limit=25
filter
string
Filter tasks using Affinity Filtering Language


 
 Example:  filter=status=failed
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
required
Array of objects (PersonMergeTask)   <= 100 items 
Array of person merge tasks


 
 Array (<= 100 items)
id
required
string <uuid> 
The unique identifier for this merge task


 
status
required
string
The current status of the batch operation


 Enum: "in-progress" "success" "failed"  
required
object
Summary of merges in this batch task


 
required
object (Pagination) 
 
prevUrl
string or null <uri> 
URL for the previous page


 
nextUrl
string or null <uri> 
URL for the next page


 
400
Bad Request


403
Forbidden


default
Errors


get/v2/tasks/person-merges
Request samples 
Response samples 
application/json
Example response showing multiple person merge tasks with different statuses


{}
Get Person Merge Task
Retrieve the status and details of a specific task for person merges.


Returns information about the person merges for a specific task including its overall status,
number of merges in-progress, completed, and failed.


Detailed information about individual merges for this task can be found by querying:
/v2/person-merges?filter=taskId={taskId} See Person
Merges for more details.


Task statuses:


    

  • in-progress: The merge task is currently being processed.
    • 

  • success: The merge task completed successfully.
    • 

  • failed: The merge task failed.
    • 



Requires the "Manage duplicates" permission and
organization admin role.


SecuritybearerAuth 
Request 
path Parameters
taskId
required
string <uuid> 
Person merge task ID


 
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
id
required
string <uuid> 
The unique identifier for this merge task


 
status
required
string
The current status of the batch operation


 Enum: "in-progress" "success" "failed"  
required
object
Summary of merges in this batch task


 
total
required
integer <int32>   [ 0 .. 2147483647 ] 
Total number of merges in the batch


 
inProgress
required
integer <int32>   [ 0 .. 2147483647 ] 
Number of merges currently in progress


 
success
required
integer <int32>   [ 0 .. 2147483647 ] 
Number of successfully completed merges


 
failed
required
integer <int32>   [ 0 .. 2147483647 ] 
Number of failed merges


 
400
Bad Request


403
Forbidden


404
Not Found


default
Errors


get/v2/tasks/person-merges/{taskId}
Request samples 
Response samples 
application/json
Example response showing a merge task that is currently being processed.


{
  • "id": "456e7890-e12b-34c5-d678-901234567890",
  • "status": "in-progress",
  • "resultsSummary": {
    }
}
➔ Next to persons