External IDs & Mapping to Salsa

Overview

When integrating your platform with Salsa, one of the most important concepts you'll use is the External ID. This field exists on several core Salsa entities-such as Employer, Worker, Address, **Bank Account

• and more (see each entity's API reference to confirm support; entities that support External IDs will include an optional externalId string field)**, and others-and provides a first-class way to map entities in your system to their corresponding entities in Salsa.

External IDs are a simple but powerful mechanism for maintaining stable, bi-directional references between systems, enabling safer syncing, easier lookups, and built-in idempotency during entity creation.

What Is an External ID?

An External ID is a string field on select Salsa entities that:

• Is optional (empty by default).
• Is unique within the namespace of the entity type.
• Is provided and owned by you, the integrating partner.
• Is treated as durable, first-class data across APIs, webhooks, and internal workflows.

Example mapping:

This creates a stable, durable mapping that Salsa preserves.

Why Use External IDs?

Reliable Entity Mapping

You may already maintain your own mapping tables for various reasons, but External IDs provide an additional first-class way to embed your system's identifier directly in Salsa, simplifying certain integration patterns.

Better Syncing & Webhook Processing

External IDs appear in API responses and webhook payloads, allowing your system to process data and events using your own identifiers.

Idempotent Creation & Duplicate Prevention

When creating an entity, pass its External ID. If the ID already exists, Salsa returns a unique constraint error-preventing duplicates. This makes repeated create attempts safe and predictable.

Where External IDs Are Available

External IDs are supported on several core Salsa entities, including:

• Employer
• Worker
• Address
• Bank Account
• …and additional entities; refer to the API reference for each entity to confirm whether it supports externalId.

Each entity type maintains its own unique namespace.

Namespace & Uniqueness Rules

• Uniqueness is enforced per entity type.
• If not provided, Salsa simply leaves the field empty.

What “uniqueness per entity type” means

Each entity type that supports External IDs maintains its own independent uniqueness namespace. For example, all Workers share one global uniqueness namespace for externalId, all Employers share another, all Bank Accounts share another, and so on.

This means that even if two Workers belong to different Employers, their externalId values must still be unique across all Workers.

Examples

• Valid: Worker external IDs wrk_1, wrk_2, wrk_3
• Invalid: Worker A has external ID 17 and Worker B (under a different Employer) also uses 17 — this will trigger a uniqueness violation.

If your identifiers are globally unique (such as UUIDs), this requirement usually requires no additional effort.

Working with locally scoped IDs

If your platform uses identifiers that are only unique within a single context (such as Worker IDs scoped to an Employer), you will need to ensure global uniqueness before passing them to Salsa. A practical approach is to construct a composite External ID.

Recommended approach: prefixing or composite IDs

You can combine an Employer’s External ID (or another unique employer identifier) with the locally scoped Worker ID. For example:

This ensures:

• Globally unique Worker External IDs
• Stable 1:1 mappings between your system and Salsa
• Easy reverse lookup and clarity about origin

Other approaches

You may additionally:

• Hash the composite key
• Generate a stable GUID
• Use any deterministic method that guarantees uniqueness

Regardless of strategy, the important part is that uniqueness is enforced globally per entity type, not scoped to parent objects like Employers.

Best Practices

• Use External IDs for any entities you want to maintain a stable 1:1 mapping with Salsa, regardless of which system owns the data or whether the entity is read-only on your side.
• Use them for webhook routing, leveraging your own stable identifiers.
• Use them for idempotent creation during sync processes.
• Do not use them as metadata-they should remain stable identifiers, not descriptive or transient values.

Example Integration Flow

1. Create an Employer

Here is an example specifying the externalId while creating an Employer via the Paystream Import Employers endpoint.

POST /rest/v1/paystream/employers
{
  "data": [
    {
      "type": "PaystreamEmployerUpsertInput",
      "businessInfo": {
        "country": "USA",
        "businessName": "Acme Corp"
      },
      "externalId": "acct_123"
    }
  ]
}

2. Store Salsa's Employer ID

While the External ID is not set on the Salsa side, it is still the best practice to store Salsa's ID for the created Employer in your database as well, associated with the record on your side represented by the External ID value you specified.

3. Process a Webhook

Here is an example of a PayrollRun.awaitingInput type event that you will receive, with the External ID of the Employer included in the employerExternalId field. With this, you can route your webhook handler logic based on the External ID alone, if that is preferable for you.

{
  "data": {
    "type": "PayrollRun.awaitingInput",
    "attributes": {
      "category": "LIFECYCLE",
      "employerId": "er_42dd7cb4-0de6-49d9-8901-b317d16c07ad",
      "employerExternalId": "acct_123",
      "payPeriod": {
        "startDate": "2025-11-17",
        "endDate": "2025-11-23"
      },
      "workerIds": [
        "wr_e8c9cd00-c87d-40f3-b5bc-38ceae9480d3",
        "wr_5d5801e4-bae3-4f2d-80bf-6beecbfab471"
      ]
    }
  }
}

This allows your system to match the event to acct_123 without additional lookup steps.

Summary

External IDs give you a consistent, first-class mechanism for maintaining entity mappings between your platform and Salsa. They enhance reliability, simplify syncing, improve webhook handling, and provide built-in idempotency. We recommend using External IDs for any entity your system creates or manages.