Integration Best Practices

System to System Workflow Best Practices

This document provides recommendations on the best methodology to implement Human API during a system to system integration.

  1. This document provides recommendations on the best methodology to implement Human API during a system to system integration.
  2. This document walks through our best practices such as,
  3. Where to insert Human API into your workflows
  4. Setting up workflows to include at least our four default Order Types
  5. Displaying statuses clearly to your underwriters and case managers
  6. Alerting underwriters when Tasks require their input
  7. Creating a method to cancel an order from your system
  8. Retrieving both a PDF and JSON report upon record delivery

Integrating Human API Workflows

The best way to get digital data sooner is to implement Human API as early as possible within the lifecycle of the application. When considering what point to create an order with Human API, we recommend implementing all of the following:

  1. Add HumanAPI’s Connect module to the Part II application process or immediately after. This allows an applicant to launch the Patient Portal process while the applicant is already engaged.
  2. Add rules to automatically order Human API based on logic within the underwriting model when evidence is determined to be required.
  3. Create the ability for underwriters to ad hoc create Human API orders based on underwriting requirements.
    1. Creating underwriting requirements based on Order Types is recommended. More information can found about this in the following, Determining Order Types section.

More details on how to create an order can be found in Submitting Orders

Determining Order Types

The underwriting requirements translate into what Human API calls an Order Type, which instructs Human API to fulfill the order in a specific way and deliver a specific set of medical records.

To properly determine which Order Types should be used based on the workflows that exist or are desired within your system, Workflow Design sessions should be scheduled with your Account Manager.

As a quick start reference, the standard workflow recommended by the Human API team includes using at least 4 Order Types:

  • Complete Medical Record: Orders medical evidence from all EHR networks with a pivot to an APS if no EHR records are found.
  • No Contact: Orders medical evidence from non-consumer mediated EHR networks with a pivot to an APS if no EHR records are found. No contact made with the applicant.
  • APS Only: Orders only an APS for the applicant.
  • EHR Only: Orders medical evidence from the EHR networks only.
Table of comparison of how Order Types Work

Comparison of how Order Types work

Further technical information can be found in the Order Types table.

Tracking Order Status

After submitting an order, you will be able to monitor the status via API notifications. Technical details around status tracking can be found in the Order Fullfillment Lifecycle section.

When considering how to display the order status within your system, we recommend that the status is readily displayed for underwriters and case managers to view. Our most successful integrations also display Human API statuses to the systems your producers utilize to check case status.

Pended Cases

Human API’s Health Intelligence Platform integrates with multiple different sources of medical information. Each of these sources/vendors have different mechanisms and methods to indicate that retrieval is blocked and some action is required from the order submitter or from the applicant.

Human API transforms all of these various messages and consolidates them into four standard "Tasks" which then route through our platform.

Task Types

Sign Provider Authorization Form

When this task is triggered a special authorization form is required to be signed by the applicant. This task triggers an email sent directly to the consumer.

Fee Approval Request

When this task triggers an additional fee is required to release medical records. This task is sent to an underwriter to be approved or denied.

Order Information

When this task triggers there is missing or invalid order information. For example, the provider information necessary for an order may be incomplete.

Response Required

When this task triggers there is a question regarding the release of medical records. For example, if the patient can not be found at the designated facility, a question would be asked of how to proceed with the order.

Task Management

During workflow considerations, it is strongly recommended that tasks are considered. When a case is placed in a Pended status, we recommend creating a method within your system to alert your underwriters/case managers that action is required. For example, the underwriting requirement used to place the Human API order may change status which places the case in an underwriting work list.

When integrated, an API payload includes a link which can be surfaced to users to enable them to resolve the task. Reminders can also be set up on a schedule to help remind stakeholders that the case is still pended. More information can be found in the Task Manager section.

Order Cancellation

We recommend creating the ability to cancel a Human API order directly from your system. There is not a way to cancel orders within Human API’s web portal and to do so manually requires Human API Support intervention. Adding the ability to cancel directly between systems removes this manual intervention. Technical information can be found in the Cancelling Orders section.

Retrieving Reports

To understand if a report is available or not, we recommend utilizing our Order Summary Notification. This makes is easy to determine if a record is available when the order moves to a Completed status.

We recommend intaking the following report types with us:

  • Combined Clinical History Report: This PDF combines Human API’s Highlights Summary and Clinical History Report. This is the full health history, normalized through Human API’s proprietary methodology, in a human-readable PDF.
  • API Data Report: Human API’s apidata report will be sent in a JSON format, which can be used within data models and decisioning rules.

More information about Report Types can be found in the specific section.


We’re here to help! Your Account Manager is here to help determine and design workflows based on our expertise and experience. Please reach out to your Account Manager for any additional questions.

What’s Next