Integrations API

Integrations are a new feature currently in beta-test: this API is subject to change without notice. Visit App Builder NodeJS for more information on integrations in 4me.

List integrations

List all integrations for an account:

GET /integrations

Response

Status: 200 OK
[
  {
    "id": 1,
    "sourceID": null,
    "reference": "note-dispatcher",
    "name": "Log Note Dispatcher Integration",
    "created_at": "2021-04-13T04:19:49-05:00",
    "updated_at": "2021-04-13T04:19:51-05:00",
    "service_instance": {
      "id": 83,
      "name": "Our Integration"
    },
    "policy_jwt_alg": "rs512",
    "webhook_uri_template": "https://jfgd645.execute-api.eu-west-1.amazonaws.com/Prod/integration/?account={account}",
    "...": "..."
  },
  "..."
]

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

Predefined Filters

The following predefined filters are available:

Collection Fields

By default the following fields will appear in collections of integrations:

created_at id name nodeID policy_jwt_alg policy_jwt_audience policy_jwt_claim_expires_in reference service_instance sourceID updated_at webhook_uri_template

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

Sorting

By default a collection of integrations is sorted ascending by reference.

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

id sourceID reference created_at updated_at

Get a single integration

GET /integrations/:id

Response

Status: 200 OK
{
  "id": 1,
  "sourceID": null,
  "reference": "note-dispatcher",
  "name": "Log Note Dispatcher Integration",
  "created_at": "2021-04-13T04:19:49-05:00",
  "updated_at": "2021-04-13T04:19:51-05:00",
  "service_instance": {
    "id": 83,
    "name": "Our Integration"
  },
  "policy_jwt_alg": "rs512",
  "webhook_uri_template": "https://jfgd645.execute-api.eu-west-1.amazonaws.com/Prod/integration/?account={account}",
  "...": "..."
}

The response contains these fields.

Create an integration

POST /integrations

When creating a new integration these fields are available.

Response

Status: 201 Created
{
  "name": "...",
  "...": "..."
}

The response contains all fields of the created integration and is similar to the response in Get a single integration.

Update an integration

PATCH /integrations/:id

When updating an integration these fields are available.

Response

Status: 200 OK
{
  "name": "...",
  "...": "..."
}

The response contains all fields of the updated integration and is similar to the response in Get a single integration.

Fields

attachments
Readonly aggregated Attachments
compliance
Optional text (max 64KB) — The Compliance field is used to enter the compliance statement for the integration. This is shown to customers on the ‘Security & Compliance’ tab in the Apps section for this Integration.
created_at
Readonly datetime — The date and time at which the integration was created.
description
Optional text (max 64KB) — The Description field is used to enter a description of the integration. This is shown to customers on its own tab in the Apps section for this Integration.
disabled
Optional boolean, default: false — The Disabled box is checked when the integration may no longer be installed by new customers. Customers that have an older version installed can still update when the integration is disabled.
features
Optional text (max 64KB) — The Feature field is used to elaborate on the features of the integration. This is shown to customers on its own tab in the Apps section for this Integration.
id
Readonly integer — The unique ID of the integration.
name
Required string (max 128) — The Name field is used to enter the name of the integration.
picture_uri
Optional string — The hyperlink to the image file for the integration.
policy_jwt_alg
Required enum — The algorithm used for generating the policy for the integration’s webhook. Valid values are:
  • rs256: RSA using SHA-256
  • rs384: RSA using SHA-384
  • rs512: RSA using SHA-512
  • es256: ECDSA using P-256 and SHA-256
  • es384: ECDSA using P-384 and SHA-384
  • es512: ECDSA using P-521 and SHA-512
policy_jwt_audience
Optional text (max 2KB) — The audience for the policy for the integration’s webhook.
policy_jwt_claim_expires_in
Optional duration — The claim expiry time for the policy for the integration’s webhook.
reference
Required string (max 161) — The Reference field can be used to identify the Integration via the APIs, it is the only identifier that will remain stable across version updates. It may only be changed until the integration is published for the first time. The Reference field defaults to the Name field value, written in lower case characters and with all spaces replaced by the underscore character, prefixed with the account name followed with an underscore (e.g. wdc_). It must be unique across all accounts.
service_instance
Required reference to Service Instance — The Service instance field is used to select the Service Instance that should be used when creating Requests regarding this Integration.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
ui_extension_version
Optional reference to UI Extension Version — The UI extension version field is used to select the (version of the) UI extension for this Integration’s instances. The UI extension is shown on the ‘Configuration’ tab in the Apps section for customers that install this Integration.
updated_at
Readonly datetime — The date and time of the last update of the integration. If the integration has no updates it contains the created_at value.
webhook_uri_template
Required string (max 255) — The URI for the Integration’s webhook. The placeholder {account} can be used to include the customer account id in the URI.