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, plus van_ids: true and id_state or id_state_column if the file has VAN ids (see The VAN id state). 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.

The key’s scopes and its user’s role must both allow the request (see GET /whoami). Since 2026-10-06 the two list reads refuse a key with no contacts scope (before, any key of the organization could read them). A key that imports lists can always read them.

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.

Since 2026-10-05. A VAN id names a voter only within a state. When your file has a VAN id column — any column mapped to external_id, whether you sent field_mappings or we resolved the headers (Automatic header resolution) — send "van_ids": true to say it holds VAN ids (since 2026-10-07), and tell us which state the ids belong to, with exactly one of:

• Say they are VAN ids (van_ids: true, since 2026-10-07). A column on external_id is always read as VAN ids, including one we map for you from a header named just id (unless it holds row numbers: we skip those, see Automatic header resolution). Without van_ids: true the request is refused with 400 van_ids_unconfirmed, before the state is asked; when we map the header ourselves, the job fails with van_ids_unconfirmed once we have read it, before any row is imported. Both name the column. If it is not VAN ids (your own person id), keep it in a custom: field and, if it is your stable id for each person, send that field as matching_key (Matching on your own id). van_ids: true on a file with no such column is ignored.
• Exactly one. Neither (with a VAN id column) is id_state_required; both is id_state_ambiguous. A file with no VAN id column needs neither, and either field is ignored for it.
• Organizations whose VAN ids are unique nationwide (an organization setting, off by default, set in Meteoric under Settings → VAN IDs) need neither, nor van_ids: their ids match on themselves alone. A request that sends id_state or id_state_column anyway is accepted, the value is ignored (not checked), and the 202 says so in warnings with the code id_state_ignored.
• Your address is not used for it. state, zip_code and congressional_district describe the address, which is often a mailing address in another state. If your statecolumn really is each voter’s registration state, name it in id_state_column; we never assume it.
• A blank or unrecognised cell in id_state_column (an empty cell, Ontario, a ZIP): that row is not imported — not matched by its id, not created. It counts in rows.failed and is in the failed-rows file with the reason (_category no_id_state). Rows without a VAN id are imported as usual.
• A congressional district in another state.A district is voting geography: when a row’s congressional_district cell names its own state (GA-05, ga 5, Georgia 5 — not a bare 005) and that state is not the row’s VAN id state, the row is not imported either (rows.failed, _category id_state_conflict). Address state and ZIP are not compared.
• If every row with a VAN id fails one of these two ways, the job ends failed: id_state_missing when any had a blank or unrecognised cell, else id_state_conflict.
• An id someone else already holds in that state. With matching_key: "email" no id lookup runs, so before a row writes its VAN id and state onto a contact we check that no other contact holds that pair. If one does, the row is still imported, withoutthe VAN id, and counted in the job’s notification.
• What it does. A row matches an existing contact whose VAN id was stored in the same state, never one stored in another state. Each contact the import creates or matches by its VAN id keeps that state, so the next push finds them again.
• id_state and enrichment.district_state must agree. Both describe the same list: the state of its VAN ids, and the state of its bare district numbers (003). When they differ the request is refused with id_state_district_mismatch unless it carries "confirm_id_state_mismatch": true. Bare district numbers name no state, so this is the only check such a file gets before its rows are matched.
• Neither field is checked against the column’s contents at request time; a column name is checked against the file’s header once we fetch it (invalid_id_state_column).

Known limits

• The district check reads whatever is in the column mapped to congressional_district: a state-senate or precinct code that looks like GA-05 there is read as a congressional district. The worst it does is refuse that row (a visible failed row, id_state_conflict); it never merges two people.
• A job whose every row with a VAN id failed still imports its rows that have no VAN id; rows.created says how many.
• With merge_strategy: "skip_existing"a matched contact is not changed, and its stored VAN id state is not set; but a contact matched by name and phone that had no VAN id at all is still given the row’s VAN id (as before 2026-10-05), without a state.

One state for the whole list

{
  "idempotency_key": "nc-universe-2026-10-05-01",
  "source": {"type": "s3_presigned_url", "url": "https://your-bucket.s3.us-east-1.amazonaws.com/nc.csv?<presigned query string>"},
  "field_mappings": {
    "vanid": {"field": "external_id"},
    "first": {"field": "first_name"},
    "last":  {"field": "last_name"},
    "cell":  {"field": "phone_1"},
    "zip":   {"field": "zip_code"}
  },
  "matching_key": "external_id",
  "van_ids": true,
  "id_state": "NC"
}

A list that mixes states, with the state in a voter_state column

{
  "idempotency_key": "multi-state-2026-10-05-01",
  "source": {"type": "s3_presigned_url", "url": "https://your-bucket.s3.us-east-1.amazonaws.com/all.csv?<presigned query string>"},
  "field_mappings": {
    "vanid":       {"field": "external_id"},
    "cell":        {"field": "phone_1"},
    "zip":         {"field": "zip_code"},
    "voter_state": {"field": "skip"}
  },
  "matching_key": "external_id",
  "van_ids": true,
  "id_state_column": "voter_state"
}

