How to trigger an import 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. 

Prerequisite to trigger an import

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

• Pigment API Key: this secret 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.

Send API request

Use this POST endpoint to trigger an import:

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

• Replace {CONFIGURATION_ID} by the ID retrieved in the previous step.
• The CSV file to push needs to be sent in the request body.
• 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.

API response

Calling the endpoint 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

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/import/{IMPORT_ID}/status

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

API response

{
  "importId": "f2b03cab-ba63-4525-bd59-c597f6721973",
  "createdAt": "2023-10-04T16:17:07.739855Z",
  "completedAt": "2023-10-04T16:17:10.243325Z",
  "importStatus": "Failed"
}

Example

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

# Get status
curl -X GET "https://pigment.app/api/import/${IMPORT_ID}/status" \
-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.

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)

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 2 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.