Keep columns as custom fields and continue an import

POST

/api/v3/contacts/imports/{importUniqueId}/field-setup

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/contacts/imports/example/field-setup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "api": true, "fields": [ { "column": "Neighborhood", "type": "text" } ] }'

• Production

Answers an import whose status is needsFieldSetup. Each entry in fields keeps one column: Letterhead creates a custom field named after the column (or uses the custom field you already have with that name) and the import fills it. Every other column the import stopped on is skipped. Send an empty fields array to skip them all. Returns 202 Accepted — the import continues asynchronously.

A kept cell that doesn’t fit its field’s type is left out of that contact, and the contact still imports. Where another mapped column already feeds the same field, its value wins on each row.

Returns 409 when the import is no longer waiting on field setup (it was already answered or cancelled), and 422 — changing nothing — when the upload has expired, a column isn’t one the import stopped on, two columns would become one field, or a column’s name is one Letterhead already uses.

This is a company-level (v3) write. Authenticate with a company API key as a Bearer token.

Authorizations

• bearerAuth

Parameters

Path Parameters

importUniqueId

required

string

The import’s unique identifier, from List subscriber imports.

Request Body ^required

Media type application/json

object

api

required

Required. Set to true to authenticate with an API key.

boolean

fields

required

The columns to keep — at most 50, each column once. Send [] to skip every column.

Array<object>

<= 50 items

object

column

required

The column’s header, as returned by Get an import’s columns awaiting field setup.

string

type

required

text, number, boolean, or date. Ignored when the column fills a custom field you already have.

string

Example

{
  "api": true,
  "fields": [
    {
      "column": "Neighborhood",
      "type": "text"
    }
  ]
}

Responses

202

Import resumed.

Media type application/json

object

items

nullable

message

string

total

integer

Example

{
  "items": null,
  "message": "Import resumed.",
  "total": 1
}