Contact Lists v1

Five steps from nothing to an imported universe. Each one links to the section that explains it properly.

1. 1

   Mint a key

   In the Meteoric app, go to Settings → API keys and create a key with the Contact list import preset. The token is shown once. See Authentication.

2. 2

   Prove which organization it writes into

   Call GET /whoami. It imports nothing and tells you the organization, user, role, scopes and limits the key carries.

3. 3

   Presign the CSV for GET

   At least 15 minutes, an hour recommended, signed for GET, on the bucket’s own S3 host. Send the string your SDK produced, byte for byte. See Presigning the object.

4. 4

   POST the job

   POST /contact-lists with an idempotency_key and the presigned URL. You get 202 Accepted and a status_url back — nothing has been fetched yet.

5. 5

   Poll to completion

   GET /contact-lists/{id} every 5 seconds until status is succeeded or failed. There is no webhook. Then read the row counts and, if anything failed, the failed-rows CSV.

Every request carries a Personal Access Token as a bearer token:

Authorization: Bearer mtk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Tokens are prefixed mtk_live_. Every key acts on your organization’s live data — verify a new key with /whoami before importing anything.
• The token carries its organization. There is no X-Org-Id header to set — if you send one and it disagrees with the token’s organization the request is refused with org_mismatch. One token writes into exactly one organization; if you push to two organizations you hold two tokens.
• Tokens are shown once, at creation. Store it in your secret manager.
• Every authentication failure returns the same 401 unauthorized with the same message, deliberately — absent, malformed, revoked and expired are indistinguishable from the outside.

Where keys come from

Keys are self-serve. A Meteoric admin enables API access for your organization, and then anyone whose role holds the api_keys permission mints keys at app.getmeteoric.io → Settings → API keys. The full walkthrough — presets, expiry, limits, revocation — is on the API keys section of the overview.

Verify a key without importing anything

curl -sS https://api.getmeteoric.io/api/partner/v1/whoami \
  -H "Authorization: Bearer $METEORIC_TOKEN"

Five operations, all under /api/partner/v1.

Exceeding a limit returns 429 with error code rate_limited and a Retry-After header. Separately, an organization runs at most 3 imports at a time; further imports are accepted and queued, first-in first-out, up to 10 waiting. Beyond that the request is refused with 409 import_queue_full and a Retry-After header. We fetch your file immediately either way — only the import waits.

update_if_newer is not supported and is rejected — it is unimplemented in the importer and would silently behave as a no-op.

Any other value is rejected. (In the underlying importer an unrecognized key means “match nothing”, which silently duplicates every contact — hence the hard rejection here.)

outreach_id accepts outreaches in draft, generating, paused and active status — attaching to a live outreach is supported and behaves like any other contact upload (standard dedupe, suppression and compliance checks apply through the shared pipeline). completed and archived outreaches are refused with outreach_not_accepting_contacts.

An outreach that does not exist and an outreach belonging to a different organization return the same 404 outreach_not_found.

• field_mappings / auto_mapped — the mappings actually used. auto_mapped is true when we resolved headers ourselves.
• source — host and object key only. We never echo your presigned URL or any part of its query string. source.encoding is the encoding we detected (utf-8, utf-8-sig for a BOM’d export, windows-1252, …).
• failed_rows_csv_url — present when rows failed. It is a freshly minted, 15-minute presigned link generated at the moment you read the status. Do not cache it; re-read the status to get a new one.
• queue_position— the job’s place in your organization’s import queue while it is waiting for a slot (1 = next); null whenever it is not waiting.
• error — null unless status is failed. See Errors.

The failed-rows CSV is your original columns plus a _error_reason column, so you can fix and re-push exactly the rows that bounced:

last,cell,zip,first,vanid,_error_reason
Carter,(404) 555-0134,30303,Ada,10029381,Error: Invalid US phone format: (404) 555-0134

• UTF-8 preferred; Windows-1252 / Latin-1 exports are tolerated. The encoding we detected is reported back in source.encoding.
• First line must be a header row. Comma-delimited.
• Maximum 50 MB, 250,000 rows, 120 columns, 30 new custom fields per import. Call GET /field-schema for the live values.
• Cells are sanitized against spreadsheet formula injection on the way in.

An object keyed by your CSV header, valued by {"field": "<target>"}:

"field_mappings": {"vanid": {"field": "external_id"}, "cell": {"field": "phone_1"}}

Rules:

• Every target must be from the table below, or the special form custom:<name>, or skip.
• If you supply field_mappings at all, at least one column must map to a phone slot — a list with no phone numbers cannot be dialed.
• A non-phone target may be used by only one column (use skip for the others). skip may repeat freely.
• At most 30 distinct custom: targets, and two columns may not target the same custom field — even in different casing.
• {"field": ...} is the only key accepted inside the per-column object.

There is no target for internal-only or superuser-only fields; they are not reachable through this API.

If you omit field_mappings we resolve headers deterministically— an alias table plus your organization’s existing custom fields. No AI guessing runs on this path. Header matching lowercases and replaces spaces with underscores. Columns we cannot resolve fail the job with mapping_unresolvable, naming them.

A VAN export usually needs no mappings at all:

GET /field-schema returns the complete, authoritative alias table as JSON — build against that rather than pasting this one into your code.

Returned by the request itself.

Reported as status: "failed", in error.code.

invalid_source_url and not_a_presigned_url appear in both tables on purpose: we re-validate the URL immediately before fetching it, so a URL that passed at request time can still be rejected at execution time.

idempotency_key is required. The worst failure this API can have is importing the same 500,000-row universe twice into a live dial program, so there is no unkeyed path.

