Affinity logo

companyMerges

Operations about company merges

Get All Company Merges

Retrieve paginated company merges for the organization.

Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company 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

Company 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: 100

Number of items to include in the page

Example: limit=100
filter
string

Filter company 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 (CompanyMergeState) <= 100 items

Array of company 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

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

ID of the primary company that other profiles were merged into

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

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

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/company-merges
Request samples 
Response samples 
application/json
Example response showing multiple company merges with different statuses


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


This is an asynchronous process that will merge all data from the duplicate company into the primary company. 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
primaryCompanyId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The ID of the company profile that will be kept after the merge. All data from the duplicate company will be merged into this company.


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


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


default
Errors


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


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


{}
Get Company Merge
Retrieve the status and details of a specific company merge.


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


The mergeId can be obtained from the response of the Get All Company Merges endpoint, or by filtering company merges by task ID using /v2/company-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 ] 
Company 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


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


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


 
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/company-merges/{mergeId}
Request samples 
Response samples 
application/json
Example of a successful company merge


{
  • "id": 12345,
  • "status": "success",
  • "taskId": "1ac19acd-674c-49a0-819a-cd674cc9a042",
  • "startedAt": "2025-06-03T10:30:00Z",
  • "primaryCompanyId": 12345,
  • "duplicateCompanyId": 67890,
  • "completedAt": "2025-06-03T10:32:15Z",
  • "errorMessage": null
}
Get All Company Merge Tasks
Retrieve paginated company merge tasks for the organization.


Returns all merge tasks initiated by users in your organization, including their current status,
the companies 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:  100
Number of items to include in the page


 
 Example:  limit=100
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 (CompanyMergeTask)   <= 100 items 
Array of company 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/company-merges
Request samples 
Response samples 
application/json
Example response showing multiple company merge tasks with different statuses


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


Returns information about the company 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/company-merges?filter=taskId={taskId} See Company
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> 
Company 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/company-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 emails