Skip to main content
Important: This section describes the API endpoint that your system must implement to link contacts to companies. This is not a Enginy API endpoint — it is the interface specification that Enginy will call on your CRM.

​
Overview

After creating contacts and companies, Enginy calls your /associations endpoint to create relationships between them. This allows your CRM to maintain the organizational structure of contacts.
Associations are created after both contacts and companies have been successfully exported. The request uses the CRM IDs returned from the /contacts and /companies endpoints.

​
Create Associations

Your Implementation Required

This endpoint must be implemented on your server
Enginy calls this endpoint to link contacts to their companies in your CRM.

​
Request

POST /associations
Content-Type: application/json
X-API-Key: <your-api-key>

​
Request Body

{
  "associations": [
    {
      "contactCRMId": "crm-contact-456",
      "companyCRMId": "crm-company-012"
    },
    {
      "contactCRMId": "crm-contact-457",
      "companyCRMId": "crm-company-012"
    }
  ]
}

​
Request Fields

FieldTypeDescription
associationsarrayArray of association objects to create
associations[].contactCRMIdstringRequired. The CRM ID of the contact (returned from /contacts)
associations[].companyCRMIdstringRequired. The CRM ID of the company (returned from /companies)
Multiple contacts can be associated with the same company in a single request.

​
Response

Return a 200 OK status to indicate associations were created successfully.
{
  "success": true
}
Or with details:
{
  "success": true,
  "created": 2
}

​
Implementation Notes

​
Handling Existing Associations

Your implementation should handle cases where an association already exists:
  • Option 1 (Recommended): Skip silently if the association already exists
  • Option 2: Return success with a note that the association was already present
  • Option 3: Return an error for that specific association
We recommend Option 1 for idempotency. This ensures that re-running an export doesn’t cause errors.

​
Multiple Companies per Contact

Depending on your CRM’s data model, a contact might be associated with:
  • One company only: Set or replace the company association
  • Multiple companies: Append to existing associations
Enginy will send one association per contact-company relationship.

​
Batch Size

Enginy sends associations in batches of up to 100 associations per request.

​
Testing Your Endpoint

Test your associations endpoint with this curl command: 
curl -X POST https://your-crm.com/associations \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "associations": [
      {
        "contactCRMId": "test-contact-123",
        "companyCRMId": "test-company-456"
      }
    ]
  }'
Expected response: 
{
  "success": true
}

​
Export Flow

Here’s how associations fit into the overall export flow:

​
Next Steps

Contacts API

Review the contacts endpoint

Companies API

Review the companies endpoint

Examples

See complete implementation examples