You can use an Action widget on a Pigment Board to send an API request to another system. This lets Members start an external process without leaving Pigment.
For example, you can start a process that prepares updated data and sends it back to Pigment, or records an activity in another system. This article explains how to create an API request connection, add it to a Board, and test it.
Before you begin
If your data platform collects and prepares data before sending it to Pigment through the import API, you can use an outgoing API request to start that process from a Board.
The external platform must be configured to run the process and import the results into Pigment. The Board reflects updated data after processing and the import have completed. For more information, see Trigger an Import and Check Status with APIs.
Access and permissions
Consider the following when connecting Pigment to an external service through an API request:
Pigment Workspace Admin access to configure the API request connection.
The Configure Boards permission to add an Action widget to a Board.
For more information about configuring widgets, see How to Use Action Widgets.
When should I use this?
Let's say you have a custom data platform with existing end-to-end processes. These processes pull data from different sources, which is then transformed and aggregated to produce intermediate datasets. It then pushes results to various destinations, including Pigment.
One option is to use the import API, and trigger a Pigment import when the data is ready. However, this requires you to stop working in Pigment, locate the process you need to run, and trigger it manually.
A more streamlined option is to connect Pigment to your external services using API requests. Here, you attach an Action widget to an outgoing API call, which triggers the external process. You don't need to leave the Board where your data is displayed. The Board reflects updated data after the external process completes and the updated data is imported into Pigment.
To sum up, API requests provide:
New integration capabilities to trigger custom actions outside of Pigment.
A way for non-technical users to activate complex workflows by selecting an Action widget.
Recommended information
We recommend that you review the following information before configuring your first API request.
Minimum requirements
Obtain the following API request connection fields:
Endpoint URL (required)
Headers (optional)
JSON body (optional)
Technical requirements
API requests currently support:
POSTHTTP requests onlyStatic requests without dynamic parameters
If you have an Application firewall or IP restrictions, you might need to add these IP addresses to your allowlist:
35.242.251.11134.145.54.11334.163.209.11935.202.142.12
You need to be a Pigment Workspace Admin to configure the connector.
We also provide the following guidelines to help ensure the service is secure and 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.
The 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 connection creation is rejected if they're found in the provided headers:
AllowContentDispositionContentEncodingContentLanguageContentLengthContentLocationContentMD5ContentRangeContentTypeExpiresLastModifiedNonValidated
Known limitations
The API request can't be dynamic. This means the API request can't use Pigment context as a parameter or body of the call. For example, this context can't be the Pigment Board where the API request is triggered, specific Pigment data, and so on.
⚠️ Important
The Pigment public API enforces rate limits to ensure fair usage. The limit is 500 requests per 5-minute window per IP address. For more information, see Rate Limits for Pigment Public API.
Step-by-step configuration
Setting up an API request is a three-step process:
Create a connection with your API or third-party service credentials.
Use the connection from a Board with an Action widget.
Test your API request.
1. Create an API request connection
Go to the Application Settings.
In the Application sidebar, select Integrations.
In the list of available integrations, find API request.
Select Add (or Manage).
Select Set up a connection.
Enter the following information:
Name. Give your connection a name. You will use this later to attach the API request to an Action widget.
Application access. Select which Application(s) this API request is available in.
POST endpoint URL. Enter the request's target endpoint URL.
Headers (optional). Add custom headers, for example, for an authentication key.
JSON body (optional). Add a JSON payload to send with each request.
⚠️ Important
These fields are encrypted in Pigment's database. No Pigment Members have read access to the configuration data you provide for these connections.
Select Setup.
ℹ️ Note
If setup fails, check the error notification and review the Technical requirements section.
2. Use the API request connection in a Board
Go to the Board where you want to use the API request connection.
Select Edit, then select + Add a Widget, then select Action.
Select API request, then select your connection from the connection menu.
ℹ️ Note
If you don't see your API request connection, go to the Integrations page in your Application settings and confirm that it was created successfully and enabled for its designated Application.
(Optional) Add a button label and tooltip for your Action widget.
Select Add to Board.
3. Test your API request
After you create the Action widget, select it at least once to test it. This helps you confirm there isn't a permission or connectivity issue with the remote service, and that the target system receives the request as expected.