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

# Sync contacts

> Find existing contacts in your CRM and return their IDs

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

Enginy calls this endpoint to find which contacts already exist in your CRM. Your CRM decides the matching logic (by email, LinkedIn URL, phone, etc.).

## Request

<ParamField body="contacts" type="array" required>
  Array of contact objects to find
</ParamField>

### Contact Object

<ParamField body="externalId" type="string" required>
  Enginy's internal lead ID
</ParamField>

<ParamField body="email" type="string">
  Email address for matching
</ParamField>

<ParamField body="linkedinUrl" type="string">
  LinkedIn URL for matching
</ParamField>

<RequestExample>
  ```json theme={null}
  {
    "contacts": [
      {
        "externalId": "lead-123",
        "email": "sarah.chen@techstartup.io",
        "firstName": "Sarah",
        "lastName": "Chen",
        "linkedinUrl": "https://linkedin.com/in/sarahchen"
      },
      {
        "externalId": "lead-456",
        "email": "new.prospect@unknown.com"
      }
    ]
  }
  ```
</RequestExample>

## Response

Return **only contacts that exist** in your CRM.

<ResponseField name="results" type="array" required>
  Array of matched contacts
</ResponseField>

<ResponseField name="results[].externalId" type="string" required>
  The `externalId` from the request
</ResponseField>

<ResponseField name="results[].crmId" type="string" required>
  Your CRM's ID for this contact
</ResponseField>

<ResponseField name="results[].properties" type="object">
  Optional properties to sync back to Enginy (leadScore, lifecycleStage, etc.)
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "results": [
      {
        "externalId": "lead-123",
        "crmId": "contact_8f3k2j",
        "properties": {
          "leadScore": 85,
          "lifecycleStage": "MQL",
          "lastActivityDate": "2024-01-15T14:30:00Z"
        }
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  Contact `lead-456` is not in the response because it doesn't exist in the CRM. Only return matches.
</Note>