Skip to main content
Every pass in PassEntry has a UUID, a system-generated identifier that permanently identifies the pass. Passes can also optionally carry an extId (external ID), a value you provide at pass creation to link the pass to a record in your own system. Both can be used to look up, update, or reference a pass via the API. The difference is in how they are assigned, whether they can be reused, and how you typically integrate them with your own records.

​
UUID

  • Generated by PassEntry when a pass is created.
  • Globally unique and immutable for the lifetime of the pass.
  • Always present on every pass.
  • Returned in the API response when you create a pass, and available as %{passData.uuid} in dynamic values.

​
extId

  • Provided by you at pass creation (optional).
  • Links a pass to a record in your own system, for example a CRM contact ID, a membership number, or an order reference.
  • Unique across active passes in your organisation.
  • Freed only via nullification. An extId becomes available for reuse only after the pass that owns it is nullified. See the Pass Nullification guide for details.
  • Convenient as a lookup key: most pass endpoints accept either a UUID or an extId as the pass_id parameter.
Nullification is irreversible, and nullified passes still count towards your billing quota.

​
Two common patterns

Which pattern fits depends on how you handle reissues.

​
extId as the primary key

You use your existing record ID (a CRM contact ID, membership number, or similar) as the pass extId. Your system stores only its own ID; the shared value is the link to PassEntry. Choose this if:
  • Your record is stable and maps 1:1 to a single active pass.
  • Nullifying a pass on reissue is acceptable, including the billing quota impact.
  • You want to look up passes by a meaningful business identifier in the API, webhooks, and notifications.
To reissue: nullify the existing pass, then create a new one with the same extId.

​
UUID stored on your records

You let PassEntry assign a UUID and store it on your record alongside your own ID. Choose this if:
  • A record may link to different passes over time and you want to avoid nullification on reissue.
  • Multiple active passes may coexist for the same record.
  • You want extId available as an optional tag, not a primary key.
To reissue: create the new pass and update the stored UUID. Nullify the old pass if you want, or leave it active.

​
Choosing between them

Ask: when a pass needs to be replaced, is nullifying the existing one acceptable? If yes, using extId as the primary key keeps your integration simpler. If you need the old pass to stay active, or expect multiple passes per record, store the UUID on your records instead. If you are unsure which fits, contact support.

​
Where extId is used across PassEntry

Even when extId is not your primary key, it is useful as a searchable tag on a pass:
  • NFC message source — an NFC-enabled pass can emit its extId when tapped. See the create pass reference for NFC source options.
  • Barcode source — a pass’s barcode can encode its extId. See the localisation guide for configuration examples.
  • Notification dynamic values — use %{passData.extId} in notification content alongside %{passData.uuid}. See the notifications guide.
  • Batch pass creation — the ext_id column in the CSV sets the extId for each pass. See the batch pass creation guide.
  • Batch pass update — the pass_id column accepts either a UUID or an extId. See the batch pass update guide.
  • Filtering — pass list endpoints support extIdPrefix for filtering by extId prefix.