Some Remote resources have a partner_external_id field. Use it to store your own reference on a Remote record, such as the ID of a timesheet line or an employee in your system. You can then find the record by that value later, without storing Remote's IDs.

Resources that support it: employments and pay items.

📘
Sending time and attendance to payroll?
This field is what lets you resend pay items without creating duplicates. See Sync time and attendance to payroll with your own IDs for each case: retries, changes, deletes and corrections.

🚧
Availability
On pay items, partner_external_id is being rolled out. Until it is turned on for you, sending it fails with "partner_external_id is not available", filtering by it returns 400 "The partner_external_id filter is not available.", and pay item responses don't include it. Ask your Remote contact.

Private to your integration

We work out your integration from the credentials you call the API with. No other integration can read or overwrite your value, and you can't see theirs.

Customer API tokens and MCP clients. If you call the API with a Customer API token (see Authorization for customers) or an MCP client, all tokens and MCP clients of your company share one set of values. If several of your systems write values, add a prefix per system, for example erp:4711 and ats:93.
Partner integrations. If your company also uses a partner integration (for example an HRIS that onboards employees for you), that partner's values and yours are kept apart. Neither of you sees the other's.

Set, change, clear

When you create a record one at a time, or update it with PATCH:

You send	What happens
The field with a value	The value is set, or replaces the old one
`null`, an empty string or only spaces	The value is cleared
Nothing (the field is left out)	The value stays as it is

On POST /v1/pay-items/bulk there is nothing to clear: null or an empty string fails that item.

A value can be up to 64 characters, counting any spaces you send around it. We then trim those spaces before we store it. Matching is exact, including upper and lower case.

Uniqueness depends on the resource

Pay items: one live pay item per value in your company. A pay item is live until it is deleted. When Remote replaces it with a new version (see Records Remote replaces), the new version is the live one. On PATCH, a value another live pay item already holds is refused with a validation error on partner_external_id. On bulk, the same value updates the pay item that holds it (see below).
Employments: the same value may be used on several employments, for example when someone is rehired.

Find a record by your value

GET /v1/pay-items?partner_external_id=TS-0042 returns the live pay item that holds TS-0042 for your integration.
GET /v1/employments?partner_external_id=EMP-17 returns every employment that holds EMP-17. There can be more than one.

Values held by other integrations are never matched.

Create or update pay items in one call

On POST /v1/pay-items/bulk, each item is handled on its own:

The item sends	What happens
No `partner_external_id`	Creates a new pay item. Sending the same item twice creates two.
A value no live pay item holds	Creates a new pay item that holds it
A value a live pay item holds	Updates that pay item, under the same rules as `PATCH`. Fails with `partner_external_id_held_by_other_pay_item` when that pay item belongs to another employment or pay code.
`null` or an empty string	The item fails

Each value may appear once per request. A later item that repeats a value fails, and its error names the earlier item that used it, for example "is already used by pay item 0 of this request". Items are counted from 0.

Records Remote replaces

When you edit a pay item before payroll cutoff, Remote may replace it with a new version that has a new id. Your partner_external_id moves with it to the live version, so you can keep sending the same value. The old Remote IDs keep working too: PATCH and DELETE on any ID we returned act on the current version.

Deleted records

Deleting a pay item frees its value. A later pay item can then take the same value. PATCH or DELETE on the deleted pay item's ID returns 404 with the message "Pay item not found because it was deleted".