App Instances API

List app instances

List all app instances for an account:

GET /app_instances

Response

Status: 200 OK
[
  {
    "id": 1,
    "app_offering": {
      "reference": "note-dispatcher",
      "id": 1
    },
    "customer_account": {
      "id": "wdc",
      "name": "Widget Data Center"
    },
    "created_at": "2021-04-13T04:36:10-05:00",
    "updated_at": "2021-04-13T04:36:10-05:00",
    "enabled_by_customer": true,
    "...": "..."
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of app instances.

Predefined Filters

The following predefined filters are available:

Collection Fields

By default the following fields will appear in collections of app instances:

created_at id nodeID updated_at disabled customer_account app_offering enabled_by_customer

Obtain a different set of fields using the ?fields= parameter.

Filtering

Filtering is available for the following fields:

id created_at updated_at disabled

Sorting

By default a collection of apps instances is not sorted.

The following fields are accepted by the ?sort= parameter:

id created_at updated_at

Get a single app instance

GET /app_instances/:id

Response

Status: 200 OK
{
  "id": 1,
  "app_offering": {
    "reference": "note-dispatcher",
    "id": 1
  },
  "customer_account": {
    "id": "wdc",
    "name": "Widget Data Center"
  },
  "created_at": "2021-04-13T04:36:10-05:00",
  "updated_at": "2021-04-13T04:36:10-05:00",
  "enabled_by_customer": true,
  "...": "..."
}

The response contains these fields.

Fields

attachments
Readonly aggregated Attachments
created_at
Readonly datetime — The date and time at which the app instance was created.
custom_fields
Optional custom fields — Custom fields provided in JSON format by the UI Extension version that is linked to the app offering.
custom_fields_attachments
Writeonly attachments The attachments used in Custom fields.
customer_account
Readonly reference to Account — Account this app instance is for.
customer_representative
Required reference to Person — The contact person regarding this app instance.
disabled
Optional boolean, default: false — The Disabled box is checked when the app instance is disabled by the provider of the Integration. This means the automation rules, webhook, application token of the instance in the customer’s account are disabled.
enabled_by_customer
Optional boolean — The Enabled by customer box is checked when the customer allows the app to operate in their account. This means the automation rules, webhook, application token of the instance in the customer’s account are enabled.
id
Readonly integer — The unique ID of the app instance.
app_offering
Required reference to App Offering — This field references the App Offering this instance belongs to.
suspended
Optional boolean, default: false — The Suspended box must be checked when either the provider or customer wants to disable the app instance, but the other party is allowed to enable it again. This means the automation rules, webhook, application token of the instance in the customer’s account are disabled.
suspension_comment
Optional string (max 64KB) — The Suspension comment field is used to describe why the app instance was suspended.
updated_at
Readonly datetime — The date and time of the last update of the app instance. If the app instance has no updates it contains the created_at value.
webhook
Optional reference to Webhook — This field references the webhook created for the app in the customer’s account.
webhook_policy
Optional reference to Webhook Policy — This field references the webhook policy created for the app in the customer’s account.