API Standards

The Hyperion API adheres to widely adopted RFCs and ISO standards for data formats. This page documents each standard, explains how it applies to the API, and provides examples of valid and invalid values.

Phone numbers (E.164)

All phone number fields follow the ITU-T E.164 international telephone numbering format.

Phone numbers must start with a + followed by the country code and subscriber number, with no spaces, hyphens, or parentheses. The maximum length is 15 digits (including the country code).

Value	Valid	Reason
+14155552671	Yes	US number with country code 1
+442071838750	Yes	UK number with country code 44
+5511998765432	Yes	Brazil number with country code 55
(415) 555-2671	No	Contains parentheses, spaces, and hyphens
415-555-2671	No	Missing + prefix and country code
+0123456789	No	Country code cannot start with 0
14155552671	No	Missing + prefix

JSON

1{
2  "phoneNumber": "+14155552671"
3}

Country codes (ISO 3166-1)

Country fields use ISO 3166-1 alpha-2 two-letter country codes.

Value	Valid	Reason
US	Yes	United States
CA	Yes	Canada
DE	Yes	Germany
USA	No	Alpha-3 code; the API requires alpha-2
us	No	Must be uppercase
United States	No	Full name not accepted

JSON

1{
2  "country": "US"
3}

State and province codes (ISO 3166-2)

State and province fields use ISO 3166-2 subdivision codes in the format {country}-{subdivision}.

Value	Valid	Reason
US-CA	Yes	California, United States
US-DC	Yes	District of Columbia
CA-ON	Yes	Ontario, Canada
CA	No	Missing subdivision code
California	No	Full name not accepted
us-ca	No	Country prefix must be uppercase

JSON

1{
2  "country": "US",
3  "state": "US-NY"
4}

Timestamps (ISO 8601 / RFC 3339)

All timestamp fields use ISO 8601 format as profiled by RFC 3339. Timestamps are always in UTC, indicated by the Z suffix.

Value	Valid	Reason
2024-02-17T10:45:23Z	Yes	Standard UTC timestamp
2024-02-17T10:45:23.123Z	Yes	With millisecond precision
2024-02-17T10:45:23.123456Z	Yes	With microsecond precision
2024-02-17T10:45:23+00:00	Yes	Explicit UTC offset
2024-02-17	No	Missing time component
2024-02-17 10:45:23	No	Space instead of T separator
02/17/2024	No	Not ISO 8601 format
1708166723	No	Unix timestamp not accepted

JSON

1{
2  "createdAt": "2024-02-17T10:45:23Z",
3  "updatedAt": "2024-02-17T14:30:00.000Z"
4}

Language tags (BCP 47)

Language and locale fields use BCP 47 language tags as defined in RFC 5646. Tags consist of a lowercase ISO 639-1 language code followed by an uppercase ISO 3166-1 region code, separated by a hyphen.

Value	Valid	Reason
en-US	Yes	English (United States)
es-US	Yes	Spanish (United States)
es-MX	Yes	Spanish (Mexico)
fr-CA	Yes	French (Canada)
pt-BR	Yes	Portuguese (Brazil)
en_US	No	Underscore instead of hyphen
EN-us	No	Language must be lowercase, region uppercase
english	No	Full language name not accepted

JSON

1{
2  "preferredLanguage": "en-US"
3}

Postal codes (USPS)

For US addresses, postal code fields accept standard USPS 5-digit ZIP codes or 9-digit ZIP+4 codes with a hyphen separator.

Value	Valid	Reason
94102	Yes	Standard 5-digit ZIP
94102-1234	Yes	ZIP+4 format
9410	No	Fewer than 5 digits
941021234	No	ZIP+4 missing hyphen
94102-123	No	ZIP+4 extension must be 4 digits
ABCDE	No	Must be numeric

JSON

1{
2  "postalCode": "94102-1234"
3}

Identifiers (UUID)

All resource identifiers use RFC 9562 Universally Unique Identifiers (UUIDs) in their canonical lowercase string representation.

Value	Valid	Reason
550e8400-e29b-41d4-a716-446655440000	Yes	Standard UUID format
550e8400e29b41d4a716446655440000	No	Missing hyphens
550e8400-e29b-41d4-a716	No	Incomplete UUID
not-a-uuid	No	Invalid format

JSON

1{
2  "id": "550e8400-e29b-41d4-a716-446655440000",
3  "partnerId": "123e4567-e89b-12d3-a456-426614174000"
4}

Currency codes (ISO 4217)

All monetary amounts include a currency field using ISO 4217 three-letter currency codes.

Value	Valid	Reason
USD	Yes	United States Dollar
CAD	Yes	Canadian Dollar
MXN	Yes	Mexican Peso
usd	No	Must be uppercase
US	No	Must be a 3-letter code
$	No	Currency symbols are not accepted

JSON

1{
2  "fee": {
3    "amount": 50,
4    "currency": "USD"
5  }
6}

Durations (ISO 8601)

Duration and period fields use ISO 8601 duration format. Durations start with P (period) followed by date components, or PT for time-only components. The API uses durations for familiarization periods, multi-zone timing windows, responsible party response times, and permit or notice fee cadence (frequency on fees and renewals).

Value	Valid	Meaning
P7D	Yes	7 days (common familiarization period)
P5D	Yes	5 days
P15M	Yes	15 minutes (multi-zone activation or RP response window)
P30M	Yes	30 minutes (responsible party response window)
P1Y	Yes	1 year (also used for annual fees or renewals)
P3M	Yes	3 months (quarterly fees or renewals)
PT0S	Yes	Zero-length period (one-time fee or non-recurring renewal)
7	No	Missing P prefix
7D	No	Missing P prefix
P	No	No duration component specified

JSON

1{
2  "period": "P7D",
3  "renewal": {
4    "frequency": "P1Y"
5  }
6}

Error responses (RFC 9457)

All error responses follow RFC 9457 Problem Details for HTTP APIs. For the full error response format, status codes, and validation error structure, see the Errors page.

Standards reference

Standard	Specification	Fields
ITU-T E.164	ITU-T E.164	phoneNumber
ISO 3166-1 alpha-2	ISO 3166	country
ISO 3166-2	ISO 3166	state
ISO 4217	ISO 4217	currency
ISO 8601 / RFC 3339	ISO 8601 / RFC 3339	createdAt, updatedAt, observedAt, effectiveAt, expiresAt
ISO 8601 Durations	ISO 8601	period, fee and renewal frequency
BCP 47 / RFC 5646	BCP 47 / RFC 5646	preferredLanguage
USPS ZIP Code	USPS	postalCode
RFC 9562	RFC 9562	id, partnerId, monitorableId, entityId
RFC 9457	RFC 9457	Error responses