The Custom CRM integration allows you to connect Enginy with your own CRM system or internal database. This option is designed for teams using a proprietary or custom-built system that is not supported by Enginy's standard integrations.
Note: Custom CRM is currently in Beta. If you need help setting it up, contact your Account Manager.
Overview
Once connected, Enginy can interact with your CRM in the following ways:
Export contacts and companies from Enginy to your CRM.
Create tasks directly in your system when sequences or workflows require it.
Create associations between contacts and companies in your CRM.
Log activities — LinkedIn messages and emails — to your CRM.
Assign owners to exported records, if your CRM supports users.
Prerequisites
Before connecting, your CRM must expose the following API endpoints:
Endpoint | Purpose | Required |
| Connection validation | Yes |
Contacts API | Batch create contacts | Yes |
Companies API | Batch create companies | Yes |
Associations API | Link contacts to companies | Yes |
Tasks API | Task CRUD and batch endpoints (for sequences) | Yes |
Activities API | Log LinkedIn and email activities | Yes |
Users API | List users for owner assignment | Optional |
For the full endpoint specification, see the Custom CRM API Reference.
Authentication
Your CRM must accept API key authentication via a configurable header. When connecting, you will need to provide the following parameters:
Parameter | Description | Default |
| Your API base URL (e.g., | Required |
| Your API key or secret token | Required |
| The header name used to send the API key |
|
| URL template for contact records — use | Optional |
| URL template for company records — use | Optional |
Enginy includes your API key header in every request sent to your CRM. For example:
POST /contacts HTTP/1.1 Host: api.mycrm.com X-API-Key: your-secret-key Content-Type: application/json Accept: application/json
CRM Record Links
When configured, Enginy can generate clickable links that open contact and company records directly in your CRM. To enable this, provide URL templates when connecting — using {{crmId}} as the placeholder that will be replaced with the actual record ID:
{ "baseUrl": "<https://api.mycrm.com>", "apiKey": "your-crm-api-key", "apiKeyHeader": "X-API-Key", "contactLinkTemplate": "<https://mycrm.com/contacts/{{crmId}>}", "companyLinkTemplate": "<https://mycrm.com/companies/{{crmId}>}" }
For example, the template https://mycrm.com/contacts/{{crmId}} becomes https://mycrm.com/contacts/ABC123 when Enginy generates the link. If link templates are not provided, the "Open in CRM" option will not be available for Custom CRM records.
Users / Owners Support (Optional)
If your CRM supports assigning users or owners to contacts, companies, tasks, and activities, you can implement the optional /users endpoint to enable owner selection in Enginy.
Every time Enginy needs to fetch owners, it automatically tests your /users endpoint. The behaviour depends on the response:
Response | Result |
2xx with user list | Owner selection enabled in the export modal |
404 / 501 / 405 | Owner selection gracefully disabled — not treated as an error |
Other errors | Owner selection disabled; connection proceeds normally |
When users are available, Enginy shows an owner dropdown in the export modal, task creation, and activity logging. You can add or remove the /users endpoint at any time — detection happens dynamically on every request, not only at initial connection.
Your /users endpoint should return an array of users in the following format:
[ { "id": "user-123", "name": "John Smith", "email": "[email protected]" }, { "id": "user-456", "name": "Jane Doe", "email": "[email protected]" } ]
The id field is sent back to your CRM whenever a record is created with an owner assignment.
Connecting Your CRM
Follow these steps to connect your Custom CRM to Enginy via the API.
Step 1: Implement the Required Endpoints
Before connecting, ensure your CRM implements all the required endpoints listed in the Prerequisites section above. See the Custom CRM API Reference for full specifications.
Step 2: Test the Connection
Use the test endpoint to validate your configuration before connecting:
curl -X POST <https://openapi.enginy.ai/v1/custom-crm/test> \\ -H "x-api-key: gsk_your_enginy_api_key" \\ -H "Content-Type: application/json" \\ -d '{ "baseUrl": "<https://api.mycrm.com>", "apiKey": "your-crm-api-key", "apiKeyHeader": "X-API-Key" }'
The response confirms whether the connection is valid and whether owner support is detected:
{ "success": true, "supportsUsers": true, "users": [{ "id": "user-123", "name": "John Smith", "email": "[email protected]" }] }
Step 3: Connect
Once the test passes, connect your CRM:
curl -X POST <https://openapi.enginy.ai/v1/custom-crm/connect> \\ -H "x-api-key: gsk_your_enginy_api_key" \\ -H "Content-Type: application/json" \\ -d '{ "baseUrl": "<https://api.mycrm.com>", "apiKey": "your-crm-api-key", "apiKeyHeader": "X-API-Key", "contactLinkTemplate": "<https://mycrm.com/contacts/{{crmId}>}", "companyLinkTemplate": "<https://mycrm.com/companies/{{crmId}>}" }'
Step 4: Verify Status
Check your connection status at any time:
curl <https://openapi.enginy.ai/v1/custom-crm/status> \\ -H "x-api-key: gsk_your_enginy_api_key"
Exporting to Your CRM
Once connected, you can export contacts and companies from Enginy to your Custom CRM:
Select leads or companies in Enginy.
Choose "Export to CRM" and select Custom CRM.
Enginy will automatically create companies first (if any), then contacts, and finally associations between contacts and companies.
CRM IDs are saved in Enginy for future reference.
Note: The export is push-only. Enginy sends all available fields as-is to your CRM. Your CRM is responsible for mapping and storing the data appropriately.
Step 1: Sync Configuration
This step defines how Enginy matches contacts and companies with your CRM records to prevent duplicates and ensure data integrity. A sync means Enginy compares its records against your CRM records using the identifiers you configure here.
Integration User
It shows whose email address is the API integration user.
Contact Identifier
Choose how Enginy determines whether a contact already exists in your CRM.
Option | Matching Logic |
First name + Last name + Company name | A contact matches when all three fields are the same in both Enginy and your CRM. |
LinkedIn profile URL OR First name + Last name + Company name | A contact matches if the LinkedIn profile URL is the same or all three name/company fields match. |
Custom Mapping | Opens a pop-up where you define custom conditions using AND/OR logic (for example, match by First Name AND Last Name, OR by Professional Email). |
Company Identifier
Choose how Enginy determines whether a company already exists in your CRM.
Option | Matching Logic |
Domain | Matches on the company domain (e.g., |
Domain or Company Name | Matches if either the domain or the company name is the same. |
Custom Mapping | Opens a pop-up where you define custom conditions (for example, match by Domain OR Company LinkedIn URL). |
General
Under General, you'll find two toggles that control how associations are handled during export:
When exporting contacts, associate them with companies in your CRM: If enabled, Enginy will automatically link exported contacts to their corresponding companies in your CRM.
When exporting companies, associate them with contacts in your CRM: If enabled, Enginy will automatically link exported companies to their related contacts in your CRM.
Step 2: Field Mapping
This step configures which Enginy fields map to which CRM fields when exporting data. The setup is split into two tabs — Contacts and Companies — and the mapping configuration works the same way in both.
Field Types
Field Type | Description |
Enginy Fields | Standard fields from your contact or company lists (e.g., Phone Number, Job Title). Click Add field to add a mapping: select the Enginy field first, then the corresponding CRM field. |
Fixed Value Fields | Fields that always export with the same static value. For example, create a field called "Source" with fixed value "Enginy" so every exported record is tagged with its origin. |
Manual Export Fields | Fields whose value you define at the time of export. Click Add field, select the CRM field to be set when exporting. As many as you want. |
Engagement Fields | Fields populated when an Activity is created in your CRM (e.g., an email sent, a LinkedIn message, or a Task log). Select the CRM field and set the Value to export. Only one can be set. |
Warning: Don't map a Company field in the Contacts tab (or a Contact field in the Companies tab). This can cause export errors. If you must map the same field in both tabs, make sure it's mapped the same in both places.
In each CRM field mapping dropdown, you'll see small status icons indicating whether the mapping is supported, not supported, or supported with limitations / a workaround.
Icon | Meaning |
Blue check | The mapping is okay, has no potential problems. |
Yellow exclamation | The field types in Enginy and your CRM may be incompatible (e.g., an Enginy Text field mapped to a CRM Enumeration field). |
Red X | The mapping can't be applied because the types don't match — or because the CRM field is read-only and can't be updated. |
Mapping Options
Option | Behaviour |
Bi-directional sync | Changes sync both ways automatically. |
CRM overwrites Enginy | Changes in your CRM automatically overwrite the corresponding fields in Enginy. |
Enginy overwrites CRM | Changes in Enginy automatically overwrite the corresponding fields in your CRM. |
Sync if value is empty | Data only syncs automatically when the destination field is empty, preventing overwriting existing values. |
Sync deactivated | No automatic sync. You'll need to manually export or run a sync to apply changes. |
Association Type
The Association Type setting controls the relationship between a contact and a company inside your CRM.
Option | Behavior |
Add as additional association | Adds the association without changing existing ones. |
Add association as Primary | Sets the new association as the primary relationship. |
Associate as Primary and remove previous associations | Sets the new association as primary and deletes all previous associations. |
Warning: The "Associate as Primary and remove previous associations" option is not recommended unless you are certain you want to erase all prior associations. Using it can result in data loss if historical relationships exist.
When exporting manually a contact or company, you can choose the Association Type in the export modal. The integration settings define the default association type, but you can override it for each individual manual export.
You can also: overwrite existing values for any field mapping (in either the Contacts or Companies tab), overwrite CRM owner, optionally set Manual export field values, and enable Export associated companies (or Export associated contacts when manually exporting a company).
Step 3: Campaign Mapping (Optional)
This step lets you sync campaign-specific properties to your CRM. These are not standard list fields; they are properties tied to campaign activity.
Sequence
Property | What It Contains | Example Value |
Campaign Sequence Details | The steps included in the campaign. |
|
Campaign Engagement Status | The current status of each lead in the campaign. |
|
Sequence Status | The overall status of the campaign sequence for the lead. |
|
Campaign Reply Analysis | Indicates per-message whether the lead replied to each automated message. |
|
Email
Property | What it Contains | Example Value |
Campaign Opens | Total number of times a lead has opened one or more emails in the campaign. |
|
Campaign Clicks | Total number of times a lead has clicked a link in campaign emails. |
|
Campaign Open Analysis | Indicates per-message whether the contact opened that specific email. |
|
Campaign Click Analysis | Indicates per-message whether the contact clicked a link in that specific email. |
|
General
Property | What it Contains | Example Value |
Campaign | All Campaign names the contact has been added to. |
|
Senders | All sender names that have contacted the contact. |
|
Activities | All activities that have occurred with the contact. |
|
Conversation Tags
Property | What it Contains | Example Value |
Conversation Tags | All conversation tags applied to the contact (comma-separated). |
|
Conversation Tags Categories | Categories of conversation tags: POSITIVE, NEUTRAL, NEGATIVE (comma-separated). |
|
Step 4: User Mapping
This final step defines the associations between Enginy users/identities and your CRM users so that exports and activity logs are attributed to the correct people.
Identities Mapping
An Identity in Enginy is the profile that runs a campaign (for example, a LinkedIn profile or an email sender). Identities Mapping links each Enginy identity to a user in your CRM.
When a campaign — which is always linked to an identity — performs a sync or export, your CRM activity log shows the associated CRM user as the one who executed the action.
Users Mapping
Users Mapping links an Enginy user account to a user in your CRM. This sets the default owner for any record exported by that user — even for automatic exports via field mappings, not just manual exports.
Default CRM owner
This mapping sets a default owner (contact or company owner) for exports performed by an Enginy user who isn't mapped in User Mapping.
Save Your Configuration
After completing all four steps, click Update to save your Custom CRM configuration.
Disconnecting
To disconnect your Custom CRM at any time, use the following API call:
curl -X DELETE <https://openapi.enginy.ai/v1/custom-crm/disconnect> \\ -H "x-api-key: gsk_your_enginy_api_key"