Integrations

Integrations link UnitX to the other systems your organization runs, so records stay in step without copying and pasting. You approve a connector, connect it with a credential, decide how its fields map onto yours, and sync. You can also send UnitX events out to your own systems with outgoing webhooks.

Key concepts#

Connector

A kind of system UnitX can talk to. Connectors are listed on the Connectors tab and must be approved before anyone can connect them.

Private connector

A connector your organization adds for its own internal API. Visible only to your organization and never published.

Connection

One connected account of a connector, with its stored credential. You can connect the same system more than once.

Sync

A run that reads records from the other system and creates or updates them in UnitX.

Field mapping

Which field in the other system corresponds to which field in UnitX.

Who can do what#

Approve a connector#

A connector must be approved for your organization before anyone can connect it. This is separate from any sign-in consent the other system asks for.

1. Open the Connectors tab

   Go to IntegrationsConnectors. Each connector shows its category, how it authenticates, and Approved or Not approved.

2. Choose Approve

   You see Connector approved. Withdraw removes the approval again.

A connector marked Unavailable is listed but has no working implementation yet, so it cannot be connected.

Add a private connector#

To integrate your own internal system with a REST API, add it as a private connector.

1. Choose Add connector

   At the top right of the Integrations page. The Add a private connector dialog opens.

2. Fill in the details

   Name (for example “Warehouse API”), Key — a stable identifier such as warehouse-api that never changes even if the name does — and Category: Custom, CRM, Finance, Communication or Storage.

3. Choose Add connector

   It appears on the Connectors tab with a Private badge. Approve it before connecting.

Connect a system#

1. Choose Connect

   On an approved connector in the Connectors tab.

2. Name the connection

   Connection name — for example “Production warehouse” — so several connections to the same system can be told apart.

3. Enter the address and credential

   Base URL of the other system’s API, and its API token. The token is stored encrypted and is never shown again, here or anywhere else.

4. Optionally describe the resources

   Resources (optional) says which path to read each kind of record from, as JSON — for example {"customer": {"path": "/companies", "recordsField": "items"}}. Leave it empty to configure it later.

5. Choose Connect

   The connection appears on the Connections tab.

The connection page#

Select a connection on the Connections tab to open it. The header shows its status, when it last synced and any last error, with Test connection and Disconnect.

Connection statuses#

connected

Working and ready to sync.

needs reauthorization / expired

The credential needs replacing.

error

Recent calls failed. See the last error shown on the page.

disconnected

The stored credential was removed.

disabled

The connection has been switched off.

Suspended / Calls suspended

After repeated failures UnitX temporarily stops calling the other system, so a failing service is not hammered. “N recent failures” warns that this may happen.

Test connection checks the credential and tells you either The connection is working. or what category of problem it found.

Sync#

1. Choose the resource

   On the Sync tab, pick the kind of record to sync from Resource.

2. Choose Sync changes

   Reads what changed since the last sync. This is the one to use day to day.

3. Use Full resync sparingly

   Full resync re-reads everything, which can be slow and expensive on a large account.

Each run is listed with its status (completed, partial, failed, running or queued) and how many records were created, updated and failed. Choose Show failures to see each failed record and why; failures marked in amber are worth retrying, red ones need a fix first.

Field mappings#

Without mappings, fields whose names already match are copied across as they are. Add a mapping when names differ or a value needs converting. Mappings added on this tab apply to customer records coming into UnitX.

1. Name both fields

   Field in the other system (for example company_name) and Field in UnitX (for example name).

2. Choose a transform

   Use the value as-is, Trim whitespace, Lowercase, Uppercase, Convert to text, Convert to a number, Convert to true/false or Convert to a date.

3. Choose what happens if both sides change

   The other system wins, UnitX wins, Most recent change wins, Whoever owns the field, or Ask a person.

4. Try it first

   Type a sample into Try it on a value and choose Preview to see the result before it touches real data.

5. Choose Save mapping

   The mapping is listed with its transform and strategy. Remove deletes it.

Conflicts#

When a field is set to Ask a person and it changed on both sides, the conflict appears on the Conflicts tab, showing the value In UnitX and In the other system. Choose Keep the UnitX value or Take the other system’s value. Your decision is recorded, and the winning value is written by the next sync.

Incoming webhooks#

If the other system can notify UnitX when something changes, create an endpoint so changes arrive as they happen instead of waiting for the next sync.

1. Choose Create an endpoint

   On the Incoming webhooks tab.

2. Copy the URL and signing secret

   Both are shown under Give these to the other system. The secret is shown only once. Every request the other system sends must carry an x-unitx-signature header computed with it, or UnitX rejects it.

3. Check what arrives

   Choose Events on an endpoint to see each request received and whether it was processed, queued or failed.

Disconnect#

Disconnect removes the stored credential. Records already brought in are kept, along with the links recording where they came from, so you can reconnect later and carry on.

Outgoing webhooks#

Outgoing webhooks send UnitX events to a URL you run — for example to trigger your own automation when something changes.

1. Add an endpoint

   On the Outgoing webhooks tab, enter the URL and an optional Description, then choose Add endpoint.

2. Copy the signing secret

   It is shown once. Your system uses it to check the x-unitx-signature header on every delivery.

3. Watch deliveries

   Deliveries lists each event sent, the number of attempts, the HTTP status your system returned, and whether it was delivered, pending, failed or exhausted.

An endpoint added here receives all events. Failed deliveries are retried with increasing delays, up to five attempts. Remove stops deliveries to an endpoint. For the delivery format, see API overview.

Related pages#

• Marketplace
• Migrations
• API overview
• Automations