Helpdesk Imports

Import new changes

Creates a new import (a draft) that brings over what changed in the source since a completed import: new and updated conversations, contacts and companies. It keeps that import's options (with open conversations kept open: use it when the team switches over), its teammate mapping and its fields. Send the key again (it was deleted when that import ended). Then pull and start the new import.

POST

/v2/helpdesk_imports/{id}/sync

Import new changes

curl --request POST \
  --url https://do.featurebase.app/v2/helpdesk_imports/{id}/sync \
  --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"
  }
}
'

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

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

credentialobjectrequired

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

Show child attributes

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