> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Endpoint specification for linking contacts to companies

<Warning>
  **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.
</Warning>

## 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.

<Info>
  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.
</Info>

***

## Create Associations

<Card title="Your Implementation Required" icon="triangle-exclamation" color="#f59e0b">
  This endpoint must be implemented on **your server**
</Card>

Enginy calls this endpoint to link contacts to their companies in your CRM.

### Request

```http theme={null}
POST /associations
Content-Type: application/json
X-API-Key: <your-api-key>
```

### Request Body

```json theme={null}
{
  "associations": [
    {
      "contactCRMId": "crm-contact-456",
      "companyCRMId": "crm-company-012"
    },
    {
      "contactCRMId": "crm-contact-457",
      "companyCRMId": "crm-company-012"
    }
  ]
}
```

### Request Fields

| Field                         | Type   | Description                                                          |
| ----------------------------- | ------ | -------------------------------------------------------------------- |
| `associations`                | array  | Array of association objects to create                               |
| `associations[].contactCRMId` | string | **Required.** The CRM ID of the contact (returned from `/contacts`)  |
| `associations[].companyCRMId` | string | **Required.** The CRM ID of the company (returned from `/companies`) |

<Note>Multiple contacts can be associated with the same company in a single request.</Note>

***

### Response

<Tabs>
  <Tab title="Success (200)">
    Return a `200 OK` status to indicate associations were created successfully.

    ```json theme={null}
    {
      "success": true
    }
    ```

    Or with details:

    ```json theme={null}
    {
      "success": true,
      "created": 2
    }
    ```
  </Tab>

  <Tab title="Partial Success (200)">
    If some associations fail but others succeed, you can return details about failures:

    ```json theme={null}
    {
      "success": true,
      "created": 1,
      "errors": [
        {
          "contactCRMId": "crm-contact-457",
          "companyCRMId": "crm-company-012",
          "error": "Contact not found"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Error (4xx/5xx)">
    Return an appropriate error status if the request fails.

    ```json theme={null}
    {
      "error": "Invalid request",
      "message": "Missing required field: associations"
    }
    ```
  </Tab>
</Tabs>

***

## 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

<Tip>We recommend Option 1 for idempotency. This ensures that re-running an export doesn't cause errors.</Tip>

### 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:

```bash theme={null}
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:

```json theme={null}
{
  "success": true
}
```

***

## Export Flow

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

```mermaid theme={null}
sequenceDiagram
    participant G as Enginy
    participant C as Your CRM

    Note over G,C: Step 1: Create Companies
    G->>C: POST /companies
    C-->>G: { results: [{ externalId: "789", crmId: "crm-company-012" }] }

    Note over G,C: Step 2: Create Contacts
    G->>C: POST /contacts
    C-->>G: { results: [{ externalId: "123", crmId: "crm-contact-456" }] }

    Note over G,C: Step 3: Create Associations
    G->>C: POST /associations
    Note right of G: Uses CRM IDs from steps 1 & 2
    C-->>G: { success: true }
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Contacts API" icon="user" href="/api-reference/custom-crm/contacts">
    Review the contacts endpoint
  </Card>

  <Card title="Companies API" icon="building" href="/api-reference/custom-crm/companies">
    Review the companies endpoint
  </Card>

  <Card title="Examples" icon="code" href="/api-reference/custom-crm/examples">
    See complete implementation examples
  </Card>
</CardGroup>