Admin API

The Admin API allows you to perform certain actions programmatically that would have been only available from the Portal. Please keep in mind this is an evolving list of functions. If you are interested in using this API for your existing client application, please let us know and we can enable it.

📘

How to enable

Admin API is disabled by default. In order to add the functionality, please contact [email protected] and identify the clientIds you would like to enable for.

Retrieve a client token

Requests to Admin API must be authenticated with a client token. In order to get it, please make a request like so to our authentication server:

POST ​/v1/admin/token​ HTTP/1.1 
Host: auth.humanapi.co 
Content-Type: application/json 
Cache-Control: no-cache

{
"client_id": "your_client_id", // retrieved from the Portal
"client_secret": "your_client_secret", // retrieved from the Portal
"type" : "client" // always "client"
}
curl --request POST 'https://auth.humanapi.co/v1/admin/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "96cb8da44a2e6663cc4dd7ae8d7363e922b5e0f4",
"client_secret": "63b0b6c606e871332v4972fc7a99d31b19112351",
"type" : "client"
}'

A successful response will look like this:

{
    "expires_in": 86400, // seconds
    "client_token": "eyJraWQiOiJDMGNiRE1jV3V4bVkyckplZGw5MF93dXRHRVNGY21wSVQ4OTJpc2E1T1QwIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjNxdlhwbm9hZ3JDSGlTUi1nOTJFSlkxQW1UVEFXTnZIQmMxbG9oUVhXYmciLCJpc3MiOiJodHRwczovL2FjY291bnQuaHVtYW5hcGkuY28vb2F1dGgyL2F1czNmY3ZhbzJaM2ViU2hPMjk3IiwiYXVkIjoiYWRtaW4uaHVtYK5waS5jbyIsImlhdCI6MTU4ODc4NTkwNSwiZXhwIjoxNTg4ODcyMzA1LCJjaWQiOiI5NmNiOGRhNDRhMmU2NjYzY2M0ZGQ3YWU4YzczNjNlOTIyYjVlMGY0Iiwic2NwIjpbImFwcHVzZXI6d3JpdGUiLCJhcHB1c2VyOnJlYWQiXSwic3ViIjoiOTZjYjhkYTQ0YTJlNjY2M2NjNGRkN2FlOGM3MzYzZTkyMmI1ZTBmNCJ9.Nq-MThWyN7Rp8bG0rR91MP9mLR8F3GZRXgwbk8cdrDdWcNQdrGoEetZk56GJfl7BHnhkyoDO4d4EE04f4HYzJRXgo4k3s6fh6xrMMFjvMW4x9WqJ8mTK2kF56wYto45pL3b6UcnxrAX-PM_ooXRfWPWw130LQCW-G4cfww1Qb2_AlqSJYSeSnozXhMW08sA4HERDJ8UuHKX6Cklln-QIBPCGkU5I_JeDAdu9FaxbDZfJWTGbHhwC8s5SRYSSrq8OhoI3U3r29DFo2kT0ekdwbV_jPd4GkYSYYcGxh9QoAcj2ThTkntyIggH9hY9uUob0ckhLAUxDL6CGE1hXCscIft"
}

Get users

To get a list of users associated with your provisioned Human API application, send a GET request with your client token. The request looks like this:

