Get a contacts export

GET

/api/v3/contacts/exports/{exportId}

const url = 'https://api.tryletterhead.com/api/v3/contacts/exports/example?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/exports/example?api=true' \
  --header 'Authorization: Bearer <token>'

Returns where an export started with Start a contacts export stands, and its download link once it’s ready.

status is one of:

processing — still being built. Ask again in a minute or so.
ready — done. Download the CSV from downloadUrl before expiresAt, 7 days after it was built.
empty — your filters matched no contacts, so there’s no file.
failed — the export couldn’t be completed. Start a new one; if it fails again, contact support.

An export can be looked up for 7 days after it starts. After that, or for an exportId that isn’t yours, this returns 404.

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

Authorizations

bearerAuth

Parameters

Path Parameters

exportId

required

string

The exportId returned by Start a contacts export.

Query Parameters

api

required

boolean

Required. Set to true.

Responses

200

200 OK

application/json

object

items

object

exportId

string

status

processing, ready, empty, or failed.

string

downloadUrl

Present only when status is ready. The CSV’s download link.

string

expiresAt

Present only when status is ready. When the download link stops working (ISO 8601).

string

message

string

total

integer

Example

{
  "items": {
    "exportId": "api-20261013_141502-Vq3kT9xLm2Pz8RwYc4HnJd6F",
    "status": "ready",
    "downloadUrl": "https://api.letterhead.email/exports/eyJpdiI6Ik1rU3ZRbW...",
    "expiresAt": "2026-10-20T14:21:47+00:00"
  },
  "message": "Export status",
  "total": 0
}

404

No export with this exportId exists for your company, or it has expired.

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