--- title: "API reference: Account" url: "https://coldmeetings.com/docs/api/account.md" canonical_url: "https://coldmeetings.com/docs/api/account" last_updated: "2026-10-28" type: "reference" summary: "Read your account, plan and prospect credits, export your data, start a checkout, and use the public health and plan list endpoints of the ColdMeetings API." related: ["https://coldmeetings.com/docs/api.md", "https://coldmeetings.com/docs/errors.md"] --- # API reference: Account > **For AI agents:** the complete index of ColdMeetings pages is [llms.txt](https://coldmeetings.com/llms.txt). Every page is also served as markdown at its URL plus .md. Read your account, plan and prospect credits, export your data, start a checkout, and use the public health and plan list endpoints of the ColdMeetings API. Your account, its plan and its prospect credits, a full export of your data, plus the two public endpoints that need no key. Base URL: `YOUR_API_BASE_URL`. Every request and response is JSON. Errors use [one envelope](https://coldmeetings.com/docs/errors.md). | Operation | What it does | | --- | --- | | [`GET /health`](#get-health) | Liveness check. | | [`GET /plans`](#get-plans) | The three plans. Prices are set and nothing is charged live. | | [`GET /v1/account`](#get-v1account) | Account, plan, credit balance, usage and keys. | | [`GET /v1/account/export`](#get-v1accountexport) | Every row the account has, as one JSON document: profile, keys (by prefix), credit ledger, invoices, domains, mailboxes, campaigns, prospects, replies and the do-not-contact list. Secrets are left out. Three requests per account every ten minutes. | | [`POST /v1/billing/checkout`](#post-v1billingcheckout) | Start a hosted checkout session. The plan starts when the payment is confirmed. | ## GET /health Liveness check. Authentication: none. This endpoint is public and not rate limited. ### Response Status 200 OK. ```json { "status": "ok" } ``` ### Example request ```bash curl YOUR_API_BASE_URL/health \ -H "Authorization: Bearer $COLDMEETINGS_API_KEY" ``` ## GET /plans The three plans. Prices are set and nothing is charged live. Authentication: none. This endpoint is public and not rate limited. ### Response Status 200 OK. ```json { "plans": [ { "id": "professional", "name": "Professional", "clientPaysSuppliers": true, "includes": [ "Sending-domain setup", "Mailbox setup", "SPF, DKIM and DMARC records", "Outreach course", "Monthly sequences", "10,000 verified prospects a month", "Monthly optimization call", "Priority support" ], "billing": "monthly", "priceUsd": 495, "checkout": "self_serve", "monthlyProspectCredits": 10000, "maxDomains": 12, "maxMailboxes": 30, "maxActiveCampaigns": 5 } ] } ``` - `plans` holds one object per plan: `professional` and `enterprise`. The example shows one. `checkout` is `self_serve` for Professional and `book_call` for Enterprise, whose `priceUsd` is its starting price. - `refund_terms` is the refund sentence: You can ask for a refund of your first paid month within 7 days of paying. - Prices are in US dollars. ### Example request ```bash curl YOUR_API_BASE_URL/plans \ -H "Authorization: Bearer $COLDMEETINGS_API_KEY" ``` ## GET /v1/account Account, plan, credit balance, usage and keys. Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md). ### Response Status 200 OK. ```json { "account": { "id": "acct_9fKd2LmQx7RtVw3ZbN1pEs", "name": "Acme Software", "created_at": "2026-10-17T12:00:00.000Z" }, "plan": { "id": "professional", "name": "Professional", "clientPaysSuppliers": true, "includes": [ "Sending-domain setup", "Mailbox setup", "SPF, DKIM and DMARC records", "Outreach course", "Monthly sequences", "10,000 verified prospects a month", "Monthly optimization call", "Priority support" ], "billing": "monthly", "priceUsd": 495, "checkout": "self_serve", "monthlyProspectCredits": 10000, "maxDomains": 12, "maxMailboxes": 30, "maxActiveCampaigns": 5 }, "prospect_credits": { "available": 9850, "reserved": 0 }, "usage": { "domains": 3, "mailboxes": 9, "active_campaigns": 1 }, "keys": [ { "id": "T4vXq9LmB2zK", "prefix": "cm_live_", "name": "first key", "revoked": false } ] } ``` - `plan` is the account's current plan. An account with no paid plan yet has `plan: null`. - `prospect_credits.reserved` is the number of credits held by an import that is still running. - `keys` lists key ids, prefixes and names. A key value is never returned after creation. ### Errors - [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown. - [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`. ### Example request ```bash curl YOUR_API_BASE_URL/v1/account \ -H "Authorization: Bearer $COLDMEETINGS_API_KEY" ``` ## GET /v1/account/export Every row the account has, as one JSON document: profile, keys (by prefix), credit ledger, invoices, domains, mailboxes, campaigns, prospects, replies and the do-not-contact list. Secrets are left out. Three requests per account every ten minutes. Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md). ### Response Status 200 OK. ```json { "brand": "coldmeetings", "account_id": "acct_9fKd2LmQx7RtVw3ZbN1pEs", "exported_at": "2026-10-17T12:00:00.000Z", "profile": { "id": "acct_9fKd2LmQx7RtVw3ZbN1pEs", "name": "Acme Software", "created_at": "2026-10-17T12:00:00.000Z" }, "tables": { "campaigns": [ { "id": "cmp_2LmQx7RtVw3ZbN1pEs9fKd", "name": "Q4 outreach", "status": "paused" } ] }, "redacted_columns": { "api_keys": [ "key_hash" ] }, "truncated": {} } ``` - `tables` holds every table that has rows for the account, each as a list of rows. Keys are listed by prefix only; secrets are left out and named in `redacted_columns`. - `truncated` names any table cut at the row cap, with the number of rows the account has there. - Three requests per account every ten minutes. ### Errors - [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown. - [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`. ### Example request ```bash curl YOUR_API_BASE_URL/v1/account/export \ -H "Authorization: Bearer $COLDMEETINGS_API_KEY" ``` ## POST /v1/billing/checkout Start a hosted checkout session. The plan starts when the payment is confirmed. The plan starts when the payment is confirmed, normally within seconds, and not before. Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md). > This operation answers 503 `provider_unavailable` when its outside service cannot be reached. The payment service could not be reached, or there is no site address to return to. Nothing is simulated and nothing is charged. ### Request body Send a JSON object. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `plan` | string | Yes | Professional starts a Checkout. Enterprise is bought on a call and answers 400 with the booking page. One of `professional`, `enterprise`. | | `customer_email` | string | Yes | The email address of the person who pays. It is trimmed and lowercased. | | `attempt_id` | string | No | A random id your client makes once per buy and sends again on every retry of it. A repeat with the same id returns the same Checkout instead of making another. Pattern `^[A-Za-z0-9_-]{16,64}$`. | | `success_url` | string | No | Where checkout returns after payment. Must be a page on the ColdMeetings site; defaults to the pricing page. Format: uri. | | `cancel_url` | string | No | Where checkout returns if the person backs out. Must be a page on the ColdMeetings site; defaults to the pricing page. Format: uri. | Example body: ```json { "plan": "professional", "customer_email": "maya@acme.example" } ``` ### Response Status 200 OK. ```json { "session_id": "cs_test_a1B2c3D4e5F6g7H8", "url": "https://checkout.example/session/cs_test_a1B2c3D4e5F6g7H8" } ``` - Send the person to `url` to finish checkout. Only Professional has a checkout, and it has no trial. - `success_url` and `cancel_url` are optional. When given, they must be pages on the ColdMeetings site; both default to the pricing page. ### Errors - [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown. - [`invalid_input`](https://coldmeetings.com/docs/errors.md#invalid_input), HTTP 400: A return address is not a page on the ColdMeetings site, or the plan is Enterprise, which is bought on a call. A body that is empty, is not JSON or fails validation also answers this, and the message names the field. - [`payload_too_large`](https://coldmeetings.com/docs/errors.md#payload_too_large), HTTP 413: The body is over 256 KiB. - [`conflict`](https://coldmeetings.com/docs/errors.md#conflict), HTTP 409: The account already has a subscription. - [`provider_unavailable`](https://coldmeetings.com/docs/errors.md#provider_unavailable), HTTP 503: Payments could not be reached. Retry with backoff. - [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`. ### Example request ```bash curl -X POST YOUR_API_BASE_URL/v1/billing/checkout \ -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"plan":"professional","customer_email":"maya@acme.example"}' ``` ## Related - [API reference](https://coldmeetings.com/docs/api.md) - [Errors](https://coldmeetings.com/docs/errors.md)