GET
/
external-api
/
v1
/
company
/
users
Get Company Users
curl --request GET \
  --url https://getbill.io/external-api/v1/company/users \
  --header 'Authorization: <authorization>'
{
  "error": false,
  "message": "Success",
  "data": [
    {
      "id": "abc123def456ghi789",
      "email": "john.manager@company.com",
      "firstname": "John",
      "lastname": "Manager",
      "is_active": true,
      "created_at": "2023-01-15T10:30:00Z",
      "last_activity": "2024-01-22T14:22:00Z"
    },
    {
      "id": "xyz789mno012pqr345",
      "email": "jane.agent@company.com",
      "firstname": "Jane",
      "lastname": "Agent",
      "is_active": true,
      "created_at": "2023-03-22T09:15:00Z",
      "last_activity": "2024-01-22T11:45:00Z"
    },
    {
      "id": "stu678vwx901yzab234",
      "email": "bob.analyst@company.com",
      "firstname": "Bob",
      "lastname": "Analyst",
      "is_active": false,
      "created_at": "2023-06-10T16:20:00Z",
      "last_activity": "2023-12-15T13:30:00Z"
    }
  ]
}

​
Overview

This endpoint returns information about all users associated with your company account, including their roles, activity status, and basic profile information.

​
Authentication

Requires a valid OAuth 2.0 access token with the users:read scope.

​
Request

​
Authorization
string
required
Bearer token for authentication

​
Example Request

curl -X GET "/external-api/v1/company/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

​
Response

​
error
boolean
Always false for successful requests
​
message
string
Success message
​
data
array
Array of user objects

​
Success Response

{
  "error": false,
  "message": "Success",
  "data": [
    {
      "id": "abc123def456ghi789",
      "email": "john.manager@company.com",
      "firstname": "John",
      "lastname": "Manager",
      "is_active": true,
      "created_at": "2023-01-15T10:30:00Z",
      "last_activity": "2024-01-22T14:22:00Z"
    },
    {
      "id": "xyz789mno012pqr345",
      "email": "jane.agent@company.com",
      "firstname": "Jane",
      "lastname": "Agent",
      "is_active": true,
      "created_at": "2023-03-22T09:15:00Z",
      "last_activity": "2024-01-22T11:45:00Z"
    },
    {
      "id": "stu678vwx901yzab234",
      "email": "bob.analyst@company.com",
      "firstname": "Bob",
      "lastname": "Analyst",
      "is_active": false,
      "created_at": "2023-06-10T16:20:00Z",
      "last_activity": "2023-12-15T13:30:00Z"
    }
  ]
}

​
Usage Notes

  • Only basic user information is returned for security and privacy reasons
  • Sensitive information like passwords, roles, and detailed permissions are not included
  • Inactive users (is_active: false) are still returned but may have limited access
  • The last_activity field helps identify active vs. inactive users
  • User management (creating, updating, deleting users) is not available through the external API

​
Error Responses

{
  "error": true,
  "message": "Authentication credentials are missing or invalid",
  "code": 401
}