Order Attributes

Request Payload Attributes

In this section we will provide details of the order request payload attributes and properties.

Attribute	Type	Description
orderType	string	(Optional) An Indication on how the order should be fulfilled by Human API and what kind of medical reports should be delivered. The value of this field must be a supported order type. If omitted, Human API will apply the default order type which was pre-configured for your application.
clientUserId	string	(Required) Your unique identifier of the user, such as the policy number.
clientUserEmail	email	(Required) A valid contact email address for the user
firstName	string	(Optional) First name
middleName	string	(Optional) middle name
lastName	string	(Optional) Last name
dateOfBirth	date	(Optional) Date of birth Format: ISO 8601
gender	string	(Optional) the user’s gender `male` or `female`
suggestedSources	array	(Optional) A list of provider names, which we will include in communications with the applicant.
conditions	array	(Optional) A list of underlying conditions or risk factors that rise to the point of concern for underwriting. This data is used by Human API to optimize data processing and presentation of medical data to the underwriters.
clientData	object	(Optional) You can send additional information along with the request that can be saved with the order. This must be a valid JSON object with no nesting. This data will be ignored by the HumanAPI platform, but can be used for troubleshooting and analytics at a later time. This field has char limit of 2048
ssn	string	(Optional) The applicant’s social security number. Must be a valid US social security number.
phone	string	(Optional) a valid North American phone number.
address	object	(Optional) The current address of the newly created user. See Address object specifications below.
providers	array	(Optional) a list of healthcare providers. See Healthcare Provider details below.
attachments	array	(Optional) a list of documents attached to the case. See order attachments below.

Order Types

Medical underwriting prerequisites may vary from a case to another. For example, some cases are time sensitive, while others are complex and need a higher level of scrutiny due to underlying health conditions.

The underwriting requirements translate into an order type, which instructs Human API to fulfill the order in a specific way and deliver a specific set of medical records. Below, the list of supported order types:

orderType	Description
(omitted)	Default order type. General purpose case when no special instructions are given by the underwriters. (In order to submit a default order, please leave out the orderType field in the order request)
aps	Attempt to retrieve and deliver a full attending physician statement from all the healthcare providers supplied in the “providers” field.
healthcheck	Retrieve the medical records electronically and deliver a health check summary report.
healthcheck-aps	Retrieve the medical records electronically and deliver a health check summary report with an option to fallback on APS.
no-contact	Attempt to retrieve medical records without interaction with the applicant.
no-contact-aps	Attempt to retrieve medical records without interaction with the applicant and has offline retrieval enabled
no-contact-healthcheck	Retrieve data without any client interaction including no invite email and no special auth email. If electronic sources are connected, deliver a health check summary report.
portal-aps	Attempt to retrieve medical information through the Patient Portal network with an option to fallback on APS.
portal-only	Attempt to retrieve medical information through the Patient Portal network only.

Address object

Addresses supplied to the API are objects that contain information to represent a physical location or a mailing address. City, state and zip are the only required fields.

Human API will validate the individual fields but won’t validate if the location does actually exist.

Attribute	Type	Description
street1	string	(Optional) street address
street2	string	(Optional) street address, continued
city	string	(Optional) City
state	string	(Required) State
zip	string	(Optional) a valid US ZIP code

Healthcare Provider details

You can supply an array of objects identifying the user’s healthcare providers.

To locate a healthcare provider, we need their name (either the practitioner’s name or the organization’s name, or both), as well as contact information such as address, phone/fax number. You can also supply the patient’s (user) Medical record number, if available.

Attribute	Type	Description
name	string	The healthcare practitioner’s name. This is typically the name of the primary care provider or attending physician (optional if the `organizationName` is provided).
organizationName	string	The name of the facility or health system where the user received care. (optional if the `name` field is provided)
address	array	(Optional) The postal address of the healthcare provider. See Address object specifications above.
phone	string	(Optional) a valid North American phone number.
fax	string	(Optional) a valid North American phone number.
mrn	string	(Optional) The Medical Record Number used at the provider to identify the newly created user.

Attachments

The release of medical records may require an authorization document signed by the patient (commonly known as HIPAA authorization or MIB authorization). You can include the document (or multiple documents) as an attachment when requesting an invite.

An attachment encapsulates the document’s purpose, format and content.

Attribute	Type	Description
type	string	(required) set the value of this field to `hipaaAuthorization`
contentType	string	(required) MIME type describing the format of the document, currently application/pdf is supported.
encoding	string	(required) Encoding of the file content. Only base64 is supported as of this version.
content	string	(required) the file content, encoded in base64.

Social security numbers

Social security numbers supplied to the API should comply with all the following:

Must be 9 numeric digits or 11 with the 2 dashes (AAAGGSSSS or AAA-GG-SSSS)
AAA ranges from 001 to 999, excluding 666
GG ranges from 01 to 99
SSSS ranges from 0001 to 9999

Phone numbers

Phone numbers (landline or mobile) and fax numbers supplied to the API should comply with the following criteria:

Must be 9 numeric digits, including the area code, e.g.: (123) 456 7890
Area code ranges from 001 to 999
Besides the 9 numeric digits, separator characters such as (), -, . and blank spaces are allowed with a maximum of 2 separator characters between each number, e.g.: (123) 123 1234, 123-1233-1234, 1234567890, 123.456.7890