---
updatedAt: 2025-10-02T22:25:28.000Z
agentTools:
  projectIndex: https://developer.bill.com/v2/llms.txt
---

# List employees

List employee objects.

See [Search operations with lists](doc:search-ops-with-lists) to learn about pagination, sorting, and filtering.

### What is an employee?
An employee object is useful for creating employee users. Use the employee object only for syncing with Sage Intacct. Intacct employee users have permissions to track bill expenses.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Organization | Accounts tracking",
    "version": "2.0",
    "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.",
    "contact": {
      "email": "developerprogram@hq.bill.com"
    }
  },
  "servers": [
    {
      "url": "https://api-stage.bill.com/api/v2",
      "description": "Sandbox base URL"
    }
  ],
  "x-readme": {
    "samples-languages": [
      "curl",
      "java",
      "javascript",
      "python",
      "ruby"
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "paths": {
    "/List/Employee.json": {
      "post": {
        "summary": "List employees",
        "operationId": "org-accounts-listemployee",
        "description": "List employee objects.\n\nSee [Search operations with lists](doc:search-ops-with-lists) to learn about pagination, sorting, and filtering.\n\n### What is an employee?\nAn employee object is useful for creating employee users. Use the employee object only for syncing with Sage Intacct. Intacct employee users have permissions to track bill expenses.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListEmployeeResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "devKey",
                  "sessionId",
                  "data"
                ],
                "properties": {
                  "devKey": {
                    "type": "string",
                    "description": "Developer key generated with your BILL developer account"
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "API session ID generated with [`/v2/Login.json`](ref:auth-login)"
                  },
                  "data": {
                    "$ref": "#/components/schemas/ListEmployeeRequest"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Employees"
        ]
      },
      "parameters": []
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code (only when `response_status` is `1`)"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (only when `response_status` is `1`)"
          }
        }
      },
      "ListEmployeeRequest": {
        "type": "object",
        "required": [
          "start",
          "max"
        ],
        "properties": {
          "start": {
            "type": "integer",
            "default": 0,
            "description": "Index of the first result"
          },
          "max": {
            "type": "integer",
            "default": 999,
            "description": "Maximum number of results"
          },
          "filters": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "Field name. See the response body documentation to learn about fields that you can filter with. Filterable fields are marked with `You can filter with this field.`"
                },
                "op": {
                  "type": "string",
                  "description": "Operator symbol.\n* `=`: Equals\n* `<`: Less than\n* `>`: Greater than\n* `!=`: Not equal\n* `<=`: Less than or equal to\n* `>=`: Greater than or equal to\n* `in`: Value in list\n* `nin`: Value not in list"
                },
                "value": {
                  "type": "string",
                  "description": "Field value"
                }
              }
            }
          },
          "sort": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "Field name"
                },
                "asc": {
                  "type": "string",
                  "description": "Sort order.\n* `true`: Ascending order\n* `false`: Descending order"
                }
              }
            }
          },
          "nested": {
            "type": "boolean",
            "description": "Set as `true` to include additional nested data in the response"
          }
        }
      },
      "ListEmployeeResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "array",
            "items": {
              "type": "object",
              "allOf": [
                {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              ],
              "properties": {
                "entity": {
                  "type": "string",
                  "description": "Object type. Set as `Employee`."
                },
                "id": {
                  "type": "string",
                  "description": "BILL-generated employee ID. The value begins with `emp`. You can filter with this field."
                },
                "shortName": {
                  "type": "string",
                  "description": "Name for identifying the employee in BILL and in your choice of accounting software."
                },
                "isActive": {
                  "type": "string",
                  "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app. You can filter with this field.\n* `1`: Active\n* `2`: Inactive"
                },
                "firstName": {
                  "type": "string",
                  "description": "Employee first name"
                },
                "lastName": {
                  "type": "string",
                  "description": "Employee last name"
                },
                "parentEmployeeId": {
                  "type": "string",
                  "description": "Parent employee ID. Set this value if the current employee ID is a child object. You can filter with this field."
                },
                "createdTime": {
                  "type": "string",
                  "description": "Created date and time. You can filter with this field."
                },
                "updatedTime": {
                  "type": "string",
                  "description": "Updated date and time. You can filter with this field."
                },
                "mergedIntoId": {
                  "type": "string",
                  "description": "Parent employee ID that the current ID is merged into. You can filter with this field."
                }
              }
            }
          }
        }
      }
    }
  }
}
```