Common Types

Directory API contains multiple resources that use common data types as part of their definition. All these common types can be categorized as either value objects, or identifiable objects.

Value Objects

Value objects are simple entity types that do not have an identity. Contrary to resources, value objects do not support partial updates. This means that when sending an update request that contains value objects attributes, one should include all the populated fields of the said value object in order not to lose previously existing data.

To create a value object, populate the attribute with the relevant fields inside a JSON object.

{
"value-object": {
"field-1": 2244,
"field-2": "John Smith",
"field-3": "Doctor"
}
}

To update an existing value-object, populate the attribute with the relevant fields inside a JSON object.

{
"value-object": {
"field-1": 2244,
"field-2": "John Smith",
"field-3": "Doctor"
}
}

When updating, sending a partial update will result in the loss of data.

// Sending this :
{
"value-object": {
"field-1": 2244,
"field-2": "John Smith",
}
}
// Is equivalent to sending this :
{
"value-object": {
"field-1": 2244,
"field-2": "John Smith",
"field-3": null,
}
}

To delete an existing value object, populate the attribute with null.

{
"value-object": null
}
important

When dealing with arrays of value objects, updating an array will overwrite any previously existing data, so be sure to send all relevant value objects on each update requests.

Address

Value Object

FieldTypeDescription
suite-numberstringSuite, door, appartment number.
street-numberstringStreet number.
routestringStreet name.
postal-codestringPostal code.
districtstringDistrict.
neighborhoodstringNeighborhood.
localitystringLocality.
placestringCity.
regionstringName of the region.
region-codestringISO 3166-2 region code.
countrystringName of the country.
country-codestringISO 3166 country code

Clientele

Value Object

FieldTypeDescription
age-rangesArray<Range>The age ranges of the expected clientele.

Communication

FieldTypeDescription
languagestringISO-639-1 language codes.
preferredbooleanIf the language is a preferred language or not.

Geo Point

Value Object

FieldTypeDescription
latfloatLatitude
lngfloatLongitude

Opening Hour

FieldTypeDescription
dayshortRanges from 1 to 7, representing days of the week from Monday to Sunday as per ISO 8601.
intervalsArray<Interval>Intervals

Interval

Value Object

FieldTypeDescription
startstringStart time of the time interval. Format is HH:mm.
endstringEnd time of the time interval. Format is HH:mm.

Range

Value Object

FieldTypeDescription
idstringIdentifier.
lowerintLower bound of the range age range in months.
upperintUpper bound of the range age range in months. null value is a valid value, which indicates an open-ended range.
labelstringDisplay name for the label. Must be selected from a list of supported labels.

The possible values for label are :
TODDLERS
CHILDREN
PRETEENS
TEENAGERS
ADULTS
ELDERS

important

When creating an age range, one can customize the lower and upper bounds and associate it to a supported label. This allows for a better coverage of edge cases where predetermined age ranges might not match the reality of a service offering. Here are the allowed ranges for each label :

LabelMinimumMaximum
TODDLERS060
CHILDREN72120
PRETEENS132156
TEENS168228
ADULTS240768
ELDERS7801800

For ELDERS, it is recommended to use an open-ended range.


Translation

Value Object

FieldTypeDescription
nameTranslationObjectValue of the translation
wordcloudArray<string>Word cloud associated with this translation

TranslationObject

Value Object

FieldTypeDescription
valuestringTranslated text

Relationship

Value Object

A relationship is a special type of value object. It represents a link between two resources. You will see relationships inside the relationships attribute for all types of resources. Essentially, a relationship describes what is the type of the relationship, and what is the id of the resource targeted by the relationship.

FieldTypeDescription
typestringType of the relation.
idstringId of the resource.
note

The possible values for the type attribute are :

  • health-facilities
  • sectors
  • practitioners
  • walk-ins
  • practices
  • services
  • specialities

Identifiable Objects

When dealing with identifiable objects individually, their behavior is identical to value objects. The only difference is that they possess an id field.

The power of identifiable objects comes when dealing with an array of them. Even though individual identifiable objects do not support partial updates, it is possible to create, update and delete many identifiable objects using a single request. It is also also possible to create, update or delete individual identifiable objects of an array without affecting the rest of the objects.

