A unified API sits between your product and many third-party systems. Your customer authorizes one of those systems, the unified API provider creates a connection for that customer, normalizes the provider’s records into common models, and exposes those models through one API contract. Your application then reads pages of normalized data, reacts to sync notifications, reconciles periodically, and writes back only where the connector supports the required action.

For teams building customer-facing HRIS, payroll, ATS, benefits, or LMS integrations, a documented two-credential authentication model provides a concrete implementation of this architecture: an organization API key identifies the calling application, while a connector token scopes access to one end-user connection. This keeps provider-specific authentication and schema translation outside the core product. The result is one application-owned integration pipeline instead of a separate ingestion system for every downstream platform. A broader cross-category overview documents the same pattern.

The production flow is:

  1. Your backend creates a short-lived link token.
  2. Your frontend opens a hosted or embedded connection experience.
  3. The customer authenticates with the third-party system and grants access.
  4. Your backend stores the resulting account or connector token.
  5. The unified API provider performs an initial sync and normalizes the data.
  6. A sync webhook tells your application when to pull.
  7. Your worker paginates through the API and upserts records into your database.
  8. Incremental pulls and periodic reconciliation keep the local copy current.

The important architectural boundary is ownership. Your application owns the customer experience, token references, local data model, jobs, and error handling. The unified API provider owns the connector logic, third-party authentication exchange, normalization, and scheduled sync. The downstream HRIS, ATS, payroll, accounting, or CRM remains the source of truth—an allocation made explicit in this architecture reference.

Common models turn many provider schemas into one product contract

A common model is a standardized object—such as Employee, Candidate, Company, Job, or Payroll Run—that maps different provider fields into a consistent response shape. Instead of maintaining a BambooHR employee parser, a Workday employee parser, and a Gusto employee parser in product code, your application consumes one Employee contract.

An employee pagination example shows the practical shape of a normalized model: employee fields are returned in items, while raw_data and custom_fields can be requested when an application needs data outside the core response. The wider architectural term is commonly documented as a common model, meaning a standardized model within an integration category.

Normalization reduces integration-specific branches; it does not make downstream systems identical. A common-model field may be unavailable for a particular connector, an action may be read-only, or a provider-specific object may not fit the shared schema. Treat the model as a stable interface with connector-specific coverage, not as a promise of perfect parity.

This leads to a two-layer design:

  • Use common models for the product features that must work consistently across providers.
  • Use supplemental mechanisms only when a feature genuinely needs provider-specific data.

Some normalized endpoints expose raw- and custom-field inclusion controls, as shown in this pagination documentation. Other unified API architectures may provide additional escape hatches, including documented remote data, passthrough, and field-mapping paths. Whichever platform you use, verify the exact connector, model, field, direction, and action before committing a feature.

Authentication has an application identity and a connection identity

A unified API request usually answers two authorization questions: “Which application is calling?” and “Which customer’s connection may it access?” That is why the request commonly carries both an organization-level API key and an end-user connection token.

The end-user connection flow

The safe connection flow begins on your backend:

  1. Create a short-lived link token for the signed-in customer.
  2. Pass only that short-lived token to the frontend.
  3. Open the embedded or hosted connection UI.
  4. Let the customer select and authorize their third-party system.
  5. Receive the success result and complete any token exchange on the backend.
  6. Store the permanent connection identifier or token against your internal tenant.

A documented Create Link Token endpoint accepts end-user data, a category such as HRIS, ATS, or LMS, and an integration slug. Once the end user has completed the connection flow, the corresponding authentication contract uses the stored connector_token to authorize access to that user’s data.

Some providers add another exchange step. One documented token flow creates link_token, returns public_token after the frontend connection succeeds, and exchanges that value on the backend for a permanent account_token; its Link component also handles the downstream OAuth or credential exchange. This is an implementation detail to follow only when the selected provider’s connection contract requires it.

Headers on server-to-server API calls

