Pigment allows users to automate their import process thanks to a generic API. In this article, you will find all the information you need on how to import your data using the Pigment Import API.

Before you begin

To trigger an import from the Pigment Import API, you need two things:

Pigment API Key. This private key will be used to authenticate the service calling the API. Use the Integration page to get one.
Import Configuration ID. This ID represents the import configuration. Check the Import configuration documentation to see how to generate one.

ℹ️ Note
An Import Configuration ID in Pigment defines the destination of the file. It is dependent on the file you import and the destination within Pigment, similar to the target path in a file server, with everything pre-configured.

You also need to understand how access rights work with API keys.

API keys impersonate the access rights of their owner. For example, if you import data from Pigment by calling an API, and you use a key that John created, then the API returns the data as John sees it. For more information on API keys in Pigment, see Manage API keys.

Swagger / OpenAPI specification

Pigment has a Swagger page with all the publicly available API endpoints: https://pigment.app/api/swagger.

Configure an Import API request

ℹ️ Note
The v1 in the endpoint examples below is required for new capabilities, such as triggering any Import or detailed report. While legacy endpoints remain compatible with or without a version prefix, it is strongly recommended to update these endpoints to ensure continued compatibility.

CSV Import

Use this POST endpoint to trigger an import with an Upload file configuration:

https://pigment.app/api/v1/import/push/csv?configurationId={CONFIGURATION_ID}

⚠️ Important
The CSV file to upload needs to be sent in the request body.

Integration or Metric/List Import

Use this POST endpoint to trigger an import with an Integration or Pigment Metric/List configuration:

https://pigment.app/api/v1/import/trigger?configurationId={CONFIGURATION_ID}

Request configuration

Replace {CONFIGURATION_ID} by the ID retrieved in the Before you begin step or from the Metadata API.
To authenticate the API call, you need to add an HTTP Authorization header to your request: Authorization: Bearer {API_KEY}
Replace {API_KEY} by the key retrieved in the previous step.

ℹ️ Note
Your final URL should look like this:
https://pigment.app/api/v1/import/push/csv?configurationId=33d0d7d0-6125-47c4-b36a-882f4ed53b33
or
https://pigment.app/api/v1/import/trigger?configurationId=33d0d7d0-6125-47c4-b36a-882f4ed53b33
And the request header like this:
Authorization: Bearer M2pwMmUyMzItOTg3NS00MmY0LTlmY2YtNjNmZTJjZTU2OGpw

⚠️ Important
If your API Key has the old format with dashes (e.g. 3jp2e232-9875-42f4-9fcf-63fe2ce568jp) then you need to generate a new key from Pigment following these instructions.

API response

Calling one of the endpoints above will return a response with a single field importId (see below on how to use it to get status information).

{
  "importId": "f2b03cab-ba63-4525-bd59-c597f6721973"
}

Example for a CSV File Import

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export CONFIGURATION_ID="CHANGE ME"
export FILE_PATH="CHANGE ME"

# Post the CSV
curl -X POST \
"https://pigment.app/api/import/push/csv?configurationId=${CONFIGURATION_ID}" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}" \
--data-binary "@/${FILE_PATH}"

Import status

Use this GET endpoint to retrieve an import status:

https://pigment.app/api/v1/import/{IMPORT_ID}/status?includedDetailedReport=true

Replace {IMPORT_ID} by the ID returned by the CSV Push call described above.

The includedDetailedReport parameter is optional and will default to false when not provided.

ℹ️ Note
Your final URL should look like this:
https://pigment.app/api/v1/import/f2b03cab-ba63-4525-bd59-c597f6721973/status
And the request header like this:
Authorization: Bearer M2pwMmUyMzItOTg3NS00MmY0LTlmY2YtNjNmZTJjZTU2OGpw

API response

{
  "importId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2025-12-23T14:20:19.689Z",
  "completedAt": "2025-12-23T14:20:19.689Z",
  "importStatus": "InProgress",
  "errorsDetails": [
    {
      "name": "string",
      "description": "string"
    }
  ],
  "detailedReport": {
    "blockType": "Metric",
    "summary": {
      "insertedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "skippedCount": 0
    },
    "impactedBlocks": [
      {
        "blockId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "scenarioId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "insertedCount": 0,
        "updatedCount": 0,
        "skippedData": [
          {
            "count": 0,
            "reason": "ParsingError",
            "sourceColumnName": "string",
            "samples": [
              "string"
            ]
          }
        ],
        "deletedCount": 0
      }
    ],
    "autoCreatedDimensionModalities": [
      {
        "blockId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "count": 0
      }
    ]
  }
}

importStatus can have three values: InProgress, Completed and Failed.

errorsDetails name and description are only informative. These fields are only available on imports with Failed status.

detailedReport will only be included in the response if includedDetailedReport=true has been specified in the request.

Example

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export IMPORT_ID="CHANGE ME"

# Get status
curl -X GET "https://pigment.app/api/v1/import/${IMPORT_ID}/status?includedDetailedReport=true" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}"

Troubleshooting

In addition to the import status API above, you can check the status of imports in the “Update History” of your block.

ℹ️ Note
The import will be displayed as if it had been triggered by the person who created or edited the Import configuration.

If the import was not successful, you can check the "Import Summary" to get more information.

Example:

Do not hesitate to re-download the CSV as received by Pigment and try to reimport it manually to figure out whether the problem is related to the CSV input format or the saved Import configuration for the Import Configuration ID.

Legacy endpoint (deprecated)

🛡️ Warning
You should absolutely avoid creating new integrations based on this deprecated endpoint.
It is strongly encouraged to migrate existing implementations to the new endpoint documented above, as soon as possible.

The following endpoint still works but is now deprecated and will soon stop being supported:

https://pigment.app/api/importservice/Csv/ApiPush/{CONFIGURATION_ID}

The response looks like this:

{
  "tranferLogId": "f2b03cab-ba63-4525-bd59-c597f6721973",
  "nbBytesPushed": 1024
}

This response is different from the new endpoint, where these two fields are removed (they shouldn’t be used) and there is the addition of importId which can be used to track import status (see above).

The authentication header of the legacy endpoint was X-Pigment-Api-Key: {API_KEY}.

The body (to specify the file) is the same as the ones documented above for the new endpoint.

API Management

Product

Use Cases

Resources

Company

Follow