---
title: "Trigger an import and check status with APIs"
slug: "trigger-import-apis"
description: "Automate your data import process with Pigment's API. Learn how to use the Import API, manage API keys, and check import status effectively."
tags: ["Data Import", "Import Configuration", "Importing Exporting Data", "Pigment API"]
updated: 2026-01-05T14:18:09Z
published: 2026-01-05T14:18:09Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.pigment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger an import and check status with APIs

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](/v1/docs/manage-api-keys) to get one.
- **Import Configuration ID**. This ID represents the import configuration. Check the [Import configuration documentation](/v1/docs/generate-import-config-id) to see how to generate one.

> [!NOTE]
> ℹ️ **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](/v1/docs/manage-api-keys).

## Swagger / OpenAPI specification

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

## Configure an Import API request

> [!NOTE]
> ℹ️ 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}`

> [!WARNING]
> ⚠️ 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](/v1/docs/trigger-import-apis#before-you-begin) step or from the [Metadata API](/v1/docs/retrieve-info-metadata-api#get-import-configurations-from-a-block).
- To authenticate the API call, you need to add an HTTP [Authorization](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) header to your request: `Authorization: Bearer {API_KEY}`
- Replace **{API_KEY}** by the key retrieved in the previous step.

> [!NOTE]
> ℹ️ **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`

> [!WARNING]
> **⚠️****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](/v1/docs/manage-api-keys).

### 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).

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

### Example for a CSV File Import

cURL example:

```plaintext
# 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]
> ℹ️ **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

```plaintext
{
  "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:

```plaintext
# 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]
> ℹ️ **Note**
> 
> The import will be displayed as if it had been triggered by the person who created or edited the Import configuration.

![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/99f05c9a-59b7-4ecb-814b-223349ba2572.png)

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

*Example:*

![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/025befd9-5617-4c0f-b09a-1828b5e7102c.png)

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*)

> [!CAUTION]
> **🛡️****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:

```plaintext
{
  "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.