HubSpot: setting or removing a company's parent

In HubSpot, companies can be organised in a parent/child hierarchy, for example a group company with several subsidiaries. With the CRM API you can set, change and remove a company's parent through the parent_id field.

Send the parent company's ID in parent_id, either when you create the company or when you update it:

POST /crm/companies
{
  "name": "Acme Benelux",
  "parent_id": "12345678901"
}

PATCH /crm/companies/{id}
{
  "parent_id": "12345678901"
}

• The parent must exist. If parent_id points to a company that doesn't exist when you create a company, the whole request is rejected and no company is created. You won't get a company back with the parent silently dropped.

• No loops. A company can't become its own ancestor, at any level. HubSpot rejects a parent_id that would create a loop.

• The new parent appears after a few seconds. Reading a company straight after you set its parent can briefly return the old value, or null. Re-read the company after a few seconds if you need to confirm the change.

• Don't send a stale value back. In an update, a parent_id you include is applied. If you read a company too soon after changing its parent and send that read straight back in a full update, you can undo your own change. Only include parent_id in an update when you intend to change it.

• A failed update may still have changed the parent. The parent is applied before the rest of the update. If an update that includes parent_id fails because of another field, check the company before retrying.

• Hubspot: Why are some properties missing in API Responses?