
Portal Reference Numbers: Make Records Easy to Find Without Granting Access
Design portal reference numbers for human communication, stable lookup, concurrent creation, and authorization that remains independent of knowing the identifier.
Custom Portals
Keep portal reference codes intact through text input, validation, lookup, import, and export without losing zeros or inventing equivalence.

LET’S BUILD SOMETHING USEFUL
Talk to Ataraxy Developers about your website, app, or custom software.
A vendor enters reference code 004281 into a portal. The browser accepts it, but an API converts it to the number 4281. An export later contains the shorter value, and the vendor cannot match it to the code printed on its document. The system preserved a quantity that nobody intended to submit.
Identifiers can contain digits without being numbers in the arithmetic sense. A customer reference, equipment code, or postal identifier may depend on leading zeros, case, separators, or fixed length. Designing the field as text is a starting point; preserving its meaning requires a consistent contract across the entire workflow.
Begin with the issuing system’s rules. Is 004281 different from 4281? Are letters case-sensitive? Are spaces only visual separators, or are they part of the code? Can the identifier change after a record is created? Do not apply a formatting convention from an unrelated field just because both contain digits.
Write examples of valid, invalid, and equivalent values. For a hypothetical supplier reference, the team might require exactly six digits and preserve all six. For an equipment code, it might allow letters and hyphens. Keep these contracts separate so a universal “clean number” helper cannot strip meaningful information from either field.
Distinguish the external identifier from the portal’s internal record key. Several suppliers may use the same reference within their own systems. The portal can store supplier context alongside the reference rather than forcing every external code to be globally unique. Authorization should determine which supplier records a user may look up.
The HTML input specification explains that number inputs are inappropriate for digit-based identifiers such as credit card numbers or US postal codes when numeric incrementing is not meaningful. A text input with an appropriate keyboard hint can better fit the task. The field type should express what the value is, not merely which characters are common.
The HTML forms guidance distinguishes input mode from input type and other form semantics. A numeric keyboard hint can help entry without turning the value into a number. Validation still needs an explicit rule; a keyboard hint does not establish that the submitted text is valid or authorized.
Keep labels visible and provide a concrete example in help text. For the supplier reference, explain that leading zeros are required and show a fictitious six-digit example. Do not use a placeholder as the only instruction, because it disappears while the user types and may be unavailable when they review an error.
Inspect the browser form model, JSON schema, server parser, database column, and export mapping. Each should carry the identifier as text under the agreed contract. A correct input control cannot protect the value if the server later casts it to an integer or a spreadsheet generator writes it as a numeric cell.
Use serialization tests that compare exact characters. Submit 004281, read the saved record, open its detail page, and export it. Verify that the complete value survives each step. Include copy and paste, bulk import, and administrative edits, because these routes often bypass the interactive form’s helper functions.
Avoid adding or removing formatting without a rule. If the product displays spaces for readability, retain a documented canonical comparison form and make the conversion reversible where required. If the code contains a check digit, validate it using the actual issuing scheme rather than an invented checksum that merely appears plausible.
Trimming accidental outer whitespace may be appropriate for one identifier, while preserving internal spaces is essential for another. Decide explicitly. If a normalization changes the value the user entered, consider showing the interpreted form before submission, especially where a mismatch could attach a document to the wrong record.
Do not silently substitute similar-looking characters. Replacing the letter O with zero or the letter I with one can create a valid but wrong code. Instead, explain the allowed character set and point to the questionable position where useful. A person should be able to correct the entry using the original document.
Review Unicode digits and punctuation according to the domain. If an external system accepts only ASCII digits, tell users clearly and provide a controlled conversion only when its meaning is established. Avoid rejecting a person’s name or unrelated free-text field because a strict identifier rule was accidentally applied to the whole form.
A syntactically valid identifier may not exist, may belong to another supplier, or may be inaccessible to the current user. Validate format separately from authorized lookup. Do not reveal private record details simply because someone guesses a code that passes a six-digit pattern.
Keep error messages helpful within the permitted scope. The portal can say that it could not find an accessible record matching the entered reference and offer a safe correction path. For users authorized to manage the supplier’s records, show enough context to distinguish similar references before attaching files or submitting approvals.
If a lookup returns several legitimate matches, require a deliberate selection using additional authorized information. Do not choose the first result automatically. A reference copied from a document may need its issuer, project, or year to identify the intended record. Capture that context in the data model rather than relying on hidden sorting behavior.
Import previews should show the exact identifier that will be stored and flag values whose zeros were already lost before upload. If the original file supplies 4281 and the contract expects six digits, do not automatically pad it unless the issuing rule guarantees that interpretation. Ask for correction or a reviewed mapping when the source is ambiguous.
For spreadsheet exports, use text cells for identifiers and keep formula-handling protections appropriate to the export format. An identifier’s textual nature does not make arbitrary content safe to interpret as a spreadsheet formula. Review the export path independently from the field’s browser validation.
AI or OCR extraction can assist with reading a reference from a scanned document, but it should expose uncertainty around similar characters and leading zeros. Show the source crop and extracted text for confirmation before linking the document to a portal record. Retain the confirmed value and provenance so a later mismatch can be investigated.
Keep examples with leading zeros, maximum length, meaningful separators, invalid characters, and ambiguous matches. Run them through entry, lookup, editing, import, and export. Add a case from each production defect after correcting it, using synthetic data that demonstrates the same failure without retaining customer secrets.
An identifier’s meaning comes from its issuing rules and context. Preserve it as text, define normalization deliberately, and verify exact values across every boundary. Combine useful entry controls with authorized lookup and reviewable extraction so the portal connects people to the intended record without silently changing the code they supplied.
LET’S BUILD SOMETHING USEFUL
Talk to Ataraxy Developers about your website, app, or custom software.