Helpdesk Imports

List the source's custom fields, and where each goes

After the pull: the custom fields of conversations, contacts and companies, how many records use each (used), a few example values, and where each goes (mapsTo: the choice, else the suggestion, with reason). Also your attributes a field can map to (attributes) and how many more attributes you can create (room). Change them with PATCH /v2/helpdesk_imports/{id} and fieldMapping.

GET

/v2/helpdesk_imports/{id}/fields

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

{
  "attributes": {
    "company": [
      {
        "id": "<string>",
        "name": "<string>",
        "type": "text"
      }
    ],
    "contact": [
      {
        "id": "<string>",
        "name": "<string>",
        "type": "text"
      }
    ],
    "conversation": [
      {
        "id": "<string>",
        "name": "<string>",
        "type": "text"
      }
    ]
  },
  "counted": {
    "company": 123,
    "contact": 123,
    "conversation": 123
  },
  "editable": true,
  "fields": {
    "company": [
      {
        "builtin": {
          "field": "<string>",
          "label": "<string>"
        },
        "chosen": true,
        "examples": [
          "<string>"
        ],
        "key": "cf_plan",
        "label": "Plan",
        "mapsTo": {
          "attributeId": "<string>",
          "field": "<string>",
          "kind": "attribute",
          "name": "<string>"
        },
        "newName": "<string>",
        "options": [
          "<string>"
        ],
        "reason": "same_name",
        "type": "text",
        "used": 123
      }
    ],
    "contact": [
      {
        "builtin": {
          "field": "<string>",
          "label": "<string>"
        },
        "chosen": true,
        "examples": [
          "<string>"
        ],
        "key": "cf_plan",
        "label": "Plan",
        "mapsTo": {
          "attributeId": "<string>",
          "field": "<string>",
          "kind": "attribute",
          "name": "<string>"
        },
        "newName": "<string>",
        "options": [
          "<string>"
        ],

Suggestions skip fields of other tools, secrets, ids and rarely used fields. Fields that duplicate a Featurebase field (builtin) need nothing.

Big accounts have hundreds of fields: ask one object at a time (object=contact).

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

Query Parameters

objectenum<string>query

Only the fields (and attributes) of conversation, contact or company. Big accounts have hundreds of fields: ask one object at a time.

Available options: conversation, contact, company

Example: contact

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

attributesobjectrequired

Your attributes a field can map to (kind: attribute).

Show child attributes

countedobjectrequired

Records counted per object for used.

Show child attributes

editablebooleanrequired

The mapping can still change (the import has not started adding data).

fieldsobjectrequired

Show child attributes

importIdstringrequired

objectenum<string>required

Available options: helpdesk_import_fields

Example: helpdesk_import_fields

roomobjectrequired

How many more attributes the workspace can create, per object (conversationText: text conversation attributes).

Show child attributes

Still need help? Ask the team