Custom integrations

Build a custom integration with Empuls’s dynamic integration framework, configure endpoints and data mapping, and monitor sync runs in the history page.

When none of the built-in integrations covers your system of record — a homegrown HRIS, a regional payroll provider, a legacy directory — you can build a custom integration using Empuls’s dynamic-integration framework. You define the endpoints, the data mapping, and the schedule; Empuls handles fetching, transforming, and applying the records. The custom-integration data-sync history page shows every run with success and error counts. Open the integrations hub in your tenant at https://<your-empuls-url>/home/integrations and click Custom integration.

Before you start

• You must be a Super Admin in Empuls.
• You need engineering capacity (or vendor support) on the source-system side to expose an endpoint Empuls can read.
• Standard authentication options: bearer token, basic auth, or OAuth 2.0. Pick the strongest your source system supports.

How custom integrations work

1. Define the endpoint

   Provide the URL Empuls should call, the HTTP method, headers, and authentication.

2. Define the data shape

   Tell Empuls what JSON path returns the user list and how each field maps to an Empuls field (First Name → $.first_name, Email → $.email, etc.).

3. Set the schedule

   Pick a cadence (every 6 hours, daily, weekly) or trigger sync manually.

4. Test with a single run

   Empuls calls the endpoint once and shows the parsed records before importing. Fix mapping errors before going live.

5. Enable the integration

   Turn it on and Empuls begins fetching on schedule.

Endpoint requirements

Your endpoint must:

• Return a JSON response.
• Be accessible from Empuls’s network (typically the public internet; IP-restricted endpoints require an allowlist exchange).
• Use TLS — HTTP is not accepted.
• Return at most a few thousand records per page (paginate if your dataset is larger).

Field mapping

Map source fields to Empuls fields via JSONPath expressions:

Empuls field	Example JSONPath
First Name	$.first_name
Last Name	$.last_name
Email	$.work_email
Department	$.org.dept_name
Designation	$.role.title
Manager email	$.manager.email
Status	$.employment_status
Custom UDF	$.custom.tier

Use JSONPath for nested structures. The test-run step shows exactly what each path resolves to.

Data sync history

The data-sync history page lists every run:

• Run ID — Unique ID for the run.
• Timestamp — When the run started.
• Duration — How long it took.
• Records added / updated / skipped / failed — Counts.
• Status — Success, partial success, or failed.

Click into any run to see per-record details and error messages.

Pause, edit, or delete

• Pause — Stop the recurring schedule without losing configuration.
• Edit — Adjust endpoint URL, headers, mapping, or schedule. Edits don’t trigger a retroactive re-sync.
• Delete — Remove the integration entirely. Already-imported users stay in Empuls.

When to build custom vs ask for a connector

Use a custom integration when:

• Your source system is internal or regional and unlikely to ship as a built-in connector.
• You need a specific transformation that built-in connectors don’t support.

Reach out to Empuls support to request a new built-in connector when:

• Your source system is a major commercial product (HRIS, payroll, identity) used by many customers.
• The data volume is high enough that a managed connector with native pagination and retry semantics would be safer.

Limits and gotchas

• Empuls won’t follow redirects across hosts — keep the endpoint URL on a single host.
• If your endpoint changes its response shape (renamed field), the integration will fail until you re-map.
• Custom integrations are subject to a per-tenant maximum (typically 10). Contact support if you need more.

Related

• HRMS integration overview — Compare custom against built-in HRIS connectors.
• Webhook & APIs — For outbound notifications instead of inbound sync.