This article explains how to connect your Pigment application to an external service using an API request. This allows you to trigger actions remotely from a Action widget on your Pigment Board. 

This is the first Pigment integration capability that can send outgoing API calls to external services, which is useful in a number of situations. For example, you can trigger an external data pipeline which computes and pushes refreshed results to Pigment through the API. You can also send API calls to log custom actions in a remote system.

Unlike other Pigment integrations, the API requests used in this connection don’t use the import data process. Instead, these API requests are triggered directly from a Pigment Board. It’s pretty straightforward. First, you configure the specific API request in your workspace Settings. Next, you create an Action widget on a designated Pigment Board in your workspace. That’s it! 
 

When should I use this? 

Let’s say you have your own custom data platform which has existing end-to-end processes. These processes pull data from different sources, which is then transformed and aggregated to produce intermediate datasets. It finally pushes these results to various destinations - one of those destinations being Pigment. 

One option to get that data into Pigment is to use the import API, and you’d trigger a Pigment import when the data is ready. However, this would require you to interrupt working in Pigment, next you’d have to locate the data process you need to run, and then you’d need to manually trigger it.

The other, streamlined, option is to connect Pigment to your external services using API requests. Here you attach a Action widget in your Pigment Board to an outgoing API call, which triggers this data to be pulled directly from Pigment. You don’t even need to leave the Board where your data is displayed. Because the Pigment update is live, the data in the various Board widgets is updated in real time as soon as the API request is called.
 

To sum up, API requests give:

• New integrations capabilities to trigger custom actions outside of Pigment
• Ability for non-technical users to activate complex workflows with a simple click of an Action widget 

Before you begin

We recommend that you review this useful information before configuring your first API request. 
 

Minimum requirement

Obtain the following API request connection fields:

• (Required) endpoint URL
• (Optional) headers
• (Optional) JSON body

Technical requirements

Currently these API requests have the following scope:

• POST HTTP requests only
• Static requests without dynamic parameters
• If you have an application firewall or IP restriction, you might need to add these IPs to your allowlist:
  • 35.242.251.111
  • 34.145.54.113
  • 34.163.209.119
  • 35.202.142.12
• You need to be a Pigment Workspace Admin to be allowed to configure the connector.

We also provide the following guidelines to ensure that the service is secure and is used reasonably:

• IPs or domain names that resolve to local IP addresses aren’t allowed and will be rejected
• headers are limited to 200 characters
• body is limited to 1000 characters
• Number of calls that can be sent is limited to 100 per hour, per host (domain) and per organization (Pigment workspace)
• The following headers are forbidden and the connection creation is rejected if they’re found in the provided headers:
  • Allow
  • ContentDisposition
  • ContentEncoding
  • ContentLanguage
  • ContentLength
  • ContentLocation
  • ContentMD5
  • ContentRange
  • ContentType
  • Expires
  • LastModified
  • NonValidated

Known limitations

• The configuration is not yet editable. For example, if you need to edit the endpoint URL, headers or JSON body, you need to create a new connection.
• The API request can’t be dynamic. That is, the API request can’t use Pigment’s context as a parameter or content or body of the call. For example, this context can’t be the Pigment Board where the API request is called, specific Pigment data, and so on.

Step by step configuration

Setting up an API request is a straightforward 3-step process:

1. Create a connection with your API or third-party service credentials.
2. Use the connection from a Board with an Action widget. 
3. Test your API request. 

1. Create an API request connection

1. Navigate to the Application Settings. 
2. Click Integrations from the Application sidebar. 
3. From the list of available integrations, locate API request. 
4. Click Add (or Manage). 
5. Click Set up a connection. 
6. Here, enter the following information:

• Name. The name of the connection. You use this later to attach this API request to a Action widget. 
• Application access. This controls in which application(s) this API request is available. 
• POST endpoint URL. This is the request’s target and is a mandatory field. 
• Headers.  (Optional) You can specify custom headers, for example, if you want to provide authentication key.
• JSON body.  (Optional) You can specify a JSON payload to send with each request. 

7. Click Setup. 
    

2. Use the API request connection in a Board

1. Locate and open the Board where you want to use the API request connection.
2. Click Edit, and then click + Add a Widget, and then Action. 

3. Click API request and in the API request connection menu, select your new connection. 

4. (Optional) Add a Button label and a Button tooltip for your Action widget. 
5.  Click Add to Board. 

3. Test your API request

We recommend that after you create the new Action widget that you click it at least once to test that it works. This checks that there isn’t a permission or connectivity issue with the remote service, and it allows you to check that the target receives the calls properly.