API Guide - UsersDevices

  • Updated on Apr 27, 2022

Get the End Users in an Organization

Fetches user information (such as user attributes and TrustScoring details) about all the users in your organization.

NOTE: To maintain backwards compatibility, this API response changes when you add the pagination query parameters: skip and limit.

HTTP Request

GET /v1/endusers

URL Parameters

N/A

Query Parameters

Parameter Format Description
Serialnumber String Filter by serial number of device
Email String Filter by email address of user
Skip Int Specify the number of records to skip
Limit Int Specify the number of records you want returned
Name String Filter by enduser’s name
Order String Sorts end users list by ascending (asc) or descending (desc) order, depending on orderby
OrderBy String Sorts end users list by given value (such as name, email)

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

N/A

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request

Response Headers

N/A

HTTP Response Body - Non-Paginated

Example for the Non-Paginated API:

GET /v1/endusers?email=foo+carly@banyanops.com

[
    {
        "Name": "Carly Contractor",
        "Email": "foo+carly@banyanops.com",
        "Groups": "contractors",
        "LastLogin": 1595623756579573745,
        "LoginCount": 12884901929,
        "SerialNumbers": [
            "PF1H8FJD123",
        ],
        "TrustData": {
            "EntityTrustscore": 100,
            "OverrideTrustscore": 100,
            "AccessTrustscore": 100,
            "OverrideActive": "FALSE",
            "Level": "AlwaysAllow",
            "UpdatedAt": 1560321695332747860,
            "Factors": []
        },
        "Roles": [
            "all-contractors",
            "exempted-users"
        ]
    }
]

HTTP Response Body - Paginated

Example for the Paginated API:

GET /v1/endusers?skip=0&limit=10

{
    "endusers": [
        {
            "Name": "Pradip Shrama",
            "Email": "pradip.example@joshsoftware.com",
            "Groups": "Type10Employee,Engineering,Everyone,Type6Employee,Type7Employee,Type1Employee,Type4Employee,Type9Employee,Type3Employee,Type5Employee,Type2Employee,Type8Employee",
            "TrustData": {
                "EntityTrustscore": 100,
                "OverrideTrustscore": 100,
                "AccessTrustscore": 100,
                "OverrideActive": "FALSE",
                "Level": "AlwaysAllow",
                "UpdatedAt": 1575033790699519866,
                "Factors": []
            },
            "Roles": ["Engineering-users"]
        },
        {
            "Name": "Omkar Patil",
            "Email": "omkar.example@joshsoftware.com",
            "Groups": "Engineering,Everyone",
            "TrustData": {
                "EntityTrustscore": 100,
                "OverrideTrustscore": 100,
                "AccessTrustscore": 100,
                "OverrideActive": "FALSE",
                "Level": "AlwaysAllow",
                "UpdatedAt": 1581405438206764451,
                "Factors": []
            },
            "Roles": ["Engineering-users"]
        },
        {
            "Name": "Akshay khatu",
            "Email": "example@joshsoftware.com",
            "Groups": "Engineering,Everyone",
            "TrustData": {
                "EntityTrustscore": 100,
                "OverrideTrustscore": 100,
                "AccessTrustscore": 100,
                "OverrideActive": "FALSE",
                "Level": "AlwaysAllow",
                "UpdatedAt": 1586334782380580944,
                "Factors": []
            },
            "Roles": ["Engineering-users"]
        }
    ],
    "count": 54
}

Get the Devices in an Organization

Fetches device information (such as device attributes, device manager data and TrustScoring details) about all the devices in your organization.

NOTE: To maintain backwards compatibility, this API response changes when you add the pagination query parameters: skip and limit.

HTTP Request

GET /v1/devices

URL Parameters

N/A

Query Parameters

Parameter Format Description
Serialnumber String Filter by serial number of device
Email String Filter by email address of user
Skip Int Specify the number of records to skip
Limit Int Specify the number of records you want returned
Model String Filter by model of device (such as MacBook, iPhone, 20QVS0FP00 (Lenovo ThinkPad))
DeviceFriendlyName String Filter by friendly name of device
Order String Sorts devices list by ascending (asc) or descending (desc) order, depending on orderby
OrderBy String Sorts devices list by given value (such as serialnumber, devicefriendlyname, or model)

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

N/A

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request

Response Headers

N/A

HTTP Response Body - Non-Paginated

Example for the Non-Paginated API:

/devices?serialnumber=27812a90a19df067

