Overview - Enginy API Docs

Important: This section describes the API endpoints that your system must implement to integrate with Enginy. These are not Enginy API endpoints — they are the interface specification that Enginy will call on your CRM.

Introduction

To integrate your custom CRM with Enginy, your system must expose a set of HTTP endpoints that Enginy will call. This documentation covers the exact specification your API must follow.

All endpoints must be accessible via HTTPS and accept the API key header you configured during connection setup.

Required Endpoints

Your Custom CRM integration supports three main use cases:

Data Export & Sync

Export contacts and companies from Enginy to your CRM, and sync data bidirectionally.

Endpoint	Method	Purpose
`/health`	GET	Connection validation
`/contacts`	POST	Batch create contacts
`/contacts/sync`	POST	Find existing contacts, return CRM IDs and properties
`/contacts`	PUT	Update contacts (including engagement fields)
`/companies`	POST	Batch create companies
`/companies/sync`	POST	Find existing companies, return CRM IDs and properties
`/companies`	PUT	Update companies (including engagement fields)
`/associations`	POST	Link contacts to companies

Campaign Activity Logging

Log all conversation activity (messages, emails, connection requests) from campaigns.

Endpoint	Method	Purpose
`/activities`	POST	Create activity record (LinkedIn message, email, etc.)

Activity Types:

EMAIL - Email messages sent/received
LINKEDIN - LinkedIn messages sent/received
LINKEDIN_INMAIL - LinkedIn InMail sent/received
LINKEDIN_CONNECTION - Connection requests sent/accepted

Task Management

Create and manage tasks triggered by campaign sequences.

Endpoint	Method	Purpose
`/tasks`	POST	Create a task
`/tasks/:id`	GET	Get a task
`/tasks/:id`	PATCH	Update/complete a task
`/tasks/batch`	POST	Get multiple tasks
`/tasks/batch`	PATCH	Complete multiple tasks

Users/Owners (Optional)

Provide a list of users for owner assignment in exports, tasks, and activities.

Endpoint	Method	Purpose
`/users`	GET	List users/owners for assignment

Optional: If not implemented (returns 404/501/405), owner selection is disabled in the UI.

Quick Reference Cards

Contacts

Create, sync, and update contacts

Companies

Create, sync, and update companies

Associations

Link contacts to companies

Activities

Log LinkedIn and email activity

Tasks

Create and manage campaign tasks

Users

List users for owner assignment (optional)

Examples

Complete implementation examples

Activities API

Log LinkedIn and email activities

Authentication

Your API must validate the API key sent in the header you specified during setup (default: X-API-Key).

# Enginy will send requests like this:
POST /contacts HTTP/1.1
Host: your-api.com
X-API-Key: your-configured-secret
Content-Type: application/json
Accept: application/json

Return 401 Unauthorized if the API key is invalid or missing.

Health Endpoint

Your Implementation Required

This endpoint must be implemented on your server

Enginy calls this endpoint to validate the connection during setup and periodic health checks.

GET /health

Return any 2xx status code to indicate your API is healthy:

{
  "status": "ok"
}

Complete Endpoint Reference

Data Export & Sync

Endpoint	Method	Purpose	Details
`/health`	GET	Connection validation	Return 200 if healthy
`/contacts`	POST	Batch create contacts	View docs
`/contacts/sync`	POST	Sync contacts (find existing)	View docs
`/contacts`	PUT	Update contacts	View docs
`/companies`	POST	Batch create companies	View docs
`/companies/sync`	POST	Sync companies (find existing)	View docs
`/companies`	PUT	Update companies	View docs
`/associations`	POST	Link contacts to companies	View docs

Campaign Activity

Endpoint	Method	Purpose	Details
`/activities`	POST	Create activity record	View docs

Tasks

Endpoint	Method	Purpose	Details
`/tasks`	POST	Create a task	View docs
`/tasks/:id`	GET	Get a task	View docs
`/tasks/:id`	PATCH	Update a task	View docs
`/tasks/batch`	POST	Get tasks in batch	View docs
`/tasks/batch`	PATCH	Complete tasks in batch	View docs

