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

​
Overview

When exporting leads from Enginy, Enginy will call your /contacts endpoint to create contacts in batch. Your endpoint must accept the contacts and return the CRM IDs for each created contact.
Enginy sends all available fields as-is. Your CRM is responsible for mapping fields to your data model.

​
Create Contacts

Your Implementation Required

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

​
Request

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

​
Request Body

{
  "contacts": [
    {
      "externalId": "123",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+1234567890",
      "company": "Acme Inc",
      "title": "CEO",
      "linkedinUrl": "https://linkedin.com/in/johndoe"
      // ... additional fields
    }
  ]
}

​
Request Fields

FieldTypeDescription
contactsarrayArray of contact objects to create
contacts[].externalIdstringRequired. Enginy’s internal lead ID. Use this to map responses back.
contacts[].emailstringProfessional or personal email address
contacts[].firstNamestringContact’s first name
contacts[].lastNamestringContact’s last name
contacts[].phonestringMobile or direct phone number
contacts[].companystringCompany name
contacts[].titlestringJob title
contacts[].linkedinUrlstringLinkedIn profile URL
contacts[].ownerIdstringOwner/assignee ID from your /users endpoint (if users are supported)
Additional fields from the lead record will be included. Your CRM should gracefully handle unknown fields (ignore them or store them as custom fields).
Owner Assignment: If you implement the optional /users endpoint, Enginy will include an ownerId field when the user selects an owner during export. This allows contacts to be assigned to specific CRM users.

​
Common Additional Fields

These fields may be included depending on the lead data in Enginy:
FieldTypeDescription
locationstringContact’s location
leadCountrystringContact’s country
industrystringIndustry
companySizestringCompany size range
domainstringCompany domain
descriptionstringLead description
emailVerificationStatusstringEmail verification status
campaignsstringAssociated campaign names
lastContactedBystringLast identity that contacted this lead
conversationTagsstringTags from conversations
enrichmentsstringSources used for enrichment

​
Response

Return a 201 Created status with the created contact IDs.
{
  "results": [
    {
      "externalId": "123",
      "crmId": "crm-contact-456"
    }
  ]
}
FieldTypeDescription
resultsarrayArray of created contact mappings
results[].externalIdstringThe externalId from the request
results[].crmIdstringRequired. Your CRM’s ID for this contact

​
Batch Size

Enginy sends contacts in batches of up to 100 contacts per request. Your endpoint should be able to handle this batch size efficiently.
If you need to process contacts individually due to CRM limitations, consider implementing internal queuing to avoid timeout issues.

​
Testing Your Endpoint

Test your contacts endpoint with this curl command: 
curl -X POST https://your-crm.com/contacts \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "externalId": "test-123",
        "email": "[email protected]",
        "firstName": "Test",
        "lastName": "User",
        "company": "Test Company"
      }
    ]
  }'
Expected response: 
{
  "results": [
    {
      "externalId": "test-123",
      "crmId": "your-crm-id-here"
    }
  ]
}

​
Next Steps

Companies API

Implement the companies endpoint

Associations API

Link contacts to companies

Examples

See complete implementation examples