Shared Objects

Several object types in the Hint API share a consistent structure wherever they appear. Rather than defining unique schemas for each parent resource, objects like phones and addresses follow the same format whether they belong to a patient, practice, or company.

This page documents these shared structures so you can handle them uniformly in your integration code.

Phones

Phone numbers appear as an array on patients, practices, and other resources. Each phone object has the same structure:

Field	Type	Description
`number`	string	The phone number (formatting varies by input)
`type`	string	Label for the phone (e.g., "home", "mobile")
`us_formattable`	boolean	Whether the number follows the US 10-digit format

{
  "phones": [
    { "number": "5551234567", "type": "mobile", "us_formattable": true },
    { "number": "+442079460958", "type": "office", "us_formattable": false }
  ]
}

US vs international formatting

The us_formattable field controls how Hint validates and stores the phone number:

true - The number is treated as a US phone number following the 10-digit plan. It must be exactly 10 digits without the leading +1 country code.
false - The number is treated as international, allowing additional characters like + for country codes.

Phone type normalization

Hint normalizes phone types to lowercase and maps common variations to canonical values. This means the type you receive back may differ from what you submitted.

Case normalization - All types are lowercased before storage:

Input	Stored as
`home`	`home`
`HOME`	`home`
`Home Phone`	`home`
`SomethingElse`	`somethingelse`

Canonical mapping - Common variations map to standard types:

Input variations	Stored as
`h`, `home phone`	`home`
`m`, `mobile phone`, `cell`, `cellphone`, `cell phone`, `cellular`	`mobile`
`w`, `work phone`, `business`, `business phone`, `company`, `company phone`	`office`

Any type not in this mapping is stored as-is (lowercased).

Addresses

Address fields are embedded directly on resources like patients, practices, companies, and locations using an address_ prefix:

Field	Type	Description
`address_line1`	string	Street address line 1
`address_line2`	string	Street address line 2 (optional)
`address_city`	string	City name
`address_state`	string	State or province code
`address_zip`	string	Postal code
`address_country`	string	Country name (optional)

{
  "address_line1": "157 E Houston St",
  "address_line2": "Suite 2402",
  "address_city": "New York",
  "address_state": "NY",
  "address_zip": "10002",
  "address_country": "United States"
}

📘
Address handling
Hint does not perform full address validation or standardization. However, state values are normalized to two-character state codes (e.g., "California" becomes "CA").