[
  {
    "DeviceID": "1864047b-ed59-48ed-b448-492d3b0feb98",
    "SerialNumber": "27812a90a19df067",
    "DeviceFriendlyName": "",
    "Emails": [
      "jack@example.com"
    ],
    "LastLogin": 1587370622671500176,
    "LoginCount": 2147483647,
    "Ownership": "Employee Owned",
    "Platform": "Android",
    "Model": "AOSP on IA Emulator",
    "Architecture": "i686",
    "RegisteredStatus": "TRUE",
    "MdmData": {
      "Timestamp": 1587453424955162624,
      "Source": "BNN",
      "CompromisedStatus": "FALSE",
      "CompliantStatus": ""
    },
    "trust": {
        "value": 100,
        "level": "High",
        "status": "Reporting",
        "last_evaluated":{
            "last_evaluated_at": 1603985589951,
            "last_evaluated_value": 80,
            "last_evaluated_level": "High",
            "last_evaluated_factors": [{
                "name": "AutoUpdateEnabled",
                "value": "true",
                "type": "internal",
                "source": "banyan",
                "description": "",
                "remediation": {
                    "description": "",
                    "url": ""
                }
            }]
        },
        "expired_at": 1603985580051,
        "factors": [{
            "name": "AutoUpdateEnabled",
            "value": "true",
            "type": "internal",
            "source": "banyan",
            "description": "",
            "remediation": {
                "description": "",
                "url": ""
            }
        }]
    },
    "TrustData": {
      "EntityTrustscore": 99,
      "OverrideTrustscore": 100,
      "AccessTrustscore": 99,
      "OverrideActive": "FALSE",
      "Level": "High",
      "UpdatedAt": 1587453425159874138,
      "Factors": [
        {
          "Name": "DiskEncryptionEnabled",
          "Value": "true",
          "Type": "internal",
          "Source": "banyan",
          "Description": "",
          "RemediationDescription":"",
          "RemediationURL":""
        },
        {
          "Name": "NotJailbroken",
          "Value": "true",
          "Type": "internal",
          "Source": "banyan",
          "Description": "",
          "RemediationDescription":"",
          "RemediationURL":""
        },
        {
          "Name": "ScreenLockEnabled",
          "Value": "true",
          "Type": "internal",
          "Source": "banyan",
          "Description": "",
          "RemediationDescription":"",
          "RemediationURL":""
        },
        {
          "Name": "UpToDateOS",
          "Value": "true",
          "Type": "internal",
          "Source": "banyan",
          "Description": "",
          "RemediationDescription":"",
          "RemediationURL":""
        }
      ]
    },
    "Roles": [
      "all-qa-users",
      "all-engineering-users"
    ],
    "Banned": "FALSE",
    "OS": "",
    "AppVersion": ""
  }
]

HTTP Response Body - Paginated

Example for the Paginated API:

GET /v1/devices?skip=0&limit=2

{
  "devices": [
    {
      "DeviceID": "94be2e72-4ce5-41c0-a76d-b0bbd865a1fb",
      "SerialNumber": "6457fa4aa96e29c7",
      "DeviceFriendlyName": "",
      "Ownership": "Employee Owned",
      "Platform": "Android",
      "Model": "AOSP on IA Emulator",
      "Architecture": "i686",
      "RegisteredStatus": "TRUE",
      "MdmData": {
        "Timestamp": 0,
        "Source": "BNN",
        "CompromisedStatus": "FALSE",
        "CompliantStatus": ""
      },
      "trust": {
        "value": 100,
        "level": "High",
        "status": "Reporting",
        "last_evaluated":{
            "last_evaluated_at": 1603985589951,
            "last_evaluated_value": 80,
            "last_evaluated_level": "High",
            "last_evaluated_factors": [{
                "name": "AutoUpdateEnabled",
                "value": "true",
                "type": "internal",
                "source": "banyan",
                "description": "",
                "remediation": {
                    "description": "",
                    "url": ""
                }
            }]
        },
        "expired_at": 1603985580051,
        "factors": [{
            "name": "AutoUpdateEnabled",
            "value": "true",
            "type": "internal",
            "source": "banyan",
            "description": "",
            "remediation": {
                "description": "",
                "url": ""
            }
        }]
      },
      "TrustData": {
        "EntityTrustscore": 100,
        "OverrideTrustscore": 100,
        "AccessTrustscore": 100,
        "OverrideActive": "FALSE",
        "Level": "AlwaysAllow",
        "UpdatedAt": 1594999256162778464,
        "Factors": [
          {
            "Name": "Bnn",
            "Value": "true",
            "Type": "internal",
            "Source": "banyan",
            "Description": "",
            "RemediationDescription":"",
            "RemediationURL":""
          }
        ]
      },
      "Roles": [
        "Developer"
      ],
      "Banned": "FALSE",
      "OS": "",
      "AppVersion": ""
    },
    {
      "DeviceID": "5b8d81a5-4bbe-41f1-a9c3-5cf19efb5543",
      "SerialNumber": "CEA60A5857D74186BEAD6F1027BFA033",
      "DeviceFriendlyName": "Jack’s iPhone",
      "Ownership": "Employee Owned",
      "Platform": "iOS",
      "Model": "iPhone Xr",
      "Architecture": "amd64",
      "RegisteredStatus": "TRUE",
      "MdmData": {
        "Timestamp": 0,
        "Source": "BNN",
        "CompromisedStatus": "FALSE",
        "CompliantStatus": ""
      },
      "trust": {
        "value": 100,
        "level": "High",
        "status": "Reporting",
        "last_evaluated":{
            "last_evaluated_at": 1603985589951,
            "last_evaluated_value": 80,
            "last_evaluated_level": "High",
            "last_evaluated_factors": [{
                "name": "AutoUpdateEnabled",
                "value": "true",
                "type": "internal",
                "source": "banyan",
                "description": "",
                "remediation": {
                    "description": "",
                    "url": ""
                }
            }]
        },
        "expired_at": 1603985580051,
        "factors": [{
            "name": "AutoUpdateEnabled",
            "value": "true",
            "type": "internal",
            "source": "banyan",
            "description": "",
            "remediation": {
                "description": "",
                "url": ""
            }
        }]
      },
      "TrustData": {
        "EntityTrustscore": 100,
        "OverrideTrustscore": 100,
        "AccessTrustscore": 100,
        "OverrideActive": "FALSE",
        "Level": "AlwaysAllow",
        "UpdatedAt": 1594998334145175888,
        "Factors": [
          {
            "Name": "Bnn",
            "Value": "true",
            "Type": "internal",
            "Source": "banyan",
            "Description": "",
            "RemediationDescription":"",
            "RemediationURL":""
          }
        ]
      },
      "Roles": [
        "Developer"
      ],
      "Banned": "FALSE",
      "OS": "",
      "AppVersion": ""
    }
  ],
  "count": 27
}