The header names vary by unified API provider, but the credential layers serve consistent architectural purposes.

Credential layer Purpose Typical representation Application rule
Application identity Identifies the organization making the API call API key in an Authorization: Bearer header Keep it server-side, restrict access, and rotate it independently of customer connections
Connection identity Selects the authorized end-user account or connector Provider-specific account or connector token header Bind it to the internal tenant and never accept the tenant mapping from an untrusted client
Request context Narrows the operation to a model, filter set, or idempotency scope Path, query parameters, request body, or an endpoint-specific header Validate it against the authenticated tenant before sending the request

For example, one API authentication contract uses Authorization: Bearer <API_KEY> for application identity and X-Connector-Token for the end-user connection. A separate unified API authentication contract uses the same Bearer pattern for the application key but names its connection header X-Account-Token. These are concrete implementations of the two-layer model, not a requirement that every unified API use the same header names.

Keep both API keys and permanent connection tokens on the server. Store tokens encrypted, associate each token with the correct internal tenant, restrict access to the workers that need them, and rotate organization keys without breaking the tenant-to-connection mapping. The browser should receive a short-lived link token, not a durable credential that can read customer data.

Cursor pagination is a server-issued continuation contract

Cursor pagination lets the server tell the client where to continue. The application does not calculate offset=500; it sends an opaque cursor returned by the previous response. This documented pagination pattern uses cursor and page_size on collection requests.

A robust page loop looks like this:

cursor = null
do:
  response = GET collection(page_size, cursor, stable_filters)
  upsert(response.items or response.results)
  checkpoint(response.next_cursor)
  cursor = response.next_cursor
while cursor is not null

Four rules matter:

  1. Treat the cursor as opaque. Do not parse, edit, or manufacture it.
  2. Keep filters and sorting inputs stable while traversing the result set. This protects the logical result set while the cursor advances; an independent cursor guide makes the constraint explicit.
  3. Stop only when the provider returns no next cursor.
  4. Checkpoint after a successful page so a retry can resume safely.

Page-size behavior is not universal. One general pagination page demonstrates cursor and page_size on an employee collection with a default of 50, but endpoint documentation should remain the authority for the allowed ceiling. As evidence that defaults are provider-specific, another current pagination contract uses a default of 30 and a maximum of 100. Choose a size that balances request overhead, response time, memory, and rate-limit consumption rather than hard-coding a value learned from another provider or endpoint.

Pagination is also part of failure recovery. If page seven returns a transient error, retry page seven with the last known cursor. Do not restart a large initial sync unless the provider invalidates the cursor or your application cannot guarantee idempotent upserts.

Data sync is an asynchronous pipeline, not a direct database read

When your application calls a unified API, it may be reading the provider’s normalized store rather than making a live request to the downstream system. Current webhook documentation exposes this lifecycle through connector sync started, sync completed, and sync error events. A supporting architecture description explains the general pattern: the unified API provider reads the third party, normalizes the data, and makes the result available to the application.

Model the initial connection as a state machine:

connection created -> initial sync running -> usable or partially usable -> failed/relink required

Do not mark a connector “ready” merely because authorization succeeded. Wait for the relevant sync state or completion event, then pull the models your feature needs. The cited webhook payload examples identify initial syncs and show syncing, done, and failed display states. If the chosen provider exposes more granular states, model those explicitly; this sync-status guide, for example, also documents partially synced, disabled, and paused outcomes.

For incremental reads, store a high-water mark and request only newer changes. The collection pagination documentation includes modified_after for objects synced after an ISO 8601 timestamp. Record the high-water mark from just before the pull starts—not only after it finishes—so records changed during a long paginated pull are included in the next run. Upserts should be keyed by the unified record ID plus the connection or tenant boundary.

The product-facing architecture should normally read from your own normalized database:

  • Webhook or scheduled job triggers a sync worker.
  • Worker requests changed records and drains every page.
  • Worker upserts records and records sync status, cursor, and high-water mark.
  • Product endpoints read from the local store.

