Headless Quickstart
The Headless API allows you to import CSVs and spreadsheet files programatically.
With Headless, you can send a file or JSON payload to Dromo and specify a schema that defines the desired shape and constraints of the final data file.
If there are no problems with the import, Dromo will send you the cleaned data in the JSON format, just like an embedded import.
If there are any issues with the import (like missing columns or failing data validations), Dromo provides a URL for a user to resolve them using the same interface as for embedded imports.
Activation
To get started with the Headless API, Dromo will need to enable Headless for your organization. The Headless API is a premium add-on to Dromo Enterprise.
Once your account is set up, get in touch and we can get you ready to go!
Using the Headless Importer
A headless import can be run either on a file or a JSON object. The steps below walk through the procedure for either type of import.
You will need a saved schema to guide the import. For more information about saved schemas, check out the Schema Studio Quickstart or the Saved Schema API.
- Importing a File
- Importing JSON
1. Create a new headless import
The import process starts by creating a new headless import record. You will use this record to check the status of the import and retrieve the results.
To create a headless import, use the create headless import endpoint.
You must provide two things when creating the import:
- The ID of the saved schema you want to use
- The original filename of the file you want to import
Here is an example request:
curl \
-H "Content-Type: application/json" \
-H "X-Dromo-License-Key: your-backend-key" \
-X POST \
'https://app.dromo.io/api/v1/headless/imports/' \
-d '{
"schema_id": "4eefe3fe-7181-4562-aa28-8cfe1c5bdf1b",
"original_filename": "data.csv"
}'
Each headless import allows you to import only one file.
2. Upload the file
Once you've created the import record, Dromo will return an ID
and a URL (in the "upload"
field) where you can upload the file.
Store the ID for later use (you need it to fetch the import status and results).
To upload the file, make a PUT request to the URL, with the file as the body. Note that the upload URL is only valid for 30 minutes, so only create the import record when you are ready to upload the file.
Here is an example request for uploading the file:
curl \
-X PUT \
'https://dromo-headless-imports-prod.s3.us-west-2.amazonaws.com/74033520-fee6-4edb-9a30-8c5b3fcd513f?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIARY5HJCMTO2AUIBEU%2F20230227%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230227T181454Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=14241560a7d9dff1e9d2bb8d8d1445880df1860a9c96728c5fb0dd2e123c0011' \
--data-binary "@/path/to/data.csv"
4. Wait for the import to run
Dromo will automatically begin the import process once the upload is complete.
5. Handle import result
You can query for the current import status using the retrieve headless import endpoint.
The import status will be one of the following:
AWAITING_UPLOAD
: The import record has been created, but the import file has not yet been uploaded.PENDING
: The import file has been received, and the import process will begin shortly.RUNNING
: The import process is currently running.SUCCESSFUL
: The import was successful and the result data is ready to be retrieved.NEEDS_REVIEW
: The import could not be completed due to data validation errors, and requires human attention.FAILED
: The import encountered a fatal error, and cannot be processed.
Successful import
If the import data did not have any issues, the import will be in the SUCCESSFUL
state.
If you define a legacy webhookUrl or associate a managed webhook with your schema, the webhook will fire normally when the import completes successfully.
You can access the import results via the retrieve headless import results endpoint. This endpoint works exactly like the standard retrieve import results endpoint.
Import needs review
If the import has issues that need manual review, the import will be in the NEEDS_REVIEW
state.
This can happen for several reasons:
- A multisheet Excel file was uploaded and a sheet could not be automatically chosen
- The header row could not be determined
- The columns could not be mapped automatically
- There are failing data validations, and invalidDataBehavior is set to
BLOCK_SUBMIT
When an import is in the NEEDS_REVIEW
state, the data returned by the retrieve headless import endpoint will include a "review_url"
field.
This is a URL which you can navigate to in a browser to resolve the import issues using Dromo's
import UI.
After resolving the issues and completing the import, the import will transition to the SUCCESSFUL
state.
Import failed
An import will enter the FAILED
state if it has an unrecoverable error.
Some examples of unrecoverable errors are:
- The JSON was of invalid format
- The data was completely empty
- A custom hook threw an unhandled exception
Failed imports do not have results and also do not have a review URL.
1. Create a new headless import
The import process starts by creating a new headless import record. You will use this record to check the status of the import and retrieve the results.
To create a headless import, use the create headless import endpoint.
You must provide two things when creating the import:
- The ID of the saved schema you want to use
- The complete JSON data
Here is an example request:
curl \
-H "Content-Type: application/json" \
-H "X-Dromo-License-Key: your-backend-key" \
-X POST \
'https://app.dromo.io/api/v1/headless/imports/' \
-d '{
"schema_id": "4eefe3fe-7181-4562-aa28-8cfe1c5bdf1b",
"initial_data": '[{"product": "widget1", "transaction": "foo123"}, {"product": "widget2", "transaction": "foo456"}]'
}'
2. Wait for the import to run
The import will start immediately.
3. Handle import result
You can query for the current import status using the retrieve headless import endpoint.
The import status will be one of the following:
PENDING
: The import has been queued, and the import process will begin shortly.RUNNING
: The import process is currently running.SUCCESSFUL
: The import was successful and the result data is ready to be retrieved.NEEDS_REVIEW
: The import could not be completed due to data validation errors, and requires human attention.FAILED
: The import encountered a fatal error, and cannot be processed.
Successful import
If the import data did not have any issues, the import will be in the SUCCESSFUL
state.
If you define a legacy webhookUrl or associate a managed webhook with your schema, the webhook will fire normally when the import completes successfully.
You can access the import results via the retrieve headless import results endpoint. This endpoint works exactly like the standard retrieve import results endpoint.
Import needs review
If the import has issues that need manual review, the import will be in the NEEDS_REVIEW
state.
This can happen for several reasons:
- The header row could not be determined
- The columns could not be mapped automatically
- There are failing data validations, and invalidDataBehavior is set to
BLOCK_SUBMIT
When an import is in the NEEDS_REVIEW
state, the data returned by the retrieve headless import endpoint will include a "review_url"
field.
This is a URL which you can navigate to in a browser to resolve the import issues using Dromo's
import UI.
After resolving the issues and completing the import, the import will transition to the SUCCESSFUL
state.
Import failed
An import will enter the FAILED
state if it has an unrecoverable error.
Some examples of unrecoverable errors are:
- The import file was corrupted and could not be parsed
- The import file was completely empty
- A custom hook threw an unhandled exception
Failed imports do not have results and also do not have a review URL.