Delete Enduser Device

Deletes an enduser device and revokes associated client certificate(s).

HTTP Request

DELETE /v1/v1/delete_device?SerialNumber=<SerialNumber>&Email=<Email>

URL Parameters

N/A

CURL request

curl -X DELETE “api_endpoint/v1/v1/delete_device?SerialNumber=TBH121231&Email=trell@mail.com” -H ‘authorization: Bearer tokenxxx’

Query Parameters

Parameter Format Description
SerialNumber String serial number of device (compulsary parameter)
Email String email associated with device

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

N/A

Behavior when the email query parameter is included

Enduser-Device mapping(s) will be deleted from the database for the mentioned SerialNumber and email. Associated certificate(s) will also get revoked. #{:.subhead} i. If the mentioned user(user with stated email) is registered on only the mentioned device(device with stated serial number) then that user will also get deleted, else the user will remain intact. #{:.subhead} ii. If the mentioned device has only the mentioned user registered then the device will also get deleted, else the device will remain intact.

Behavior when the email query parameter is not included

Enduser-Device mapping(s) will be deleted from the database for the mentioned SerialNumber. Device with the mentioned SerialNumber will also get deleted. All certificates associated with the device will also get revoked. #{:.subhead} i. If any user(s) is/are associated with only the mentioned device then that/those user(s) will also get deleted else that/those user(s) will remain intact .

Status Codes and Errors

Value Description
200 OK
400 Bad Request
500 Internal Server Error

Response Headers

N/A

HTTP Response Body

"Successfully deleted end user device"

Ban & Unban Devices

Updates all end user devices for given serial number. This endpoint can be used to ban/unban a device if the device object contains banned="TRUE"/"FALSE" field.

HTTP Request

POST /v1/mdm/update_device?SerialNumber=<SerialNumber>

URL Parameters

N/A

Query Parameters

Parameter Format Description
SerialNumber String Serial number of device(s) to be updated

Request Headers

Authorization: Bearer $AUTHTOKEN

ContentType: application/json

Request Body

[
  {
    "Model": "lenovo thinkpad",
    "Ownership": "CorporateDedicated",
    "Platform": "darwin",
    "Architecture": "hello123123",
    "Banned" : "FALSE",
  }
]

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request

Response Headers

N/A

Response Body

[
  {
    "Message": "Success"
  }
]

DELETE enduser

This api marks endusers as inactive, checks the devices associated with the user, if the device has no more active users then such devices are marked as inactive too.

Authorization needed: Admin

HTTP Request

DELETE /v2/endusers

URL Parameters

N/A

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

{
    "enduser_ids" : [
            "725dc2fb-b162-45bd-8d91-9902c31afdf4",
            "725dc2fb-b162-45bd-8d91-9902c31afdg7",
            "725dc2fb-b162-45bd-8d91-9902c31affr5"
        ] 
}

Status Codes and Errors

Value Description
200 OK
401 Unauthorized
400 Bad Request
500 Internal Server Error

Response Headers

N/A

HTTP Response Body

200 Ok
{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": "successfully marked the endusers as inactive"
}

400 Bad Request
{
    "request_id": "",
    "error_code": 400,
    "error_description": "record not found",
    "data": null
}

500 Ok
{
    "request_id": "",
    "error_code": 500,
    "error_description": "error occoured while marking the endusers as inactive",
    "data":null
}