Overview

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.

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": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+1234567890",
      "company": "Acme Inc",
      "title": "CEO",
      "linkedinUrl": "https://linkedin.com/in/johndoe"
      // ... additional fields
    }
  ]
}

Request Fields

Field	Type	Description
`contacts`	array	Array of contact objects to create
`contacts[].externalId`	string	Required. Enginy’s internal lead ID. Use this to map responses back.
`contacts[].email`	string	Professional or personal email address
`contacts[].firstName`	string	Contact’s first name
`contacts[].lastName`	string	Contact’s last name
`contacts[].phone`	string	Mobile or direct phone number
`contacts[].company`	string	Company name
`contacts[].title`	string	Job title
`contacts[].linkedinUrl`	string	LinkedIn profile URL
`contacts[].ownerId`	string	Owner/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:

Field	Type	Description
`location`	string	Contact’s location
`leadCountry`	string	Contact’s country
`industry`	string	Industry
`companySize`	string	Company size range
`domain`	string	Company domain
`description`	string	Lead description
`emailVerificationStatus`	string	Email verification status
`campaigns`	string	Associated campaign names
`lastContactedBy`	string	Last identity that contacted this lead
`conversationTags`	string	Tags from conversations
`enrichments`	string	Sources used for enrichment

Response

Success (201)
Partial Success (201)
Error (4xx/5xx)

Return a 201 Created status with the created contact IDs.

{
  "results": [
    {
      "externalId": "123",
      "crmId": "crm-contact-456"
    }
  ]
}

Field	Type	Description
`results`	array	Array of created contact mappings
`results[].externalId`	string	The `externalId` from the request
`results[].crmId`	string	Required. Your CRM’s ID for this contact

If some contacts fail, return success for those that worked. Enginy will mark failed contacts as errors.

{
  "results": [
    {
      "externalId": "123",
      "crmId": "crm-contact-456"
    }
  ],
  "errors": [
    {
      "externalId": "124",
      "error": "Duplicate email address"
    }
  ]
}

Return an appropriate error status if the entire batch fails.

{
  "error": "Invalid request",
  "message": "Missing required field: contacts"
}

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": "test@example.com",
        "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

Getting Started

Contacts

Companies

Associations

Tasks

Activities

Users (Optional)

Examples

Overview

Overview

Create Contacts

Your Implementation Required

Request

Request Body

Request Fields

Common Additional Fields

Response

Batch Size

Testing Your Endpoint

Next Steps

Companies API

Associations API

Examples

​Overview

​Create Contacts

Your Implementation Required

​Request

​Request Body

​Request Fields

​Common Additional Fields

​Response

​Batch Size

​Testing Your Endpoint

​Next Steps

Companies API

Associations API

Examples

Overview

Create Contacts

Request

Request Body

Request Fields

Common Additional Fields

Response

Batch Size

Testing Your Endpoint

Next Steps