Who This Page Is For

This page is for your ERP or CRM's development team when your system is not one of the native integrations (Dynamics 365, Salesforce, HubSpot, Pipedrive, Loji). CX-Engine's generic REST connector lets you connect any system that exposes an API, but that API needs to implement a small, specific set of routes so the Middleware can query and write to it during PBX events (incoming calls, outgoing calls, chat sessions).

You do not need to replicate CX-Engine's own API shape — the generic connector is configured visually (endpoint URLs, auth, field mapping) from the CX-Engine interface. What matters is that your system exposes routes that can perform the following operations.

Authentication

Your API must support one of the following, since these are the methods the generic connector can be configured with:

Method Description
OAuth 2.0 Client Credentials Server-to-server auth using a client_id / client_secret pair. Recommended for headless setups.
HTTP Basic Auth Username / password sent on every request.
API Key A static key sent as a header or query parameter.

Whichever method you choose, credentials are entered once in the CX-Engine Integrations menu and used for every subsequent request to your API.

Required Routes

Contact Lookup — search by phone number or email

Usage: Called during a screen-pop when a call rings on the PBX, so CX-Engine can display the matching customer record to the agent before they pick up.

Your API needs a route that accepts a phone number and/or an email address and returns matching contacts.

Suggested shape

GET /contacts/search?phone={phone}&email={email}

Response field Description
id Unique contact identifier in your system
first_name / last_name Contact name
email Contact email
phone_business / phone_mobile Phone numbers, so CX-Engine can match on either
company Company name, shown in the screen-pop
entity_url Direct URL to the contact's record in your system, used to open it in one click

If a call comes in and no contact matches, return a 404. CX-Engine uses this to fall back to its dummy contact placeholder, so call logging can still proceed.

Contact Creation

Usage: Called when an agent chooses to create a new record for an unrecognized caller, directly from the CX-Engine screen-pop.

Suggested shape

POST /contacts

Field Required Description
last_name yes Last name
first_name no First name
email no Email address
phone_business / phone_mobile no Phone numbers
call_direction no inbound or outbound — the direction of the triggering call

Your API should respond with the created record (at minimum its id) so CX-Engine can link the call to it.

User Lookup — find a user by email

Usage: The PBX only ever provides the agent's email address. If call logging in your system needs a user_id to link the call to a specific user/agent record, CX-Engine needs a route to resolve that email to your internal user identifier.

Suggested shape

GET /users/search?email={email}

Response field Description
id Unique user identifier in your system
email The user's email address

Call Logging — record a completed call

Usage: Called when a call ends on the PBX, so it appears as an activity/history entry against the right contact in your system. This is the core of the "automatic call logging" feature.

Suggested shape

POST /calls

Field Description
direction inbound, outbound, or internal
status e.g. completed, no-answer, busy
number_from / number_to Caller and callee numbers
duration Call duration
start_time / end_time Call timestamps (UTC)
agent_email Email of the agent who handled the call
user_id Internal user identifier for the agent, resolved via the user lookup route above, if your call record requires it
recording_url URL to the call recording, if your plan includes call recording
linked_contact_id The contact id returned by the lookup route, if a match was found

Updating a Call

Usage: Some data isn't available yet when the call first ends — additional PBX details fetched in a second pass, or an AI transcription/summary that finishes asynchronously. Your API needs a route to update the call record that was already created, rather than requiring a fresh POST for every subsequent piece of data.

Suggested shape

PUT /calls/{id}

Accepts the same fields as POST /calls, applied as a partial update to the call identified by {id} — the identifier your system returned when the call was first logged.

AI Fields

If your CX-Engine plan includes the Insights AI add-on, calls are also enriched with AI-generated data — transcription, summary, sentiment, topics, and more. This data is typically not ready when the call ends, so it's sent via the PUT /calls/{id} update route above once transcription completes. See the AI & Transcription fields in Configure the Middleware for the full list of fields you can choose to map and store.

Chat Logging (optional)

Usage: If your PBX/contact center also handles live chat, the same pattern applies — a route to record a completed chat session against a contact.

POST /chats

Field Description
email Customer's email address, used to match or create a contact
number_external Customer's external identifier, if no email is available
chat_messages Transcript or summary of the conversation
start_time / end_time Chat timestamps
agent_email Agent who handled the chat

Response Conventions

  • Return standard HTTP status codes: 200/201 for success, 4xx for client errors (bad request, not found), 401/403 for authentication/authorization failures.
  • Return JSON for every response, including errors.
  • For list or search routes, return an empty array rather than a 404 when there are no matches. The contact lookup route is the exception: return a 404 there so CX-Engine can trigger its dummy contact fallback (see above).

Next Steps

Once your API exposes these routes, an administrator can configure the connection from the CX-Engine Integrations menu — see Connect CRM Integration — and map your API's fields to CX-Engine's fields from the CRM Connector > Settings menu — see Configure the Middleware.

Configure the Middleware