Import & Export

Once an account is connected, moving files takes three calls:

Browse to let the user choose a folder
Transfer to create the link and start a run
Poll or subscribe to follow progress

Step 1: Browse the provider

Browse returns one level at a time. With no parameters you get the top-level containers—matters for Clio, My Drive and shared drives for Google Drive.

Endpoint

GET /connectors/v1/connections/{id}/browse

cURL

curl "https://api.case.dev/connectors/v1/connections/conn_abc123/browse?page_size=100" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Response

{
  "items": [
    {
      "id": "1a2b3c",
      "name": "Smith v. Hospital",
      "kind": "matter",
      "browse_ref": { "kind": "folder", "folder_id": "1a2b3c" },
      "import_ref": { "folder_id": "1a2b3c" }
    }
  ],
  "cursor": null
}

To descend, pass back the browse_ref fields from the item the user picked:

cURL

curl "https://api.case.dev/connectors/v1/connections/conn_abc123/browse?container=drv_99&parent=1a2b3c" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Parameter	Description
`container`	Container id—a shared drive or a matter
`parent`	Folder id to list inside
`query`	Provider-supported search text, scoped to the current level
`cursor`	Continuation from a previous page
`page_size`	Up to 1000

Item kind is one of my_drive, shared_drive, matter, folder, or file. The enum also reserves site and document_library for providers that group drives under sites; neither current provider returns them, and the site query parameter is likewise unused.

browse_ref and import_ref are opaque references. Pass them back exactly as received.Never construct one from a provider id supplied by a browser, and never accept one as user input in your own API. These values are how the service decides what a caller is allowed to reach.

Some items are browsable but not importable, and some are the reverse. When an item carries an import_ref that differs from its browse_ref, use import_ref as the link’s remote.

Browsing needs a connection scope that permits server-side listing. If it does not, you get 403 provider_scope_insufficient—the user consented at a narrower tier than browsing requires.

Step 2: Create the link and run it

Endpoint

POST /connectors/v1/transfer

cURL

curl -X POST https://api.case.dev/connectors/v1/transfer \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "import",
    "connection_id": "conn_abc123",
    "remote": { "folder_id": "1a2b3c", "path": "Smith v. Hospital" },
    "vault_id": "vault_abc123",
    "policy": {
      "deletes": "preserve",
      "filters": { "max_size_bytes": 209715200 }
    }
  }'

Response (202)

{
  "links": [{ "id": "link_55aa", "direction": "import", "mode": "once", "state": "running" }],
  "run": { "started": true }
}

A link’s identity is (connection_id, direction, remote, vault_id). The first call creates it and runs a full backfill. Every later call with the same four values runs an incremental diff against the ledger—so “Re-import” in your UI is this exact request again. If a run is already active, the existing run is returned instead of an error. Double-clicking is safe.

Exclude folders or files

For Clio and Google Drive document imports, include policy.filters.exclude_folder_ids and policy.filters.exclude_file_ids with stable provider IDs from browsing. Excluding a folder excludes its entire subtree. New files in included folders continue importing, while these exclusions apply to subsequent runs and full reconciliations. Existing vault copies are preserved. Exclusions require policy.deletes: "preserve" (the default); combining exclusions with deletes: "mirror" returns 400. For direction: "both", exclusions are stored on the import half only; the export half retains other policy settings. Each list accepts up to 1,000 IDs. The import root cannot be excluded. These filters do not apply to exports, Clio tasks, or Clio communications. Connections advertise support through import_exclusions_supported: true. An existing source link keeps its selection. Repeating a transfer with a different selection returns 409 import_selection_conflict; use the link policy update endpoint to deliberately change an existing link’s filters. PATCH /connectors/v1/links/{id} replaces the entire stored policy. Include every policy field you want to retain, including deletes, collisions, and existing size/MIME filters. Omitted fields return to their defaults; PATCH does not merge policy objects.

Field	Description
`direction`	`import`, `export`, or `both`
`remote.folder_id`	Required. From the browse `import_ref` or `browse_ref`.
`remote.resource_type`	Provider-declared collection. Omit for the provider default.
`vault_id`	Destination vault. Must be granted if you use installations.
`matter_id`	Optional association with a matter
`run_mode`	`auto` (default) or `full_reconcile` to force a complete re-scan
`export_destination`	For `direction: "both"`. Defaults to a `CaseMark Output` subfolder under `remote`.

When a run does not start

run.started can be false with a reason. This is not an error:

Reason	Meaning
`already_running`	A run for this link is in flight
`stale_run_recovery`	A previous run is being reconciled first
`ingestion_backlog`	The vault ingestion queue is saturated; `backlog` gives the depth

