---
title: Requirements for the CX-Engine Middleware
excerpt: What your ERP or CRM's REST API needs to expose for CX-Engine's generic connector — contact lookup, contact creation, and call/chat logging.
order: 5
---

## 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](/en/faq/crm-middleware/supported-integrations) 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](/en/docs/middleware-crm/configure-middleware#available-fields) 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](/en/docs/middleware-crm/connect-integration) — and map your API's fields to CX-Engine's fields from the **CRM Connector** > **Settings** menu — see [Configure the Middleware](/en/docs/middleware-crm/configure-middleware).