Skip to main content

Headless Quickstart

The Headless API allows you to import CSVs and spreadsheet files programatically.

With Headless, you can send a file 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 Pro.

Once your account is set up, get in touch and we can get you ready to go!

1. Create a schema​

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.

2. 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"
  }'

NB: Each headless import allows you to import only one file.

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

Once the file upload completes, Dromo will automatically begin the import process.

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 file did not have any data issues, the import will be in the SUCCESSFUL state.

Completed import webhook

If you define a webhookUrl for 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 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.