Overview (backup)
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]",
"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.
Updated almost 2 years ago