GET /api/v1/users HTTP/1.1 
Host: admin.humanapi.co
Content-Type: application/json
Cache-Control: no-cache
Authorization: Bearer your-client-token
curl -X GET 'https://admin.humanapi.co/api/v1/users' \
-H 'Authorization: Bearer eyJraWQiOiJDMGNiRE1jV3V4bVkyckplZGw5MF93dXRHRVNGY21wSVQ4OTJpc2E1T1QwIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjNxdlhwbm9hZ3JDSGlTUi1nOTJFSlkxQW1UVEFXTnZIQmMxbG9oUVhXYmciLCJpc3MiOiJodHRwczovL2FjY291bnQuaHVtYW5hcGkuY28vb2F1dGgyL2F1czNmY3ZhbzJaM2ViU2hPMjk3IidiYXVkIjoiYWRtaW4uaHVtYW5waS5jbyIsImlhdCI6MTU4ODc4NTkwNSwiZXhwIjoxNTg4ODcyMzA1LCJjaWQiOiI5NmNiOGRhNDRhMmU2NjYzY2M0ZGQ3YWU4YzczNjNlOTIyYjVlMGY0Iiwic2NwIjpbImFwcHVzZXI6d3JpdGUiLCJhcHB1c2VyOnJlYWQiXSwic3ViIjoiOTZjYjhkYTd0YTJlNjY2M2NjNGRkN2FlOGM3MzYzZTkyMmI1ZTBmNCJ9.Nq-MThWyN7Rp8bG0rR91MP9mLR8F3GZRXgwbk8cdrDdWcNQdrGoEetZk56GJfl7BHnhkyoDO4d4EE04f4HYzJRXgo4k3s6fh6xrMMFjvMW4x9WqJ8mTK2kF56wYto45pL3b6UcnxrAX-PM_ooXRfWPWw130LQCW-G4cfww1Qb2_AlqSJYSeSnozXhMW08sA4HERDJ8UuHKX6Cklln-QIBPCGkU5I_JeDAdu9FaxbDZfJWTGbHhwC8s5SRYSSrq8OhoI3U3r29DFo2kT0ekdwbV_jPd4GkYSYYcGxh9QoAcj2ThTkntyIggH9hY9uUob0ckhLAUxDL6CGE1hXCscIfg'

A successful response yields a HTTP 200 status code and an array in the body similar to below:

[
    {
        "firstName": "Sam",
        "lastName": "Doe",
        "clientUserId": "Human_441272526",
        "clientUserEmail": "[email protected]",
        "humanId": "b3301c8d6f5242fcf2e6455aa83423cf",
        "createdAt": "2020-06-09T18:15:13.388Z",
        "updatedAt": "2020-06-09T18:16:25.138Z",
        "status": "All Synced"
    },
    {
        "firstName": "John",
        "lastName": "Doe",
        "clientUserId": "Human_337596920",
        "clientUserEmail": "[email protected]",
        "humanId": "37db9784cd01029cf27f2eff22b476a3",
        "createdAt": "2020-06-09T18:21:00.491Z",
        "updatedAt": "2020-06-09T18:21:59.335Z",
        "status": "Declined"
    },
    {
        "firstName": "Jane",
        "lastName": "Doe",
        "clientUserId": "Human_478102855",
        "clientUserEmail": "[email protected]",
        "humanId": "fecfdd65dc1567481b22f6a043dde31a",
        "createdAt": "2020-06-09T18:40:20.955Z",
        "updatedAt": "2020-06-09T19:25:27.627Z",
        "status": "Declined"
    },
    {
        "firstName": "Tim",
        "lastName": "Doe",
        "clientUserId": "Human_399765218",
        "clientUserEmail": "[email protected]",
        "humanId": "89e05678d1a299e9f268d68ffe23dc13",
        "createdAt": "2020-06-09T20:04:26.140Z",
        "updatedAt": "2020-06-16T20:11:52.865Z",
        "status": "Engaged"
    },
    {
        "firstName": "James",
        "lastName": "Doe",
        "clientUserId": "Human_547887179",
        "clientUserEmail": "[email protected].co",
        "humanId": "26b7edc263ac5b421dd8a826465d619a",
        "createdAt": "2020-06-16T16:53:49.658Z",
        "updatedAt": "2020-06-17T23:33:43.901Z",
        "status": "Engaged"
    }
]

📘

Get a single user

You can also check the details of one user by simply appending their humanId to the call. The request will resemble https://admin.humanapi.co/api/v1/users/b3301c8d6f5242fcf2e6455aa83423cy

User statuses and definitions

