Skip to main content
PUT
Attach Contact Company

Overview

This endpoint attaches a contact to a company. A contact belongs to at most one company per Space, so attaching it to a new company moves it off any company it currently belongs to. In the same transaction, the contact’s conversions, touchpoints, and visit metadata are re-stamped with the new company id, so company-level reports and the Companies dataset company_id columns in the data warehouse follow immediately — nothing is left pointing at the old company. This call is idempotent: repeating it with the contact’s current company id re-stamps the same rows again, which is useful for repairing rows that drifted out of sync rather than a no-op.

Path Parameters

integer
required
The unique identifier of the contact to attach. Merged profile aliases are automatically resolved to the current canonical contact — the response’s id is the surviving contact.

Request Body

integer
required
The unique identifier of the company to attach the contact to. Must belong to a company in the same Space as the contact.

Response

Success Response

integer
The unique identifier of the contact (after resolving merged-profile aliases).
integer
The id of the company the contact is now attached to — echoes the company_id sent in the request.

Error Response

string
Error description explaining what went wrong.

Example Requests

Status Codes

Notes

  • Rate Limit: This endpoint has a limit of 60 requests per minute per Space. See Rate Limiting for details, the same bucket as Update Contact.
  • One company per contact: attaching a contact to a new company removes it from any company it previously belonged to — a contact is never attached to more than one company at a time.
  • Rows are re-stamped, not just the pivot: the contact’s conversions, touchpoints, and visit metadata are updated to the new company_id in the same transaction, so company-level reports and the data warehouse Companies dataset join correctly right away.
  • Idempotent repair: calling this again with the contact’s current company id is not a no-op — it re-stamps the contact’s rows, which repairs any that had drifted out of sync.
  • Merged profiles: If you pass an ID that was merged into another profile, the attach is applied to the canonical (current) profile, and the response’s id is that canonical id.
  • company_id must be in the same Space: attaching to a company from a different Space returns 404.
  • Behavior after a manual attach depends on company identity mode: in the default Auto mode, the tracker only assigns a company to a contact that currently has none, so a manual attach sticks until the contact is manually detached — it is not undone by a later event. In External ID mode, the next event carrying a different company_external_id re-points the contact again.