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

headless with file or data

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 Guide or the Saved Schema API.

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"
  }'
tip

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.

Completed import webhook

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.