Users (Optional)

Endpoint	Method	Purpose	Details
`/users`	GET	List users/owners	View docs

The Users endpoint is optional. If not implemented, return 404, 501, or 405 to gracefully disable owner selection in the UI.

Data Flows

Export Flow

When exporting data from Enginy to your CRM, sync endpoints are always called first to identify existing records. Based on the sync results, Enginy will either create new records or update existing ones:

New records: If a contact/company is not found during sync (no crmId returned), it will be created via POST /contacts or POST /companies
Existing records: If a contact/company already exists in your CRM (a crmId is returned from sync), it will be updated via PUT /contacts or PUT /companies

Important: The /contacts/sync and /companies/sync endpoints are required. Enginy always calls them first to determine which records already exist in your CRM, then routes each record to either an update (PUT) or create (POST) operation accordingly.

Sync Endpoint Behavior

The sync endpoints (POST /contacts/sync and POST /companies/sync) allow Enginy to:

Find existing records - Your CRM matches by email, LinkedIn URL, domain, etc.
Return CRM IDs - So Enginy can link records for future updates
Sync properties back - Optionally return data to update in Enginy

Key Principle: All matching logic lives in YOUR CRM. You decide how to identify existing records and what properties to sync back.

Minimal Implementation: If you don’t need matching logic, your sync endpoints can return an empty array { results: [] }. This will treat all records as new and proceed to create them.

Campaign Activity Flow

When a campaign sends messages or receives replies:

Engagement Field Updates

When contacts engage with campaigns (reply, click, connect), Enginy updates your CRM via PUT /contacts with fields like:

Field	Example Value	Description
`campaignEngagementStatus`	`Message Replied (2/3) - LINKEDIN`	Current engagement status
`campaignSequenceStatus`	`Ongoing`	`Not Started`, `Ongoing`, `Finished`, `Replied`
`campaignOpens`	`5`	Number of email opens
`campaignClicks`	`2`	Number of link clicks
`activities`	`Connection Request Sent, Message Sent`	Activity log

Field names are user-configurable in Enginy. Your CRM should accept any field name and store it appropriately.

Engagement field updates are sent through PUT /contacts and PUT /companies using the mappings you configure in Enginy (e.g., last engaged date).

CRM Record Links (Optional)

Enginy can generate clickable links to open records in your CRM:

Configuration	Example
`contactLinkTemplate`	`https://mycrm.com/contacts/{{crmId}}`
`companyLinkTemplate`	`https://mycrm.com/companies/{{crmId}}`

Error Handling

Return appropriate HTTP status codes:

Status Code	When to Use
`200` / `201`	Success
`400`	Invalid request
`401`	Invalid API key
`404`	Resource not found
`500`	Server error

Reference Implementation

GitHub Repository

Clone our complete working example: Node.js/Express server with SQLite, including all endpoints and a web dashboard for viewing data.

​Introduction

​Required Endpoints

​Quick Reference Cards

Contacts

Companies

Associations

Activities

Tasks

Users

Examples

Activities API

​Authentication

​Health Endpoint

Your Implementation Required

​Complete Endpoint Reference

​Data Export & Sync

​Campaign Activity

​Tasks

​Users (Optional)

​Data Flows

​Export Flow

​Sync Endpoint Behavior

​Campaign Activity Flow

​Engagement Field Updates

​CRM Record Links (Optional)

​Error Handling

​Reference Implementation

GitHub Repository

Introduction

Required Endpoints

Quick Reference Cards

Authentication

Health Endpoint

Complete Endpoint Reference

Data Export & Sync

Campaign Activity

Tasks

Users (Optional)

Data Flows

Export Flow

Sync Endpoint Behavior

Campaign Activity Flow

Engagement Field Updates

CRM Record Links (Optional)

Error Handling

Reference Implementation