As you call the Admin API's /users endpoint to retrieve status information, a "status" field will be returned. The table below is a quick guide to identify each of the values that you may encounter related to that attribute:

User Status

Description

Invited

The user record was created and an invite was sent.

Engaged

The user opened the link and engaged in the authorization process.

Declined

The user explicitly declined to participate.

Syncing

The user authorized access to at least one provider and the sync operation is in progress.

All Synced

We have successfully retrieved data from all the healthcare providers.

Some Synced

We have successfully retrieved data from some of the healthcare providers.

Error

We are unable to send an invite to the user or unable to retrieve data

Attn Required

We need the user to perform an action before we proceed (such as accepting the terms and conditions in the Patient portal)

Disconnected

The user has disconnected all the providers to whom they had previously authorized access.

Delete users

This is a soft delete function that prevents further access to the user's data.

To perform this, send a DELETE request along with your ​client token. You must also identify the user by their ​humanId in /api/v1/users/humanId.

The request looks like this:

DELETE /api/v1/users/ef14404e9860776f6300e3e4cb10f84a HTTP/1.1 
Host: admin.humanapi.co
Content-Type: application/json
Cache-Control: no-cache
Authorization: Bearer your-client-token
curl -X DELETE 'https://admin.humanapi.co/api/v1/users/943b077e6b0330d4dd1c56565ef4db0a' \
-H 'Authorization: Bearer eyJraWQiOiJDMGNiRE1jV3V4bVkyckplZGw5MF93dXRHRVNGY21wSVQ4OTJpc2E1T1QwIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjNxdlhwbm9hZ3JDSGlTUi1nOTJFSlkxQW1UVEFXTnZIQmMxbG9oUVhXYmciLCJpc3MiOiJodgRwczovL2FjY291bnQuaHVtYW5hcGkuY28vb2F1dGgyL2F1czNmY3ZhbzJaM2ViU2hPMjk3IiwiYXVkIjoiYWRtaW4uaHVtYW5waS5jbyIsImlhdCI6MTU4ODc4NTkwNSwiZXhwIjoxNTg4ODcyMzA1LCJjaWQiOiI5NmNiOGRhNDRhMmU2NjYzY2M0ZGQ3YWU4YzczNjNlOTIyYjVlMGY0Iiwic2NwIjpbImFwcHVzZXI6d3JpdGUiLCJhcHB1c2VyOnJlYWQiXSwic3ViIjoiOTZjYjhkYTd0YTJlNjY2M2NjNGRkN2FlOGM3MzYzZ1kyMmI1ZTBmNCJ9.Nq-MThWyN7Rp8bG0rR91MP9mLR8F3GZRXgwbk8cdrDdWcNQdrGoEetZk56GJfl7BHnhkyoDO4d4EE04f4HYzJRXgo4k3s6fh6xrMMFjvMW4x9WqJ8mTK2kF56wYto45pL3b6UcnxrAX-PM_ooXRfWPWw130LQCW-G4cfww1Qb2_AlqSJYSeSnozXhMW08sA4HERDJ8UuHKX6Cklln-QIBPCGkU5I_JeDAdu9FaxbDZfJWTGbHhwC8s5SRYSSrq8OhoI3U3r29DFo2kT0ekdwbV_jPd4GkYSYYcGxh9QoAcj2ThTkntyIggH9hY9uUob0ckhLAUxDL6CGE1hXCscIfg'

A successful request yields a response with 200 status code and an empty body.

After deleting the user :

  • They will be removed from the Portal.
  • They will not be able to authorize additional data sources.
  • New tokens cannot be generated.
  • Status notifications will cease (if enabled).
  • Communications and reminder emails will cease (if enabled).

📘

Can I recreate a deleted user?

After deletion, you may receive a 403 error if you attempt to recreate a user with the same client_user_id. Instead, it is recommended to use a client_user_id value that has not been used before if the user returns to your platform and wishes to use Human API again.