Meteoric Partner API
API reference
A small, deliberate HTTP surface for the things partners need to do to a Meteoric organization from their own systems. It is versioned separately from the product, authenticated with a bearer token that carries its own organization, and documented here in full.
What the Partner API is
The Partner API lets a system you run push work into a Meteoric organization without a person in the loop. Today it does one job thoroughly: bulk-loading a contact list from a CSV you host in your own S3 bucket. You presign the object, we fetch it once, and we import it through exactly the same pipeline the Meteoric UI uses — the same dedupe, the same DSAR and opt-out suppression, the same compliance checks, the same optional district enrichment.
Everything is asynchronous and idempotent by construction. A create call returns a job id and a status URL; you poll until the job is terminal. Every request carries an idempotency key, because the worst thing this API could do is import the same half-million-row universe twice into a live dial program. There is no unkeyed path, and there is no webhook — polling is the completion signal.
Base URL
Every request goes to https://api.getmeteoric.io/api/partner/v1 over HTTPS, with Content-Type: application/json and a bearer token prefixed mtk_live_. There is one environment: the keys your organization mints act on your live data, so verify a new key with /whoami before importing anything.
API keys
Keys are self-serve. A Meteoric admin enables API access for your organization once; after that, minting and revoking keys is something your own team does, with no ticket and no waiting on us.
Who can mint a key
Any user whose role holds the api_keys permission. Organization owners and admins have it automatically. For anyone else, an owner or admin adds it to their custom role under Settings → Roles.
Where
app.getmeteoric.io → Settings → API keys → Create key. Revocation lives on the same page and takes effect immediately.
What you choose
| Setting | Detail |
|---|---|
| Scope preset | Contact list import is the default preset and grants {contacts: [import, view], upload_status: [view]}. Effective permission is the intersection of the key’s scopes and the user’s role — a scope on the key is not by itself a grant. |
| Expiry | Defaults to 90 days; 365 days is the maximum. An expired key fails as a plain 401, so rotate before the date, not after. |
| Active keys | Up to 10 active keys per user. Enough to run a rotation without a gap; small enough that abandoned keys get noticed. |
| The token itself | Shown once, at creation. Copy it into your secret manager then. There is no way to read it again — if it is lost, revoke it and mint a new one. |
First call with a new key
Prove which organization the key writes into before you import anything. /whoami writes nothing and returns the organization, user, role, scopes and limits the token carries.
curl -sS https://api.getmeteoric.io/api/partner/v1/whoami \
-H "Authorization: Bearer $METEORIC_TOKEN"Endpoints
Five operations across four paths, all under /api/partner/v1. Exceeding a rate limit returns 429 rate_limited with 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.
| Method | Path | Purpose | Rate limit |
|---|---|---|---|
| POST | /contact-lists | Create a bulk-load job from a presigned S3 CSV URL | 10 / minute, 100 / day |
| GET | /contact-lists/{id} | Status of one job | 120 / minute |
| GET | /contact-lists | Recent jobs, paged (reconciliation) | 30 / minute |
| GET | /field-schema | Machine-readable field vocabulary | 60 / minute |
| GET | /whoami | Which organization/user this key acts as | 60 / minute |
OpenAPI specification
The machine-readable contract — OpenAPI 3.1, generated from the running service, so it cannot drift from what the API actually accepts. Point your client generator at it rather than hand-writing models.