How to trigger an import with APIs

  • 21 December 2021
  • 0 replies
  • 3781 views

Userlevel 2
Badge +4

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.

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, kind of like the target path in a file server, with everything pre-configured.

 

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.

Note

Your final URL should look like this:

https://pigment.app/api/import/push/csv?configurationId=33d0d7d0-6125-47c4-b36a-882f4ed53b33

And the request header like this:

Authorization: Bearer M2pwMmUyMzItOTg3NS00MmY0LTlmY2YtNjNmZTJjZTU2OGpw

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

Note

Your final URL should look like this:

https://pigment.app/api/import/f2b03cab-ba63-4525-bd59-c597f6721973/status

And the request header like this:

Authorization: Bearer M2pwMmUyMzItOTg3NS00MmY0LTlmY2YtNjNmZTJjZTU2OGpw

 

API response

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

importStatus can have 3 values: InProgress, Completed and 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.

 

Note

The import will be displayed as if it was triggered by the person who created or edited the Import configuration.

 

Click on the image to expand the view

 

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

 

Example:

 

Click on the image to expand the view

 

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)

 

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


This topic has been closed for comments