Import-Export

Import Entities

Changed on

This endpoint enables the import of entities into the platform. The entities should be provided in a CSV format inside an S3 bucket. This API will return the `job_id`` which can be used to fetch the status of the import process.

post/v1/entity:import

Request

  • Base URL
    https://entity.sls.epilot.io
  • URL
    https://entity.sls.epilot.io/v1/entity:import
  • Auth
    • HTTP bearer
    • or API key in header x-epilot-org-id

Query parameters

job_idstring

The unique identifier of the import job.

Example:abc123

The ID of the import job. This ID is used to track the progress and fetch the result of the import operation.

Request body

schemastring required

The schema of the entities being imported. This must match the schema of the entities on the platform.

unique_keystring[]

Attribute names (text, email or number) used to match rows to existing entities, combined with AND. Use ["_id"] to match by entity id only. Empty by default, which keeps the current behaviour.

dry_runboolean

Report the outcome of every row without writing any entities.

dry_run_job_idstring

The job id of a completed dry run that this import commits. Cannot be combined with dry_run.

trigger_automationsboolean

Write committed rows as normal creates and updates: they emit entity events, so automations run, and each entity gets its activities. Off by default, when imported rows trigger no automations. Cannot be combined with dry_run: true.

Example request

{
  "S3Reference": {
    "bucket": "my-bucket",
    "key": "imports/my-import.json"
  },
  "schema": "contact",
  "unique_key": [
    "email"
  ]
}

Response

The import operation was initiated successfully. The response includes the URLs for the files containing the successful and failed imported entities.

jobPollIdstring

The ID of the import job.

trigger_automationsboolean

Whether committed rows of the job trigger automations.

started_bystring

User id of whoever started the job. A finished job is only returned by entity:import:latest to this user, and only this user can commit or discard a dry run.

status'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED'
totalinteger

Number of data rows in the file, once known.

importedEntitiesCountinteger
failedEntitiesCountinteger
importedEntitiesUrlstring
failedEntitiesUrlstring
updated_atstring date-time
failure_reasonstring
failure_code'invalid_csv_bad_headers' | 'dry_run_required' | 'dry_run_mismatch' | 'dry_run_expired' | 'import_file_changed' | 'prescan_missing' | 'import_too_large' | 'token_expired' | 'max_duration_exceeded' | 'no_progress' | 'internal_error'

Machine readable reason of a failed job. failure_reason holds the human text.

  • invalid_csv_bad_headers: the file has neither a _schema nor an _id column
  • dry_run_required, dry_run_mismatch, dry_run_expired: the dry-run rule rejected the commit before any row
  • import_file_changed: the file was replaced after the pre-scan
  • prescan_missing: the job cannot be continued after an update
  • import_too_large: the file has more rows than a single job can report on
  • token_expired: the session that started the job expired before it finished
  • max_duration_exceeded: the job ran longer than allowed
  • no_progress: consecutive runs made no progress
  • internal_error: an unexpected error ended the job
abortableboolean
dry_runboolean
unique_keystring[]
report_urlstring

Download link of the per-row report (CSV, UTF-8 with BOM).

phase'scanning' | 'dry_run' | 'importing' | 'finalizing' | 'done'

What the job is doing now: scanning the file (pre-scan), running the dry_run or importing rows, finalizing the report, or done (every terminal status).

heartbeat_atstring date-time

Refreshed at every phase change and at least every few seconds while the job makes progress (rows or pre-scan). A PROCESSING job whose heartbeat is minutes old may be stuck.

started_atstring date-time

When the job started.

finished_atstring date-time

When the job ended; set on a terminal status.

Changes

  • 299db8038dd4Revision changes
    • warning

      added the new dry_run_expired enum value to the response property for the response status

    • warning

      added the new dry_run_mismatch enum value to the response property for the response status

    • warning

      added the new dry_run_required enum value to the response property for the response status

    • warning

      added the new import_file_changed enum value to the response property for the response status

    • warning

      added the new import_too_large enum value to the response property for the response status

    • warning

      added the new internal_error enum value to the response property for the response status

    • warning

      added the new invalid_csv_bad_headers enum value to the response property for the response status

    • warning

      added the new max_duration_exceeded enum value to the response property for the response status

    • warning

      added the new no_progress enum value to the response property for the response status

    • warning

      added the new prescan_missing enum value to the response property for the response status

    • warning

      added the new token_expired enum value to the response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • dcab4cb50e1bRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the media type application/json for the response with the status