Helpdesk Imports

Add the data to the workspace (step 2 of 2)

Starts adding the pulled data to your workspace (the dashboard's "Start import"): status ready only. The field mapping is applied now: new attributes are created first.

POST

/v2/helpdesk_imports/{id}/start

curl --request POST \
  --url https://do.featurebase.app/v2/helpdesk_imports/{id}/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "confirmLiveEmails": true,
  "confirmSnoozeEffects": true
}
'

{
  "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,

Live emails with a dynamic audience would send to the people the import adds: then the call answers 409 confirmation_required with details.liveEmails (how many, and their names when you may manage outbound). Tell the user; send confirmLiveEmails: true only if they agree (or pause those emails first). The same for details.snoozeEffects and confirmSnoozeEffects. Never send a confirmation before a 409 asked for it.

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

Body

confirmLiveEmailsboolean

Send true only after the user agreed: live emails with a dynamic audience will send to the people the import adds. Asked only when such emails are live (409 with details.liveEmails).

Example: true

confirmSnoozeEffectsboolean

Send true only after the user agreed: the imported snoozed conversations wake up later and run the workspace's workflows, webhooks or reassignment. Asked only when that applies (409 with details.snoozeEffects).

Example: true

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