E.164 phone numbers

Every phone number written to Awell has to be in E.164 format: a +, a country calling code, and the national number, with nothing else in between. +16175551212 is accepted; (617) 555-1212 is not. This page gives the rules the API applies and how to convert numbers that arrive in another shape.

The patient profile fields phone (landline) and mobile_phone both take an E.164 string. See Patients for the operations that write them.

E.164 gives a number one written form everywhere

E.164 is an international telephone numbering plan for the worldwide public switched telephone network and some other data networks. It defines a general format for international telephone numbers that ensures each device on the network has a globally unique number, so calls and text messages can be routed to individual phones in different countries.

ISO 8601 does the same job for dates and times. E.164 is the equivalent standard for telephone numbers, and Awell requires it for the same reason: one unambiguous written form per value keeps data interoperable and consistent across every system a care flow touches. 06 17 55 51 21 is a French mobile number written the way someone would type it locally, and it identifies nobody until a reader supplies the country. +33617555121 is the same number, and it needs no context.

The format is fixed: a leading +, then a country calling code of one to three digits, then the national subscriber number. Everything after the + is 15 digits at most.

Validation rules

A phone number passed to the API is subjected to the following validation rules:

1. It contains no whitespace.
2. It starts with a +.
3. Aside from the leading +, it contains only numbers ranging from 0 to 9.
4. It is a possible phone number: 15 digits or fewer, with a correct country code.

A conforming value in a create-patient input:

{
  "input": {
    "mobile_phone": "+16175551212",
    "phone": "+16175551212"
  }
}

A value that fails these rules is rejected rather than stored. See Errors for reading the response.

Awell checks that a number is possible, not that it is real

The check is whether a number is technically possible according to the E.164 format. It is not a check that the number is an actual, working phone number.

+16175550100 can satisfy every rule above and still be unassigned, out of service, or belong to someone other than the patient. Nothing in the format proves a message will arrive, so treat a successful write as a format guarantee only.

Convert to E.164 at the integration boundary

Source systems frequently store numbers the way a person typed them: a national format, sometimes with a separate country column, often with spaces, parentheses, hyphens, or a leading trunk 0. Convert those into E.164 before the API call rather than sending them through as they are.

• Combine the number with its country. E.164 has no meaning without a country calling code. Phone libraries accept a default country alongside a national number and produce the E.164 string from both, which is also how a national trunk prefix such as the leading 0 used across much of Europe gets dropped correctly instead of stripped by hand.
• Store the result, not just the input. Normalizing once on write and keeping the E.164 string in the source system avoids every later call re-deriving it, and makes a bad number visible in one place.
• Send no number rather than a guessed one. A national number with no reliable country context cannot be converted safely: eight local digits identify a different subscriber in every country. In healthcare, a number normalized to the wrong country sends care instructions to a stranger. Leave the field empty, fix the record at source, and send it once it is right.
• Validate before the call, not after. Running the same rules in the integration turns a rejected mutation into a data-quality item on a system that can fix it.

Libraries that format and validate numbers

• libphonenumber-js, for formatting and validating numbers, including conversion to E.164 from a national number plus a country.
• react-international-phone, an international phone input component for React, for collecting a number in E.164 form at the point of entry.

Related

• Manage patients, which covers the rest of the create and update behavior.
• Patients for the operations and fields.
• Errors for how the API reports a rejected write.
• Patient identifiers, the other format convention an integration has to get right before sending patient data.
• Patient Demographics Query, which returns phone and mobile_phone as E.164 strings.