Phone Number Filtering Reference

Overview

The number parameter on the /api/v1/phone_numbers/ endpoint supports flexible
filtering across both stored number formats: NANP (NNN-NNN-NNNN) and E.164
(+XNNNNNNNNNN). Wildcard characters and digit-only input are both supported, with
automatic format normalisation applied where possible.

Wildcard Characters

Two wildcard characters are supported. They may appear at the start, end, or both
ends of the search term. They cannot appear in the middle of a value.

Character	Meaning	ORM Lookup
`*`	Match anything	Recommended
`%`	Match anything	Supported, but must be submitted as `%25` in a URL to avoid percent-encoding conflict. Use `*` instead.

Wildcard Position	Example Input	ORM Lookup
Leading only	`*5555`	`ends with`
Trailing only	`111*`	`starts with`
Both ends	`222`	`contains`
None	`111-222-5555`	`exact`

Input Normalisation

When the search term (after stripping any wildcard characters) is purely numeric,
the API automatically generates additional format candidates and OR's them together,
so a single query can match records stored in either NANP or E.164 format.

Non-numeric input (containing dashes, +, spaces, or letters) is used as-is with
no normalisation.

10-Digit Input

Treated as a full NANP subscriber number. Two candidates are generated:

Candidate	Format
`NNN-NNN-NNNN`	NANP (dash-formatted)
`+1NNNNNNNNNN`	E.164 with `+1` country code

Examples:

Query Parameter	Candidates Searched
`?number=1112225555`	`111-222-5555` OR `+11112225555`
`?number=*2225555`	`ends with` on `222-5555` OR `2225555`

11 to 15-Digit Input

Treated as E.164 digits without the + prefix. A + is prepended for the E.164
candidate. If the leading digit is 1 and the total length is 11, the 10 subscriber
digits are also checked as NANP.

Candidate	Condition
`+NNNNNNNNNNN`	Always generated
`NNN-NNN-NNNN`	Only when leading digit is `1` and length is exactly 11

Examples:

Query Parameter	Candidates Searched
`?number=11112225555`	`+11112225555` OR `111-222-5555`
`?number=441112225555`	`+441112225555` (non-NANP country code, no NANP candidate)
`?number=*11112225555`	`ends with` on `+11112225555` OR `111-222-5555`

Other Digit Lengths (Partial Input)

Input that is purely numeric but outside the 10-15 digit range is treated as a
partial number. The raw digits are used as one candidate, and a dash-formatted
version (with dashes inserted at NANP boundaries from the right) is added as a
second candidate where the input is long enough.

NANP dash boundaries from the right: position 4 (last 4 digits) and position 8
(digits 5-7 from the right).

Digit Count	Dash Candidate Generated	Example Input	Candidates
8-9 digits	Yes (two boundaries)	`222555123`	`222555123` OR `2-225-55123`
5-7 digits	Yes (one boundary)	`2225555`	`2225555` OR `222-5555`
4 digits	No (too short)	`5555`	`5555` only
1-3 digits	No (too short)	`555`	`555` only

Note: Partial digit input without a wildcard uses exact matching, which
means neither candidate is likely to match a full NANP or E.164 stored value.
Use a leading * for suffix matching when searching with fewer than 10 digits.

Non-Numeric Input

Input containing any non-digit character (dashes, +, spaces, letters) is passed
through as-is with no normalisation. Only one candidate is generated.

Examples:

Query Parameter	Candidate Searched	Lookup
`?number=111-222-5555`	`111-222-5555`	`exact`
`?number=*222-5555`	`222-5555`	`ends with`
`?number=+11112225555`	`+11112225555`	`exact`
`?number=+1111`	`+1111`	`contains`

Quick Reference

Goal	Recommended Query
Exact match, full NANP number	`?number=111-222-5555`
Exact match, full 10-digit no dashes	`?number=1112225555`
Exact match, E.164	`?number=+11112225555`
Suffix match on last 7 digits	`?number=*2225555`
Suffix match on last 7 digits with dashes	`?number=*222-5555`
Contains a 3-digit area code	`?number=111`
Starts with area code (NANP)	`?number=111*`
Match any number for a country code	`?number=+44`