Creates a new company or updates an existing one based on the provided identifiers.
This endpoint is idempotent and will never create duplicates.

How It Works

• If a company exists (based on identifiers), it will be updated
• If no company exists, a new one will be created
• Returns 201 Created for new companies, 200 OK for updated companies

How Identifiers Work

You must provide at least one identifier:

• company_id: Internal Customerly ID (if specified, must exist)
• custom_company_id: Your custom identifier (company_id in your system)

Priority order:

1. company_id (internal ID) - if provided, must exist
2. custom_company_id - if no internal ID, we'll search by this

Conflict Detection

If multiple identifiers are provided, they must either:

• All point to the same company, OR
• Point to no existing company (new company creation), OR
• company_id exists and other identifiers are "free" (will update the company_id company)

If different identifiers point to different companies, the request will fail with a conflict error.

Attributes

• Attributes: Merged incrementally (only specified attributes are created/updated, others remain unchanged)
• You can provide any custom key-value pairs in the attributes object

Response Data

The endpoint returns the complete company object including:

• All company basic information (ID, name, created date, last seen)
• All attributes (both updated and unchanged ones)
• Total number of contacts associated with this company
• HTTP status: 201 Created for new companies, 200 OK for updated companies