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:

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.
end_user_privacy
Optional boolean, default: false — The End user privacy box is checked when end users from this organization should be prevented from seeing information of other end users.
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.