Get an import's columns awaiting field setup

GET

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

const url = 'https://api.tryletterhead.com/api/v3/contacts/imports/example/field-setup?api=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/contacts/imports/example/field-setup?api=true' \
  --header 'Authorization: Bearer <token>'

This step may need to be enabled for your account — contact support if your imports never reach needsFieldSetup.

For an import whose status is needsFieldSetup, lists the columns in its file that match no contact field, each with a few example values from the file and a suggested custom-field type. Answer with Keep columns as custom fields and continue an import, or cancel with Cancel an import awaiting field setup.

Returns 409 when the import is no longer waiting on field setup, and 422 when its upload has expired (import the file again).

This is a company-level (v3) read. 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.

Query Parameters

api

required

boolean

Required. Set to true.

Responses

200

200 OK

application/json

object

items

Array<object>

object

column

The column’s header, exactly as it appears in the file. Use it as column when answering.

string

sampleValues

A few values from the file’s first rows.

Array<string>

suggestedType

text, number, boolean, or date. When existingFieldLabel is set, this is that field’s own type.

string

existingFieldLabel

The label of the custom field you already have with this column’s name, which a kept column fills instead of creating a new one. null when there’s no such field.

string

nullable

canKeep

false when Letterhead already uses this name (for example source, tags, phone, or a channel slug), so the column can’t be kept unless it is renamed in the file.

boolean

message

string

total

integer

Example

{
  "items": [
    {
      "column": "Neighborhood",
      "sampleValues": [
        "Riverside",
        "Old Town"
      ],
      "suggestedType": "text",
      "existingFieldLabel": null,
      "canKeep": true
    }
  ],
  "message": "Columns awaiting field setup retrieved.",
  "total": 1
}

Still can’t find what you need? Contact support.