To add an identifiable object to an array, populate the attribute with an array of identifiable objects without setting their id field.

{
"objects": [
{
"field-1": "5146772888",
"field-2": "999",
"field-3": "MAIN"
}
]
}

To update an existing identifiable object, populate the attribute with an array of identifiable objects and set their respective id field.

{
"objects": [
{
"id": "object-73a34ca4-17c6-4957-beda-ad6a1a2908c1",
"field-1": "5146772888",
"field-2": "999",
"field-3": "MAIN"
}
]
}

To remove an existing identifiable object from an array, populate the attribute with an array of identifiable objects, set their respective id field and remove all other fields from the objects to delete.

{
"objects": [
{
"id": "object-73a34ca4-17c6-4957-beda-ad6a1a2908c1"
}
]
}

To add, update and remove many identifiable objects at once, you can use the same logic with multiple objects

{
"objects": [
{
// Create new identifiable object
"field-1": "5146772888",
"field-2": "999",
"field-3": "MAIN"
},
{
// Update existing identifiable object
"id": "object-73a34ca4-17c6-4957-beda-ad6a1a2908c1",
"field-1": "5146772888",
"field-2": "999",
"field-3": "MAIN"
},
{
// Delete existing identifiable object
"id": "object-a2df9df9-447b-4e2d-98f7-78811b40471d"
}
]
}

Booking Detail

Identifiable Object

FieldTypeDescription
idstringIdentifier.
phonePhonePhone number to call for booking.
online-bookingOnlineBookingOnline method for booking.
appointment-opening-timestringTime at which the booking window opens on a given day. Format is HH:mm
appointment-opening-daystringDay at which the booking window opens.
appointment-patient-accessstringEnumeration describing of this booking method is for new patients or existing patients only. If the booking method is for both new and existing patients, then use NEW_PATIENTS.
notestringNotes.

The possible values for appointment-opening-day are :
TODAY
TOMORROW
ANY_DAY

The possible values for appointment-patient-access are :
EXISTING_PATIENT
NEW_PATIENT

note

The combination of appointment-opening-time and appointment-opening-day defines when a patient can book a new appointment for the next day.

Examples :

To book an appointment, a patient can call from 13h00 on a given day and should only expect availability for the next day at the earliest.

{
"appointment-opening-time": "13:00",
"appointment-opening-day": "TOMORROW"
}

To book an appointment, a patient can call from 8AM on a given day and can expect availibility for the same day.

{
"appointment-opening-time": "08:00",
"appointment-opening-day": "TODAY"
}

A patient can call anytime and we will find availibility based on our schedule.

{
"appointment-opening-time": null,
"appointment-opening-day": "ANY_DAY"
}
important

Booking detail contains a phone and an online-booking field which are both identifiable objects, but that act here as value objects. This means that for all intent and purposes, their id field should be ignored.

// Update phone and online booking
{
"booking-detail": {
...
"phone": {
"number": "4505555050",
"type": "MAIN"
},
"online-booking": {
"url": "https://clinic.ca/registration",
},
...
}
}
// Delete phone and online booking
{
"booking-detail": {
...
"phone": null,
"online-booking": null,
...
}
}

Phone

Identifiable Object

FieldTypeDescription
idstringIdentifier.
numberstringThe phone number.
extensionstringThe extension of the phone number.
typestringThe type of phone.

The possible values for type are :
MAIN
ALTERNATE
RECEPTION
FAX
TEXT_TELEPHONE_TTY
INFO
PAGER
MOBILE
HOME
WORK
PERSONAL
APPOINTMENT


Email

Identifiable Object

FieldTypeDescription
idstringIdentifier.
addressstringThe email address.

Online Booking

Identifiable Object

FieldTypeDescription
idstringIdentifier.
urlstringThe url.

Practitioner Registration

Identifiable Object

FieldTypeDescription
idstringIdentifier.
practice-numberstringRegistration number.
region-codestringISO 3166-2 region code.

Social

Identifiable Object

FieldTypeDescription
idstringIdentifier.
urlstringUrl representing the link.