Skip to content
Help Center
Submit a request Sign in

Tags

Configure record ID mappings

Updated Monday, October 26, 2026 · Marc Staine

ID mappings define recognizable identifier prefixes for supported records. Choose stable prefixes early so agents, customers and integrations can refer to records consistently.

Applies to: Supportbench Core. Location: Settings → API → Id mapping. Access and available controls depend on your role and account capabilities.

Before you begin

  • You need permission to edit this configuration. Ask an administrator if the page is available but its editing controls are not.
  • Review the current configuration and where it is used before making a change. Available choices depend on your account, enabled modules, division access and role.
  • Use a test record or a controlled test account for behavior checks. Do not change production routing or send customer messages just to try an example.

Configure and verify

  1. Open Settings → API → ID mapping.
  2. Review existing mappings and select the supported new-mapping action.
  3. Choose the prefix, record type and description carefully.
  4. Save and reopen the mapping.
  5. Inspect a controlled record using the mapping before configuring any dependent customer role or integration.

Settings reference

Mapping definition

SettingWhat it controlsHow to choose
PrefixRequired prefix of 1–5 characters; cannot be changed after creation.Choose a short, distinct prefix you can retain.
Record typeCase, Article, Asset, Company or Contact. Can be changed only before references exist.Choose the correct type before any records use the mapping.
DescriptionExplanation up to 250 characters.Document the intended use and owner.

Behavior to know

  • System mappings are protected. Prefixes are immutable after creation, and record-type changes are restricted once references exist.
  • Deletion is permanent. Review every dependency before using a delete action.

Recommended use

  • Use terminology that agents and customers already understand. Explain the intended meaning in the description.
  • Keep the initial configuration small enough for people to choose consistently. Add options when they represent a real operational difference.
  • Review existing references before renaming, changing scope, or deleting. Where supported, deactivate an obsolete option before considering permanent deletion.

Worked example

  1. Choose a distinct short case prefix for a supported customer-role use case.
  2. Create the Case mapping and verify it.
  3. Select the existing mapping in the appropriate customer role; do not enter an unrelated freeform prefix there.

Troubleshooting

ProblemWhat to check
The item is missing from a picker.Check Active, division access, parent hierarchy, enabled modules, and the user’s role. Reopen the consuming form after saving.
The form rejects a save.Read the displayed validation message. Check required values, text limits and permitted scope; do not change unrelated settings to bypass validation.
An existing record still shows an old value.A configuration change and a record change are different operations. Inspect the record and relevant references before assuming the save failed.
  • Customers → Configure customer roles
  • API → Find record IDs for API configuration

Was this article helpful?