Helpdesk Imports

Get an import (status, progress, next step)

Returns the import: status, phase, the progress of the pull (pull) and of the write (write), what the pull found (totals), why it waits (wait), the last problem (lastError), and nextStep: what to do next, in plain words.

GET

/v2/helpdesk_imports/{id}

curl --request GET \
  --url https://do.featurebase.app/v2/helpdesk_imports/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit'

{
  "account": {
    "connectedAs": "jane@acme.com",
    "conversationAccess": "all",
    "domain": "acme.freshdesk.com",
    "name": "Acme"
  },
  "companyMatch": {
    "by": "company_id",
    "fieldKey": "<string>"
  },
  "continues": {
    "importId": "<string>",
    "since": "<string>"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "createdBy": {
    "id": "<string>",
    "name": "<string>"
  },
  "expiresAt": "2026-11-02T12:00:00.000Z",
  "fields": {
    "counted": {
      "company": 123,
      "contact": 123,
      "conversation": 123
    },
    "editable": true,
    "mapped": {
      "company": 123,
      "contact": 123,
      "conversation": 123
    }
  },
  "finishedAt": "2026-11-02T12:00:00.000Z",
  "id": "6720b1c2d3e4f5a6b7c8d9e0",
  "lastError": {
    "at": "<string>",
    "code": "<string>",
    "message": "<string>",
    "stream": "<string>"
  },
  "mapping": {
    "agents": {},
    "brands": {},
    "teams": {}
  },
  "nextStep": {
    "description": "Everything was read. Check the fields (GET /v2/helpdesk_imports/{id}/fields), then start the import (POST /v2/helpdesk_imports/{id}/start).",
    "step": "map_fields"
  },
  "object": "helpdesk_import",
  "options": {
    "conversationsSince": "<string>",
    "importAttachments": true,
    "openConversations": "close",
    "snoozedConversations": "open",
    "streams": [
      "agents"
    ],
    "syncContactsToCrm": true
  },
  "phase": "pull",
  "pull": [
    {
      "counts": {
        "failed": 0,
        "files": 0,
        "filesMissed": 0,
        "listed": 0,
        "messages": 0,
        "pulled": 0,
        "skipped": 0,
        "unchanged": 0
      },
      "endedEarly": {
        "code": "<string>",
        "message": "<string>"
      },
      "pages": 123,

A running import works in the background: check it every few minutes. A large account takes hours (about 1,000 conversations an hour for Freshdesk).

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

The import id (from POST /v2/helpdesk_imports or GET /v2/helpdesk_imports).

Pattern: ^[a-f0-9]{24}$

Example: 6720b1c2d3e4f5a6b7c8d9e0

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Response

Success

accountobjectrequired

Show child attributes

companyMatchobject

How imported companies find yours (sources with matchesCompanies only).

Show child attributes

continuesobject | nullrequired

Set for "Import new changes" (POST /v2/helpdesk_imports/{id}/sync).

Show child attributes

createdAtstringrequired

createdByobjectrequired

Show child attributes

expiresAtstring | nullrequired

While the import waits for you (draft, ready, paused, needs_reconnect): when it is cancelled if nothing happens.

Example: 2026-11-02T12:00:00.000Z

fieldsobject | nullrequired

The field mapping. Null for a draft (the fields are known after the pull).

Show child attributes

finishedAtstring | nullrequired

When the import ended.

Example: 2026-11-02T12:00:00.000Z

idstringrequired

The import id.

Example: 6720b1c2d3e4f5a6b7c8d9e0

lastErrorobject | nullrequired

The last problem.

Show child attributes

mappingobjectrequired

The saved teammate, team and brand choices (see GET /v2/helpdesk_imports/{id}/teammates for what each one maps to).

Show child attributes

nextStepobjectrequired

What to do next.

Show child attributes

objectenum<string>required

Object type identifier

Available options: helpdesk_import

Example: helpdesk_import

optionsobjectrequired

Show child attributes

phaseenum<string>required

pull: reads the source into a private staging area; nothing is added to your workspace. write: adds the data.

Available options: pull, write

Example: pull

pullobject[]required

Progress of reading the source, per stream.

Show child attributes

sourcestringrequired

The tool it imports from.

Example: intercom

sourceNamestringrequired

Example: Intercom

startedAtstring | nullrequired

When the pull started.

Example: 2026-11-02T12:00:00.000Z

startedByobject | nullrequired

Show child attributes

statusenum<string>required

draft: connected, not started. running: reading the source (phase: pull) or adding the data (phase: write). ready: everything was read; map the fields, then start. paused. needs_reconnect: the source refused the key. completed, cancelled, failed.

Available options: draft, running, paused, needs_reconnect, ready, completed, cancelled, failed

Example: ready

teammatesToInviteobjectrequired

Invite them (in the dashboard) and their imported messages become their own when they join.

Show child attributes

totalsobject | nullrequired

What the pull found. Null until the pull ends.

Show child attributes

waitobject | nullrequired

Why a running import waits (for example the source's rate limit), and until when. It continues by itself.

Show child attributes

writeobject[]required

Progress of adding the data, per object.

Show child attributes

Still need help? Ask the team