(voter_state is mapped to skip here because it is read only for the id; map it to state instead if it is also the address state you want stored. Without a state, zip_code, congressional_district or manual_timezone column, the 202 carries the no_location_columns warning: Where your contacts are.)

The refusal when the file maps a column to external_id and the request leaves out van_ids: true

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "van_ids_unconfirmed",
    "message": "Column 'vanid' is mapped to external_id, the VAN ID field, but the request did not confirm it holds VAN IDs, so nothing was imported. If it does, send van_ids: true together with id_state or id_state_column. If it does not, map it to a custom: field (your own id can then be the matching_key) or to skip.",
    "details": {"column": "vanid"},
    "request_id": "0f2c8e14-77a1-4a55-9a9b-2f0f18cbf1f0"
  }
}

The refusal when van_ids: true is sent but neither state field is

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "id_state_required",
    "message": "This file has VAN IDs (column 'vanid') but no VAN ID state. VAN IDs are only unique within a state, so choose the column of the file that holds each ID's state, or one state for the whole list. Send id_state (one state for the whole list) or id_state_column (the header of the column holding each row's state).",
    "details": null,
    "request_id": "0f2c8e14-77a1-4a55-9a9b-2f0f18cbf1f0"
  }
}

None of these refusals changes on retry: fix the request and send it with a new idempotency_key.

Since 2026-10-07. We call each contact inside legal calling hours on their own clock, and we place them by the first of these they have:

1. a timezone (manual_timezone, or one we derived earlier) that names a region, like America/Chicago; EST, CST or UTC place no one;
2. a state;
3. a zip_code that places them;
4. a congressional_district that names a state (NV-02, or a bare 002 that enrichment.district_stateor your outreach’s district gives a state).

A contact with none of these is imported and called like anyone else, but only between noon and 9 PM Eastern(9 AM to 6 PM Pacific), the hours that are legal everywhere in the lower 48 states. If such a contact’s phone number has a Hawaii, Alaska, Puerto Rico or other territory area code, that place’s legal hours must hold too, which narrows the window further. The VAN id state (The VAN id state) is not used for this: it decides who a VAN id matches, not when they are called.

We tell you, and never refuse the request for it:

contacts_unlocated counts people, not rows: a person listed twice in the file counts once, and a contact the organization already had is judged by everything stored for them, not only by this file. It is counted after district enrichment (enrichment.enabled), which can place people by their street address. A warning never changes status or rows.

To call those contacts on their local hours, send their state, ZIP code or congressional district in another import, with any merge_strategy except skip_existing (which changes nothing on a contact we already have).

"warnings": [
  {
    "code": "contacts_unlocated",
    "message": "1,204 of the 58,124 contacts in this list have no state, ZIP code, congressional district or timezone that places them. They were imported, and will be called only between noon and 9 PM Eastern, the hours that are legal everywhere in the lower 48 states, never on their own local hours. To change that, send their state, ZIP code or congressional district in another import (any merge_strategy except skip_existing).",
    "details": {"unlocated_contacts": 1204, "list_contacts": 58124}
  }
]

Branch on code and read the numbers from details; the message wording may change.

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.)

Since 2026-10-08. If the id you key your sync on is not a VAN id, keep it in a custom field and name that field as the matching key:

{
  "idempotency_key": "members-2026-10-08-01",
  "source": {"type": "s3_presigned_url", "url": "https://your-bucket.s3.us-east-1.amazonaws.com/members.csv?<presigned query string>"},
  "field_mappings": {
    "voterbase_id": {"field": "custom:voterbase_id"},
    "first":        {"field": "first_name"},
    "last":         {"field": "last_name"},
    "cell":         {"field": "phone_1"},
    "zip":          {"field": "zip_code"}
  },
  "matching_key": "custom:voterbase_id",
  "merge_strategy": "update_all"
}

No van_ids, no id_state: this id is not a VAN id, and we never treat it as one. You choose the field; we never pick a matching key for you.

What makes a custom field usable as the key.These are the rules of Meteoric’s own upload screen, checked the same way here:

