Skip to content
Help Center
Submit a request Sign in

Configure record ID mappings

Define a recognizable short prefix for a supported record type while preserving stable record identities. Prefixes cannot be renamed after creation. Plan the convention before using it in customer-facing case numbers or integrations, and configure any Customer-role assignment separately.

Applies to: Supportbench Core. Location: Settings → API → Id mapping. Requires Administer API configurations.

Before you begin

  • Identify the record type and future use. A prefix distinguishes an ID; it does not establish case routing, an SLA, a Division or portal access.
  • Check existing and reserved prefixes and any integration convention. Choose a prefix you can retain permanently rather than expecting to rename issued IDs later.
  • For customer-created case prefixes, identify the intended Customer role and Company context. Creating the mapping alone does not assign it to that role.

Configure and verify

  1. Open Settings → API → Id mapping and inspect the existing mappings.
  2. Choose New mapping. Enter a unique Prefix of 1–5 characters, select Used for and add an optional administrator Description of up to 250 characters.
  3. Select the exact type: Case, Article, Company, Contact or Asset. Recheck it before any records or roles refer to the mapping.
  4. Choose Save Changes. Confirm the row appears, then reopen it and inspect the saved prefix, type and description.
  5. If using the prefix for customer-created cases, separately configure the intended Customer role’s Case ID mapping. Follow the Company/Customer-role procedure and test a new case under the intended context.
  6. For an existing unprotected mapping, edit the description as needed. The saved Prefix is disabled. Used for can change only before references exist.
  7. Consider Delete only for an unprotected mapping with no record or Customer-role references. Deletion is permanent; there is no deactivate control. Do not remove dependencies simply to bypass an in-use check.

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.
Used forCase, 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 and integration mappings are protected from editing/deletion. Prefixes are immutable after creation.
  • References in Cases, Articles, Companies, Contacts, Assets or Customer roles prevent deletion and constrain type changes. Review the owning reference rather than guessing why a control is locked.
  • A mapping change does not rewrite issued IDs. A Company/Customer-role change affects new case creation according to the documented creation path.

Recommended use

  • Choose a small stable convention and describe its operational owner. Avoid encoding a temporary team name or campaign that would soon need renaming.
  • Verify the selected type and intended role assignment using a controlled new record. Existing cases are unsuitable evidence for a newly assigned creation prefix.
  • If the prefix was created incorrectly, retain issued identities and choose another unused prefix for future use. Coordinate API consumers and customer communication before adopting a new convention.

Worked example

  1. A B2B team wants a recognizable prefix for newly created customer cases. It first checks the existing mapping list and chooses a distinct short prefix for Case.
  2. The administrator creates and reopens the mapping, then configures the intended Customer role separately.
  3. Using an approved test customer context, the team creates a new case and checks the final ID. It verifies that historical case IDs are unchanged.
  4. If the result differs, the team reviews creation timing and role selection before changing unrelated routing or attempting to rename the prefix.

Troubleshooting

ProblemWhat to check
Prefix is rejectedCheck the 1–5 character requirement, uniqueness and reserved values. Use the exact validation message to resolve the choice.
I cannot rename a saved PrefixSaved prefixes are immutable. Plan a different unused mapping for future use and preserve issued IDs.
Used for is lockedThe mapping has references or is protected. Review its records and Customer-role use; do not assume the control is malfunctioning.
Delete reports that the mapping is in useInspect record and Customer-role references. There is no deactivate action and deletion is not a safe substitute for preserving required identities.
The new prefix does not appear on an existing caseIssued IDs are not rewritten. Test the intended creation path on a new controlled case and review its Company/Customer-role context.
The page or New mapping is unavailableVerify Administer API configurations. Editing Companies or Customer roles does not by itself grant this administration permission.
  • Customers → Configure customer roles
  • API → Find API IDs for queues, statuses, agents and custom-field choices

Was this article helpful?