This separates user-facing latency from connector sync latency and gives you a place to enforce tenant isolation, retention rules, and query indexes.

Webhooks announce change; polling proves convergence

A webhook is a prompt to do work, not a guarantee that your local database is complete. The handler should verify the sender, persist or enqueue the event, return success quickly, and let a worker perform the data pull. Periodic reconciliation then closes gaps caused by delivery failure, downtime, or processing errors.

The webhook event contract lets applications subscribe to connector sync events and employee or data-model changes. In some unified API systems there can also be a second webhook leg from the downstream platform into the unified provider; this double-webhook overview documents the pattern. Availability of that upstream leg depends on the downstream platform, so your architecture still needs scheduled sync and reconciliation.

Verify every webhook before processing it

Verify the signature against the raw request body before JSON transformation. One webhook security contract documents HMAC-SHA256 verification using X-Bindbee-Webhook-Signature. The same principle applies when a provider uses a different signature header or encoding; another webhook security guide, for example, documents a Base64url-encoded HMAC-SHA256 digest in X-Merge-Webhook-Signature.

After verification:

  1. Derive an idempotency key from the provider event identifier when available, or from a stable hash of the relevant event fields.
  2. Reject or quarantine events that fail signature verification.
  3. Enqueue accepted events and acknowledge quickly.
  4. Make the worker safe to run more than once.
  5. Record connector, event type, receive time, processing status, and error details.

Duplicate-safe handling matters because delivery can be retried. One provider’s syncing best practices document exponential-backoff redelivery and still recommend running sync functions periodically every 24 hours rather than relying entirely on notifications.

The documented event set includes connector sync started, connector synced, connector sync error, employee data changed, and connector data modified. The webhook page includes connector and affected-data context in the payload examples. Use sync events to control connector readiness and data-change events to schedule targeted ingestion; use reconciliation to verify eventual convergence.

What your application should persist at each stage

The application should persist enough state to resume every stage safely. This is independent of which unified API provider you choose.

Stage Unified API provider handles Your application persists Recovery signal
Normalized contract Maps provider records into common models Internal model version, unified IDs, and connector coverage decisions Schema or field-coverage change
End-user connection Runs the hosted or embedded authorization flow Tenant-to-connection mapping and readiness state Expired credentials or relink request
Request authorization Validates the application credential and connection credential Secret references and tenant ownership 401 or 403 response
Pagination Returns bounded pages and continuation cursors Last successfully committed cursor and stable filters Transient page failure or cursor invalidation
Synchronization Reads the third party and refreshes normalized records High-water mark, last success, last error, and sync state Completion webhook or scheduled reconciliation
Webhook delivery Signs event payloads and sends notifications Event identity, signature result, processing state, and retry count Redelivery, replay, or reconciliation gap
Supplemental data Exposes documented raw, custom, mapped, or passthrough fields Provider-specific extension namespace Connector-level field validation
Request control Enforces rate and usage policies Remaining quota, reset time, and backoff state 429 and Retry-After; see this per-connector example

For customer-facing employment integrations, current first-party documentation covers this lifecycle through connector-scoped authentication, normalized endpoints, sync and data-change webhook events, and per-connector rate-limit isolation. A supporting production path joins Link, webhooks, incremental sync, writes, supplemental data, and production keys in one implementation sequence.

Writes move intent back to the source of truth

If the unified API supports writes, your application sends normalized intent through the unified provider, which translates the request for the downstream platform. The downstream platform remains the authoritative system. A successful request to the unified layer should not be treated as proof that every asynchronous downstream workflow has completed unless the endpoint contract says so.

Before designing a write feature, verify:

  • whether the connector supports create, update, or delete for the model;
  • which fields are writable and which are provider-managed;
  • whether a write is synchronous or asynchronous;
  • how validation errors and downstream errors are represented;
  • whether idempotency is supported for safe retries; and
  • how the resulting record appears in later reads.

