Run an import with a manage key

This page covers running an import with a manage key, the same imports as Integration › Imports. Every path here is under https://prd-api-manage.caseactive.com/v1/integration/<hub id>. For the file's columns, see Look up the columns each import needs.

Calls

1. Create the import

curl -X POST https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October claimants", "source": "claims-sync", "type": "post_user"}'

It answers 201 with the import_id, such as import::20261002141503_3f9a1c2b7d4e60.

2. Upload the file

Ask for an upload address with GET /drive/private?import_id=<import_id>&media_group=docs&media_extension=csv. It answers a url and a set of fields. Send the file there as a multipart/form-data POST, with every entry of fields exactly as given, and the file last, as file:

curl -X POST "<url>" \
  -F "key=<fields.key>" \
  -F "<every other entry of fields, as given>" \
  -F "file=@october-claimants.csv"

• The address works for an hour.
• Save the file as CSV UTF-8, with the column names in the first row.
• A file holds up to 25,000 rows under the column names. A longer one fails the import and imports nothing: split it into files of 25,000 rows or fewer, with an import for each.
• Keep fields.key: it's how you attach the file next.

3. Attach the file

PUT /imports/<import_id> with the upload's key starts the import. It answers 204.

{"media_key": "<fields.key>"}

Attach a file once. If the import fails, correct the file and start a new import.

4. Check progress

GET /imports lists your imports, newest first, with each one's status, total, passed and failed:

• QUEUED: created, or attached but not yet read.
• PROCESSED: the file has been read into total rows, which run one at a time. It's finished when passed and failed add up to total.
• FAILED: the file couldn't be read, held no rows, or held more than 25,000; the import's error_msg says which: ImportFileUnreadableException, ImportFileEmptyException or ImportFileTooLargeException.

Rows run in your hub's turn with every other import, so a large file takes a while. Your hub's Admins and Managers are emailed when an import or its first row fails.

GET /imports/<import_id> lists the rows that have run, in the order they're in your file, with limit (up to 1000) and start_key:

{
  "data": {
    "items": [
      {
        "unique_id": "unique::20261002141503_3f9a1c2b7d4e60_0000002",
        "line": 2,
        "type": "post_user",
        "status": "SUCCEEDED",
        "data": {"username": "jane.sample@example.com", "given_name": "Jane", "family_name": "Sample", "host_ref_id": "cl-1042"},
        "output": {"host_id": "ca-7e6d5c4b3a2f10", "user_id": "cu-4f1c2a9e8b7d60"}
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports/import::20261002141503_3f9a1c2b7d4e60"
  }
}

A row counts as succeeded only when it made its change. A row whose Tag ID, Reference ID or person clashes with another record fails, with the refusal's name in error_msg. An Assign users to cases or Create case posts row naming a closed case fails with {"_schema": ["Case is closed"]} in schema_errors: reopen the case, then import the row again.

A row's unique_id is made from the import's ID and the row's number in your file, so row 2 of import::20261002141503_3f9a1c2b7d4e60 is unique::20261002141503_3f9a1c2b7d4e60_0000002.

5. Retry a row

PUT /imports/<import_id>/<unique_id> with {"retry": true} runs a failed row again, exactly as it was, at the back of your hub's turn. It answers 204, and the import's failed count drops by one until the row has run. Use it for a row that failed for a passing reason, such as a busy moment. A row whose cells were wrong fails again: correct the file and start a new import.

What happens next

An import's rows do what the same rows do on screen: added people aren't emailed, people put on cases with the invitation get it, new cases run your Assign Cases rules, and new posts notify the case's people. The import is recorded as your hub's Virtual AssistantVirtual Assistant An automated team member that posts welcome messages, check-ins and stage updates for the firm; its posts carry a Virtual Assistant badge.'s. Sending the same file twice runs every row again: rows that clash with the first run fail, and posts are made twice. To fix failed rows on screen instead, see Fix an import with failed rows.

If a call is refused