Organizations API
List organizations
List all organizations for an account:
GET /organizations
Response
Status: 200 OK
[
{
"id": 44,
"sourceID": null,
"name": "Widget Data Center, External IT",
"parent": {
"id": 6,
"name": "Widget Data Center"
},
"manager": {
"id": 6,
"name": "Howard Tanner"
},
"created_at": "2016-03-22T21:02:50-05:00",
"updated_at": "2016-03-25T16:54:52-05:00"
},
{
"id": 50,
"sourceID": null,
"name": "Widget North America, Finance",
"parent": {
"id": 51,
"name": "Widget North America, Inc."
},
"manager": {
"id": 120,
"name": "Carolyn Goldrat"
},
"created_at": "2016-03-22T21:02:50-05:00",
"updated_at": "2016-03-22T21:03:36-05:00"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of organizations.
Predefined Filters
The following predefined filters are available:
/organizations/disabled
: List all disabled organizations/organizations/enabled
: List all enabled organizations/organizations/external
: List all external organizations/organizations/internal
: List all internal organizations/organizations/trusted
: List all trusted organizations/organizations/directory
: List all organizations registered in the directory account of the support domain account from which the data is requested/organizations/support_domain
: List all organizations registered in the account from which the data is requested/organizations/managed_by_me
: List all organizations which manager or substitute is the API user
Collection Fields
By default the following fields will appear in collections of organizations:
id
sourceID
name
parent
manager
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Filtering
Filtering is available for the following fields:
id
source
sourceID
name
disabled
created_at
updated_at
disabled
financialID
parent
Sorting
By default a collection of organizations is sorted ascending by name
.
The following fields are accepted by the ?sort= parameter:
id
sourceID
name
created_at
updated_at
Response
The response is similar to the response in List organizations
Get a single organization
GET /organizations/:id
Response
Status: 200 OK
{
"addresses": [
{
"address": "1172 Park Avenue",
"city": "New York",
"country": "US",
"id": 71,
"integration": false,
"label": "street",
"state": "NY",
"zip": "10128"
}
],
"business_unit": false,
"business_unit_organization": {
"id": 51,
"name": "Widget North America, Inc."
},
"contacts": [
{
"id": 225,
"label": "general",
"telephone": "+1 (212) 369 2610"
},
{
"id": 226,
"label": "fax",
"telephone": "+1 (212) 369 2611"
},
{
"id": 227,
"label": "general",
"website": "www.widget.com"
}
],
"created_at": "2016-03-22T21:02:50-05:00",
"custom_fields": null,
"disabled": false,
"id": 50,
"manager": {
"id": 120,
"name": "Carolyn Goldrat"
},
"name": "Widget North America, Finance",
"parent": {
"id": 51,
"name": "Widget North America, Inc."
},
"picture_uri": null,
"region": "NA",
"remarks": "The Finance department of Widget North America, Inc. is responsible for purchasing, accounting, and invoicing within Widget North America, Inc.",
"source": null,
"sourceID": null,
"substitute": {
"id": 121,
"name": "Buck Kreuter"
},
"ui_extension": null,
"updated_at": "2016-03-22T21:03:36-05:00"
}
The response contains these fields.
Create an organization
POST /organizations
When creating an organization these fields are available.
Response
Status: 201 Created
{
"addresses": "...",
"...": "..."
}
The response contains all fields of the created organization and is similar to the response in Get a single organization
Update an organization
PATCH /organizations/:id
When updating an organization these fields are available.
Response
Status: 200 OK
{
"addresses": "...",
"...": "..."
}
The response contains all fields of the updated organization and is similar to the response in Get a single organization
Fields
- addresses
- Readonly aggregated Addresses — The Address fields are used to enter the street, mailing and billing addresses of the organization.
- attachments
- Readonly aggregated Attachments
- business_unit
- Optional boolean, default:
false
— The Business unit box is checked when the organization needs to be treated as a separate entity from a reporting perspective. This checkbox is only available for internal organizations. - business_unit_organization
- Readonly reference to Organization — Refers to itself if the organization is a business unit, or refers to the business unit that the organization belongs to.
- contacts
- Readonly aggregated Contacts — The Contact fields are used to enter the general/service desk email addresses, general/fax/etc. of the organization.
- created_at
- Readonly datetime — The date and time at which the organization was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the organization.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- disabled
- Optional boolean, default:
false
— The Disabled box is checked when the organization may no longer be related to other records. - financialID
- Optional string (max 128) — The Financial ID field is used to enter the unique identifier by which the organization is known in the financial system.
- id
- Readonly integer — The unique ID of the organization.
- manager
- Optional reference to Person — The Manager field is used to select the manager of the organization.
- name
- Required string (max 128) — The Name field is used to enter the full name of the organization.
- order_template
- Required reference to Request template — Refers to the order template that is used for purchases of people defined in this organization or its descendants.
- parent
- Optional reference to Organization — The Parent organization field is used to select the organization’s parent organization.
- picture_uri
- Optional string — The hyperlink to the image file for the organization.
- region
- Optional string (max 128) — The Region field is used to specify which region the organization belongs to. It is possible to select a previously entered region name or to enter a new one. This field is only available when the organization is a business unit (i.e. when the Business unit box is checked). Although not visible, the Region field of a business unit’s child organizations is automatically set to the same value as the Region field of the business unit. Examples of commonly used region names are:
-
- Asia Pacific (APAC)
- Europe, Middle East & Africa (EMEA)
- North America (NA)
- remarks
- Optional text (max 64KB) — The Remarks field is used to add any additional information about the organization that might prove useful.
- remarks_attachments
- Writeonly attachments The attachments used in the Remarks field.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- substitute
- Optional reference to Person — The Substitute field is used to select the person who acts as the substitute of the organization’s manager.
- ui_extension
- Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the organization.
- updated_at
- Readonly datetime — The date and time of the last update of the organization. If the organization has no updates it contains the
created_at
value.