• Exactly one column fills it. With field_mappings, one column must be mapped to that custom: field. None is 400 custom_matching_key_unusable (the message names the field). Two columns on one field are refused too: two spellings of its name as 400 invalid_field_mappings (field_mappings), its name from one column and its key from another as 400 custom_matching_key_unusable. The name follows the rules of any custom: target (Field targets): case, spaces, hyphens and underscores are interchangeable, and a field’s key from GET /field-schema works too.
• Its values tell people apart. At least 90% of the values in the file must be different (read on its first 10,000 rows). A file that lists a few people twice passes; a county, a party or a household id does not: matched on, everyone sharing a value would become one person.
• At least half of the rows have it. A column with no value on any row cannot be the key, and neither can one with a value on fewer than halfof the file’s rows (counted on the whole file; a row with nothing in any cell is not counted): that is a wrong column or a broken export far more often than a list, and nearly every row would be matched by name and phone number without a word. The message gives the count. A list where some people have no id yet still imports (see below).
• Never row numbers. A column that counts 1, 2, 3… is not an id, and a custom field named like a row number (row_number, row, line, index, #…) cannot be the key (row_number_matching_key).
• The field’s name is checked at the request; the file when we read it. A file that breaks the 90% rule or the half-of-the-rows rule, or holds row numbers, fails as a job with custom_matching_key_unusable or row_number_matching_key, before any row is imported. So does a file that has no column with the exact header your field_mappings put on the key.
• Send field_mappings with a custom key. Without them we read a header as a custom field only when it is the name of a field your organization already has (Automatic header resolution). A header like voter_id or id is read as external_id instead, and the job fails with custom_matching_key_unusable; a header we cannot read at all fails it with mapping_unresolvable.

What it does.

• A row matches the contact in your organization whose value for that field is the row’s (compared exactly, after trimming spaces), in any state. The usual merge_strategy then applies.
• A row whose value nobody holds is matched by name and phone number, the rule every import ends with: a contact you loaded earlier without the id is found that way and gains the id, so your first push on this key fills it in. No match either: a new contact is created, holding the id.
• That name-and-phone match is refused when the contact it finds already holds another value of the field: by your own key they are two people. The row is not imported; it is in the failed-rows file with both values (_category duplicate) and counts in rows.failed.
• The same value on several rows of the file is one person: the rows are merged onto one contact.
• If several contacts in your organization already hold a row’s value, the row goes to the one with the row’s phone number, else the oldest record.
• A row with no value in that column is matched by name and phone number (at least half of the file’s rows must have one, or the job fails).
• A file with a custom key and a column on external_id still follows The VAN id state for that column (van_ids: true, and id_state or id_state_column).
• If matching on a custom field is switched off on our side, the request is refused with 400 custom_matching_key_disabled. A job accepted before that fails with the same code, when we read its file or when its import starts, rather than being imported without its key.

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 or were suppressed. 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.
• warnings — the 202’s warnings, then any recorded since: no_location_columns when we resolved your headers ourselves, and contacts_unlocated once status is succeeded (Where your contacts are), and row_number_columns_skipped when we skipped columns of row numbers (Automatic header resolution), and blank_rows_skipped when rows of the file had no value in any column (details.blank_rows; they are skipped, counted in no rows number and not in the failed-rows file). Never a failure; empty when there is nothing to say.

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.

state, zip_code, congressional_district and manual_timezone decide the hours each contact is called in; a file with none of them gets a warning (Where your contacts are).

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 column of row numbers is skipped instead, see below).

A VAN export usually needs no mappings at all — but it does need two things said: when we resolve a column to external_id, send "van_ids": true and id_state or id_state_column with the request (The VAN id state), or the job fails once we have read the header (van_ids_unconfirmed, then id_state_required).

A header named just id resolves to external_id (unless it holds row numbers, below). If your id column is your own person id rather than VAN ids, send field_mappings that map it to a custom: field, and name that field as matching_key if it is the id you sync on (Matching on your own id); without van_ids: true the job fails with van_ids_unconfirmed, naming the column, and nothing is imported.

With matching_key: "custom:<name>", send field_mappings. Without them one header must be read as that custom field, which happens only when the header is the name of a field your organization already has: not its key, and not a header from the table below (voter_id and id are read as external_id). A header we cannot read at all fails the job with mapping_unresolvable; a file whose headers all resolve, but none to that field, fails with custom_matching_key_unusable.

A column of row numbers is skipped (since 2026-10-07), whatever its header, idincluded: every row with any value has a whole number there, the first is 0 or 1, and each row’s is the one before plus 1. Nothing else is read that way. The job’s status then warns row_number_columns_skipped, naming the columns in details.columns. If you send field_mappings yourself, a row-number column on external_id or on your matching_key fails the job (row_number_matching_key); keep it, if you want it, as custom:row_number.

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.
• A replay is returned before any check added since the job was accepted: a retry of a request we accepted before 2026-10-05 (a VAN id and no id_state/id_state_column) gets its original job back, not id_state_required. A new key with that body is refused. The same holds for a request accepted before van_ids (2026-10-07) that did not send it, and for a request on a custom: matching key: its retry returns its job even if a check on that key would refuse a new request now.
• matching_key is part of the fingerprint, as it always was: the same key with another matching_key is 409 idempotency_key_reused.
• New key + a file identical to one your organization already has (since 2026-10-08) → accepted, then the job fails once we have fetched the file, naming the earlier job (Asynchronous errors): same_file_already_imported when that job imported it, same_file_importingwhile it is still waiting or importing. The fingerprint is of the request; this check is of the file’s bytes. A replay of an accepted request is never refused by it.

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. A re-push whose content has not changed at all is refused as same_file_already_imported, and so is the same file sent with another outreach_id, field_mappings, matching_key or merge_strategy: the check looks only at the file.

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",
        van_ids: true,
        id_state: "GA"
      }')"

# 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,
        "van_ids": True,      # the vanid column holds VAN ids...
        "id_state": "GA",     # ...and they are Georgia ids
    },
    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",
    van_ids: true,                               // the vanid column holds VAN ids...
    id_state: "GA",                              // ...and they are Georgia ids
  }),
});
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.