The link is created either way. Poll it and the run will begin.

Keeping a folder current

For a standing promise instead of a one-shot, use /sync-link. Same body, minus run_mode.

Endpoint

POST /connectors/v1/sync-link

It backfills now, then stays current on a sweep cycle. Due links run incrementally about every 15 minutes. Once a day the sweep runs a full reconcile instead, which catches deletions and moved folders that per-file change feeds cannot report. An existing once link is upgraded in place, keeping its ledger and cursor. Nothing re-imports. To step back down or pause:

cURL

curl -X PATCH https://api.case.dev/connectors/v1/links/link_55aa \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "once" }'

PATCH also accepts state (paused or ready) and a replacement policy.

Step 3: Follow progress

Endpoint

GET /connectors/v1/links/{id}

Response

{
  "id": "link_55aa",
  "direction": "import",
  "mode": "once",
  "automation_status": "manual_only",
  "state": "running",
  "vault_id": "vault_abc123",
  "counts": {
    "synced": 118,
    "pending": 12,
    "queued": 9,
    "processing": 3,
    "failed": 1,
    "skipped": 4,
    "tombstoned": 0
  },
  "active_run": {
    "id": "run_77cd",
    "trigger": "manual",
    "mode": "backfill",
    "status": "running",
    "stats": { "listed": 135, "added": 118, "updated": 0, "deleted": 0, "skipped": 4, "failed": 1, "bytes": 884213504 },
    "started_at": "2026-01-15T10:32:00Z",
    "finished_at": null,
    "error": null
  },
  "last_run": null
}

Link states

State	Meaning
`ready`	Idle, will run when asked or swept
`running`	A run is executing
`active`	Synced and current
`paused`	Suspended—by you, or by a lost grant
`orphaned`	Its provider folder or vault is gone. `orphan_reason` says which.
`error`	The last run failed in a way that needs attention

Run statuses

running, completed, completed_with_errors, or failed. completed_with_errors means the run finished and some files failed—check the ledger for which.

counts.pending is the umbrella for everything not yet settled. queued and processing are subsets of it, so do not add them together.

Per-file results

Run stats tell you how many. The ledger tells you which.

Endpoint

GET /connectors/v1/links/{id}/objects

cURL

curl "https://api.case.dev/connectors/v1/links/link_55aa/objects?state=failed" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Each row carries the provider item, the vault object it became, its path, its content version, its state, and an error when one applies.

State	Meaning
`pending`	Recorded, not started
`transferring`	Bytes in flight
`ingesting`	In the vault, being OCR’d and indexed
`synced`	Done
`skipped`	Excluded by policy—size or MIME filter
`failed`	Did not transfer. The row carries the reason.
`tombstoned`	Source file is gone and the delete policy was applied

Filter by state and page with cursor.

Events instead of polling

For anything longer than a few seconds, subscribe rather than poll. These events carry connector progress:

Event	Fires when
`run.completed`	A run finished, with full stats—possibly with per-file errors
`run.failed`	A run failed before completing
`link.objects_changed`	A run changed the set of synced objects
`link.orphaned`	The provider folder, provider access, or vault went away
`connection.reauth_required`	The account needs reconnecting

All connector events require the connectors scope on your webhook endpoint.

Deleting a link

Endpoint

DELETE /connectors/v1/links/{id}

Deletes the link and its ledger. Vault documents are kept by default. Add ?vault_docs=delete to remove the documents an import link brought in. That cleanup runs as a durable background workflow and returns 202.

vault_docs=delete is not reversible. Confirm with the user before calling it.

Next steps

Errors & Recovery

What each failure means and which ones to retry

Providers

How Clio and Google Drive differ in hierarchy, change detection, and rate budget

Vault Search

Search the documents once they have been ingested

Get Started

Platform

Resources

Step 1: Browse the provider

Step 2: Create the link and run it

Exclude folders or files

When a run does not start

Keeping a folder current

Step 3: Follow progress

Link states

Run statuses

Per-file results

Events instead of polling

Deleting a link

Next steps

Errors & Recovery

Providers

Vault Search

​Step 1: Browse the provider

​Step 2: Create the link and run it

​Exclude folders or files

​When a run does not start

​Keeping a folder current

​Step 3: Follow progress

​Link states

​Run statuses

​Per-file results

​Events instead of polling

​Deleting a link

​Next steps

Errors & Recovery

Providers

Vault Search

Step 1: Browse the provider

Step 2: Create the link and run it

Exclude folders or files

When a run does not start

Keeping a folder current

Step 3: Follow progress

Link states

Run statuses

Per-file results

Events instead of polling

Deleting a link

Next steps