Overview

An alternative to using webviews is our Hosted App experience. With this approach, users can open an Invite Link on their browsers and be redirected to a page where Connect assets are hosted by Human API. Once the user's data source connection process is complete, you can call back your application using a deep link.

The image below shows an example of a Mobile Integration with a native Android implementation.

📘

Callback URLs

Prior to integrating the Invite Links, please provide your callback URLs to [email protected] so that we can whitelist them (e.g. "https://webhook.site/", "hapiconnect://").

Usage

Composing the Invite Link URL

With Session Token / ID Token

You can leverage Session or ID tokens to help form the user's unique link to the Hosted App experience. In order to generate the session or id tokens, please visit the web guide documentation. You can then compose your own Invite Link with the tokens using the following format:

https://hapi-link.humanapi.co/connect?clientId=<ClientId>&token=<userSessionToken>&callback=<aValid://callbackUrl>

You may also specify optional query parameters mode, segment, and pinnedProviders, for more information, take a look at Customize your Connect integration.

Opening the Invite Link URL

Once the Invite Link with callback is available, you can open it on the user's default browser from your Native or Hybrid mobile application. When the user closes Connect, they will be redirected to the provided callback.

Response payload

After the user is redirected, you should see a payload response that indicates various details on the session. Those details include their:

• current data connections ("currentConnections")
• newly connected sources during the session ("sessionResults.connectedSources")
• disconnected sources during the session ("sessionResults.disconnectedSources")
• requested sources during the session ("sessionResults.requestedSources")
• unique userId generated by Human API ("humanid")

//example of new connection to Fitbit during the session
{
    "currentConnections": [
        {
            "name": "Fitbit",
            "id": "54dc427aaa6b4cb7d6202f01"
        }
    ],
    "requestedProviders": [],
    "sessionResults": {
        "connectedSources": [
            {
                "name": "Fitbit",
                "id": "54dc427aaa6b4cb7d6202f01"
            }
        ],
        "disconnectedSources": [],
        "requestedSources": []
    },
    "status": "SUCCESS",
    "humanid": "053b94541c2dff1bc67fbeb6bfdf8bcb"
}

//example of currently connected medical account, no new connections or disconnections by the conclusion of user session
{
 "currentConnections":
  	[{
      "name":"Starfleet Pharmacy",
      "id":"5b1daf3f079c652eaf41fd23"
    }],
  "requestedProviders":[],
  "sessionResults":
  	{
   	 "connectedSources":[], 
     "disconnectedSources":[],
     "requestedSources":[]
  	},
 "status":"SUCCESS", 
 "humanid":"8ecfc1a73e350f17d20ed0fc66036bf2"
}

Possible errors

A user may encounter a 403 error in the Hosted App experience. If this is the case, please verify that the provided callback URL in the Invite Link is correct and that the appropriate URLs are whitelisted with Human API support.

{
 "statusCode": 403,
 "error": "Forbidden",
 "message": "Invalid callback URL"
}