• Keys are scoped to your organization.
• We fingerprint the request body with the URL’s query string removed — so re-signing the same object and retrying is recognised as the same request, not a new one.
• Same key + same body → 200 with "replayed": trueand the original job’s id. Safe to retry after a timeout.
• Same key + different body → 409 idempotency_key_reused.
• Two requests racing with the same key produce one job, not two.
• A replay is still returned when your organization’s import queue is full — you can always recover a job id you already own.

Pick keys that encode the push, e.g. moveon-ga-2026-09-03-01. A weekly re-push of the same filename with new content is a new key.

Presign for at least 15 minutes (we recommend 1 hour) and POST the job right away. All three samples below do the same three things: presign for an hour, create the import, poll until the job is terminal.

# 1) Presign the CSV (GET-signed, 1 hour)
URL=$(aws s3 presign s3://moveon-lists/universes/ga-2026-09.csv \
        --expires-in 3600 \
        --region us-east-1)

# 2) Create the import
curl -sS -X POST https://api.getmeteoric.io/api/partner/v1/contact-lists \
  -H "Authorization: Bearer $METEORIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg url "$URL" '{
        idempotency_key: "moveon-ga-2026-09-03-01",
        source: {type: "s3_presigned_url", url: $url},
        list_name: "GA Universe 2026-09",
        outreach_id: 4821,
        matching_key: "external_id",
        merge_strategy: "add_new_only"
      }')"

# 3) Poll to completion
JOB=91744
while :; do
  BODY=$(curl -sS "https://api.getmeteoric.io/api/partner/v1/contact-lists/$JOB" \
          -H "Authorization: Bearer $METEORIC_TOKEN")
  echo "$BODY" | jq -r '.status, .rows'
  case "$(echo "$BODY" | jq -r .status)" in
    succeeded|failed) break ;;
  esac
  sleep 5
done

import time

import boto3, requests

url = boto3.client("s3", region_name="us-east-1").generate_presigned_url(
    "get_object",
    Params={"Bucket": "moveon-lists", "Key": "universes/ga-2026-09.csv"},
    ExpiresIn=3600,
)

resp = requests.post(
    "https://api.getmeteoric.io/api/partner/v1/contact-lists",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "idempotency_key": "moveon-ga-2026-09-03-01",
        "source": {"type": "s3_presigned_url", "url": url},   # verbatim
        "list_name": "GA Universe 2026-09",
        "outreach_id": 4821,
    },
    timeout=30,
)
resp.raise_for_status()
job_id = resp.json()["id"]

# Poll to completion
while True:
    status = requests.get(
        f"https://api.getmeteoric.io/api/partner/v1/contact-lists/{job_id}",
        headers={"Authorization": f"Bearer {token}"},
        timeout=30,
    ).json()
    print(status["status"], status["rows"])
    if status["status"] in ("succeeded", "failed"):
        break
    time.sleep(status.get("poll_after_seconds", 5))

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const base = "https://api.getmeteoric.io/api/partner/v1";
const token = process.env.METEORIC_TOKEN;

// 1) Presign the CSV (GET-signed, 1 hour)
const url = await getSignedUrl(
  new S3Client({ region: "us-east-1" }),
  new GetObjectCommand({ Bucket: "moveon-lists", Key: "universes/ga-2026-09.csv" }),
  { expiresIn: 3600 },
);

// 2) Create the import
const created = await fetch(base + "/contact-lists", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    idempotency_key: "moveon-ga-2026-09-03-01",
    source: { type: "s3_presigned_url", url },   // verbatim, never re-encoded
    list_name: "GA Universe 2026-09",
    outreach_id: 4821,
    matching_key: "external_id",
    merge_strategy: "add_new_only",
  }),
});
if (!created.ok) throw new Error(created.status + " " + (await created.text()));
const job = await created.json();

// 3) Poll to completion
let status = job;
while (status.status !== "succeeded" && status.status !== "failed") {
  await new Promise((done) => setTimeout(done, (status.poll_after_seconds || 5) * 1000));
  const res = await fetch(base + "/contact-lists/" + job.id, {
    headers: { Authorization: "Bearer " + token },
  });
  status = await res.json();
  console.log(status.status, status.rows);
}

The Node sample needs @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner; fetch is built in from Node 18.

• https only, on the bucket’s own …s3[.<region>].amazonaws.com host.
• Signed for GET.
• No credentials embedded in the URL (no user:pass@).
• Only public AWS S3 endpoints — not our buckets, not third-party S3-compatible hosts.

1. Never append a query parameter to a presigned URL. Not &download=1, not a cache-buster. Any added parameter invalidates the SigV4 signature and S3 answers 403 → source_url_forbidden.
2. Never re-encode the URL. Send the string your SDK/CLI produced, byte-for-byte. Re-quoting %2F, normalizing +, or round-tripping it through a URL builder breaks the signature the same way.
3. Presign for at least 15 minutes, and post the job immediately. A URL that is already expired — or expires within two minutes — is refused synchronously (source_url_expired) so you find out at request time.
4. We only ever issue a GET. We do not HEAD your object to check reachability: a HEAD against a GET-signed URL always 403s, so the check would be pure noise. Sign for GET, and expect exactly one fetch — the file is copied on first read, so retries never touch your URL again.
5. One 50 MB cap, and polling is the completion signal. 50 MB is the ceiling everywhere (API and UI). There is no webhook and no callback: poll status_url every 5 seconds until succeeded or failed.

The two discovery endpoints. Neither one writes anything, and both are the right place to start an integration.

Email support@getmeteoric.io with the request_id (synchronous failures) or the job id (asynchronous failures) for anything this document does not cover.