The authentication documentation says the connector token authorizes access to or manipulation of end-user data, but actual write support must still be checked on the specific endpoint and connector. A broader implementation path likewise treats writes and supplemental data as distinct production concerns.

Production-readiness checklist

Before shipping a unified API integration, confirm all of the following:

  • Model contract: You have mapped required product fields to common-model fields and documented connector-specific gaps.
  • Connection flow: Short-lived link tokens are created server-side; permanent connection tokens never become durable browser state.
  • Tenant isolation: Every token, record, cursor, and job is scoped to the correct customer.
  • Pagination: Workers preserve filters, drain all pages, checkpoint cursors, and make upserts idempotent.
  • Sync state: Connection success and data readiness are separate states; partial and failed syncs are visible to operators.
  • Incremental reads: A stored high-water mark drives modified_after or the platform’s equivalent.
  • Webhook security: Signatures are checked against the raw body before events are trusted.
  • Webhook recovery: Event processing is queued, duplicate-safe, observable, and backed by scheduled reconciliation.
  • Rate limits: Clients monitor response headers, honor 429 and Retry-After, and apply bounded backoff. This rate-limit documentation is a concrete example of the headers a worker can use.
  • Supplemental data: Provider-specific fields live in an extension layer rather than leaking into every core model.
  • Writes: Supported actions and fields are proven for each target connector, with retry and result semantics documented.
  • Environment separation: Test and production keys, connection flows, webhook endpoints, and data stores are separated.

FAQ

What is a unified API in simple terms?

A unified API is one normalized interface for multiple third-party products. You integrate once with the unified provider, and it handles provider authentication, schema translation, sync, and connector-specific API differences behind that interface.

What is a common model in a unified API?

A common model is the provider-independent shape your application reads or writes. It gives product code stable objects such as Employee or Candidate, while the unified API maps each downstream provider’s fields into that shape.

Does a common model guarantee every field works for every connector?

No. It standardizes the contract, but provider capabilities still differ. Verify required fields, relationships, filters, write actions, and refresh behavior for every connector you plan to support; use raw data, custom fields, field mapping, or passthrough only for documented gaps.

Why are both an API key and an account or connector token required?

The API key identifies your application or organization. The account or connector token identifies the end-user connection whose data the request may access. Together they enforce application identity and tenant-specific data scope.

How does cursor pagination work?

The server returns an opaque cursor in a paginated response. Your client sends that cursor with the next request, keeps all other filters stable, processes and checkpoints the page, and continues until the next cursor is null or missing.

Are webhooks a replacement for polling?

No. Webhooks reduce detection latency, while scheduled polling or reconciliation provides recovery when delivery or processing fails. A sound design uses webhooks to trigger work and periodic pulls to prove that the local store converges.

Should a webhook contain the full record?

That depends on the provider and event type. Design the handler around the documented payload, but prefer using the event as a trusted trigger for an idempotent API pull when correctness depends on the latest normalized record.

How should an initial sync be handled?

Treat it as asynchronous. Show a connecting or syncing state, listen for completion or status changes, handle partial and failed outcomes, then page through the required models into your local database before enabling features that depend on the data.

Where should unified API data live in my application?

For most product workflows, keep an application-owned normalized store. It gives your product predictable read latency, tenant-scoped querying, auditability, and resilience when a provider or sync job is temporarily unavailable.

What is the biggest implementation mistake to avoid?

Do not confuse successful authorization with complete, current data. A production integration needs connection state, sync state, pagination, webhook verification, idempotent upserts, rate-limit handling, and periodic reconciliation as separate concerns.

Source transparency: Most endpoint-level examples in this guide come from Bindbee’s first-party documentation. Merge’s first-party documentation is cited only where it supplies additional cross-category architecture or operational detail.