Helpdesk Imports

Connect a source account (create an import)

Creates an import (a draft) after Featurebase checks the key with the source. Send source and its credential (see GET /v2/helpdesk_imports/sources):

POST

/v2/helpdesk_imports

curl --request POST \
  --url https://do.featurebase.app/v2/helpdesk_imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "credential": {
    "accountId": "https://app.crisp.chat/settings/website/6b1f0c2e-3d4a-4e5b-8c6d-7e8f9a0b1c2d/",
    "apiKey": "dG9rOmFiYzEyMw==",
    "secret": "<string>",
    "subdomain": "acme.freshdesk.com"
  },
  "source": "intercom"
}
'

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

Intercom: { "apiKey": "<access token>" } (+ subdomain: EU or AU for workspaces hosted there).
Freshdesk: { "subdomain": "acme.freshdesk.com", "apiKey": "<API key of an administrator>" }.
Crisp: { "apiKey": "<token>", "accountId": "<address of the Crisp settings page, or the website ID>" }.

The key is stored encrypted, never returned, and deleted when the pull ends. Nothing is read or added yet. Next: map the teammates (GET /v2/helpdesk_imports/{id}/teammates). A draft is cancelled after 7 days without a change.

Authorizations

Authorizationstringheaderrequired

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

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

credentialobjectrequired

The fields each source needs are listed by GET /v2/helpdesk_imports/sources (credentialFields).

Show child attributes

sourcestringrequired

The tool to import from: intercom, freshdesk or crisp (the id of a source from GET /v2/helpdesk_imports/sources).

Required string length: 1 - 50

Example: intercom

Response

Created

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