departments

List Departments

SecurityRemoteAuthentication or M2MAuthentication or BasicAuthentication or cookieAuth
Request
query Parameters
branch
integer

Filter departments by their branch.

format
string
Enum: "csv" "json"
include_is_active_for_account_code
integer

Setting this adds the addition of the booeal field 'has_active_account' to each department object of the response. The query param accepts an integer representing the primary key of the account code to check if there exists an account object associated with the department with that account code.

location_perm_override
boolean

Setting this overrides the need to enable the PROCUREMENT_ACCESS and/or RECEIVE_BY_DEPARTMENT feature switches. This parameter can only be used in conjunction with permission and user and cannot function without both of those parameters explicitly set.

locations
Array of integers

Filter departments by the locations (branches) passed in.

order_by
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

permission
integer

Filter by permission. In isolation, this parameter can only be set to 68 (add purchase order); 841 (view report); or 899 (receive_po), which correlate with permission to add purchase orders, view reports, and receive purchase orders respectively. However, the results returned correlate with the “by department” version of these permissions, which means that results are filtered by permission to add purchase orders by department, permission to view reports by department, and receive purchase orders by department. This should only be used in conjunction with the PROCUREMENT_ACCESS and/or RECEIVE_BY_DEPARTMENT feature switches. If used in conjunction with location_perm_override=true and user, the value can be set to any permission, and the result will be departments filtered by the provided user and permission values. If used in conjunction with the RECEIVE_BY_DEPARTMENT feature flag, the permission can only be set to 68, 841, or 899 (see second sentence for what these permissions do). The result will be all departments filtered by the provided user value.

requestable
string

Fetch all requestable departments by the currently authorized user. Accepts ORDER, EXPENSE, TRAVEL, and PAY_REQUEST.

search
string

A search term.

user
integer

Filter by user. If this parameter is set, the user must be a superuser or have the add_po_by_department or receive_po_by_department permissions. In isolation, this parameter should only be used in conjunction with the PROCUREMENT_ACCESS and/or RECEIVE_BY_DEPARTMENT feature switches. If used in conjunction with location_perm_override=true and permission query parameter, the result returned will be departments filtered by the provided user and permission values. If used in conjunction with the RECEIVE_BY_DEPARTMENT feature flag, the result will be departments filtered by the user provided and the permission set to 68 (add purchase order); 841 (view report); or 899 (receive purchase order) (see permission query parameter explanation for more information on what these stand for).

Responses
200
Response Schema:
object
Array of objects (DepartmentRead)
get/api/v3/departments/
Response samples
{
  • "metadata": {
    },
  • "data": [
    ]
}

Create New Department

SecurityRemoteAuthentication or M2MAuthentication or BasicAuthentication or cookieAuth
Request
query Parameters
format
string
Enum: "csv" "json"
Request Body schema:
required
branch
required
integer
external_id
string or null <= 100 characters

External id

name
required
string [ 1 .. 150 ] characters
active
boolean
punchout_email
string or null non-empty
Responses
201
Response Schema:
object
Default: {}
required
object (DepartmentRead)
post/api/v3/departments/
Request samples
{
  • "branch": 0,
  • "external_id": "string",
  • "name": "string",
  • "active": true,
  • "punchout_email": "string"
}
Response samples
{
  • "metadata": { },
  • "data": {
    }
}

Update Department

SecurityRemoteAuthentication or M2MAuthentication or BasicAuthentication or cookieAuth
Request
path Parameters
id
required
integer

A unique integer value identifying this department.

query Parameters
format
string
Enum: "csv" "json"
Request Body schema:
required
branch
required
integer
external_id
string or null <= 100 characters

External id

name
required
string [ 1 .. 150 ] characters
active
boolean
punchout_email
string or null non-empty
Responses
200
Response Schema:
object
Default: {}
required
object (DepartmentRead)
put/api/v3/departments/{id}/
Request samples
{
  • "branch": 0,
  • "external_id": "string",
  • "name": "string",
  • "active": true,
  • "punchout_email": "string"
}
Response samples
{
  • "metadata": { },
  • "data": {
    }
}