Helpdesk Imports

Update options, teammates, fields or the company match

Changes the choices of an import. Only what you send changes: one teammate, one field, or one option at a time is fine, and changes sent at the same time are merged one after another (with many at once, a change that keeps losing answers 409 revision_conflict: send it again). Many fields fit in one call.

PATCH

/v2/helpdesk_imports/{id}

curl --request PATCH \
  --url https://do.featurebase.app/v2/helpdesk_imports/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "companyMatch": {
    "by": "domain",
    "fieldKey": "cf_crm_id"
  },
  "fieldMapping": {
    "contact": {
      "cf_legacy_id": {
        "kind": "skip"
      },
      "cf_plan": {
        "kind": "new",
        "name": "Plan"
      }
    }
  },
  "mapping": {
    "agents": {
      "5123456": "6720b1c2d3e4f5a6b7c8d9e1"
    },
    "brands": {
      "42": "6720b1c2d3e4f5a6b7c8d9e2"
    },
    "teams": {
      "901": "new"
    }
  },
  "options": {
    "conversationsSince": "2025-01-01T00:00:00.000Z",
    "importAttachments": true,
    "openConversations": "close",
    "snoozedConversations": "open",
    "streams": [
      "companies",
      "contacts",
      "conversations"
    ],
    "syncContactsToCrm": false
  }
}
'

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

options (before the pull): what to import (streams), conversationsSince, openConversations (close / keep_open), snoozedConversations, syncContactsToCrm, importAttachments.
mapping (before the pull): source agent → teammate, source team → team (or new), Freshdesk product → brand. Ids of the source come from GET /v2/helpdesk_imports/{id}/teammates.
fieldMapping (once the pull started, until the start; the field list is read then): source custom field → attribute ({ "kind": "attribute", "attributeId": "…" }), a new attribute ({ "kind": "new", "name": "Plan" }), a Featurebase field (builtin), or { "kind": "skip" }; null = back to the suggestion. Keys come from GET /v2/helpdesk_imports/{id}/fields. Example, to skip two contact fields: { "fieldMapping": { "contact": { "cf_a": { "kind": "skip" }, "cf_b": { "kind": "skip" } } } }.
companyMatch (until the start): how imported companies find yours.

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

companyMatchobject

Show child attributes

fieldMappingobject

Custom fields, by the key from GET /v2/helpdesk_imports/{id}/fields. Only the fields you send change; a field without a choice gets the suggestion. Can change until the import starts adding data.

Show child attributes

mappingobject

Teammates, teams and brands (before the pull only). Only the entries you send change; the others keep their choice.

Show child attributes

optionsobject

Only the options you send change.

Show child attributes

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