Order Attributes

Request Payload Attributes

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

orderTypestring(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.
clientUserIdstring(Required) Your unique identifier of the user, such as the policy number.
clientUserEmailemail(Required) A valid contact email address for the user
firstNamestring(Optional) First name
middleNamestring(Optional) middle name
lastNamestring(Optional) Last name
dateOfBirthdate(Optional) Date of birth
Format: ISO 8601
genderstring(Optional) the user’s gender male or female
suggestedSourcesarray(Optional) A list of provider names, which we will include in communications with the applicant.
conditionsarray(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.
clientDataobject(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
ssnstring(Optional) The applicant’s social security number. Must be a valid US social security number.
phonestring(Optional) a valid North American phone number.
addressobject(Optional) The current address of the newly created user. See Address object specifications below.
providersarray(Optional) a list of healthcare providers. See Healthcare Provider details below.
attachmentsarray(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:

(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)
apsAttempt to retrieve and deliver a full attending physician statement from all the healthcare providers supplied in the “providers” field.
healthcheckRetrieve the medical records electronically and deliver a health check summary report.
healthcheck-apsRetrieve the medical records electronically and deliver a health check summary report with an option to fallback on APS.
no-contactAttempt to retrieve medical records without interaction with the applicant.
no-contact-apsAttempt to retrieve medical records without interaction with the applicant and has offline retrieval enabled
no-contact-healthcheckRetrieve 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-apsAttempt to retrieve medical information through the Patient Portal network with an option to fallback on APS.
portal-onlyAttempt 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.

street1string(Optional) street address
street2string(Optional) street address, continued
citystring(Optional) City
statestring(Required) State
zipstring(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.

namestringThe healthcare practitioner’s name. This is typically the name of the primary care provider or attending physician (optional if the organizationName is provided).
organizationNamestringThe name of the facility or health system where the user received care. (optional if the name field is provided)
addressarray(Optional) The postal address of the healthcare provider. See Address object specifications above.
phonestring(Optional) a valid North American phone number.
faxstring(Optional) a valid North American phone number.
mrnstring(Optional) The Medical Record Number used at the provider to identify the newly created user.


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.

typestring(required) set the value of this field to hipaaAuthorization
contentTypestring(required) MIME type describing the format of the document, currently application/pdf is supported.
encodingstring(required) Encoding of the file content. Only base64 is supported as of this version.
contentstring(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