# SparkLoop API v3 > SparkLoop's v3 REST API for newsletter growth and monetization. Base URL: https://api.sparkloop.app/v3. Authenticate by sending your API key in the `x-api-key` header. The previous v2 API remains available and unchanged. Every resource is scoped to a publication and is richly queryable, so most questions can be answered in one or two calls: - Nesting: most publication-scoped resources live under `/v3/publications/:publication_uuid/...` and are grouped by product side into `earn/` (monetization), `grow/` (audience growth), and `tools/` (configuration), mirroring the dashboard. `account`, `publications`, `payouts`, and `webhooks` are top-level. - Expand: opt into related data with `?expand=a,b`. A referenced object is returned as its UUID by default, or as the full object when expanded. - Stats: `?expand=stats` adds date-ranged performance where a resource has it; set the window with `from` and `to` (default: the last 30 days). Values only. - Pagination: `page` and `per_page` (default 50, max 200); list responses include a `meta` block with `page`, `per_page`, `total_pages`, and a total count. - Errors: `{ "error": "" }` with conventional HTTP status codes (401 unauthorized, 404 not found, 422 unprocessable). - Identifiers are UUIDs; monetary amounts are in dollars. ## Account & Publications - [GET /v3/account](https://api.sparkloop.app/v3/account): Retrieve the account (team) that owns your API key — name, ESP, owner. `expand=team_members`. - [GET /v3/publications](https://api.sparkloop.app/v3/publications): List the newsletters on your team. - [GET /v3/publications/:uuid](https://api.sparkloop.app/v3/publications/:uuid): Retrieve a single publication. ## Earn - [GET /v3/publications/:publication_uuid/earn/recommendations](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/recommendations): List this publication's paid recommendations — newsletters it recommends through a partner program to earn commission (`type: paid`, renamed from v2 `partner_campaigns`). `expand=recommended_publication,stats` (referrals + earnings). - [GET /v3/publications/:publication_uuid/earn/recommendations/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/recommendations/:uuid): Retrieve a single paid recommendation. `expand=recommended_publication,stats`. - [GET /v3/publications/:publication_uuid/earn/directory/recommendations](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/directory/recommendations): Browse the Partner Network catalog of partner programs this publication can recommend to earn commission. `order_by=created_at|commission|max_payout`. - [GET /v3/publications/:publication_uuid/earn/directory/recommendations/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/directory/recommendations/:uuid): Retrieve a single directory program. - [POST /v3/publications/:publication_uuid/earn/directory/recommendations/:recommendation_uuid/recommend](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/directory/recommendations/:recommendation_uuid/recommend): Start recommending a program — creates a paid recommendation. - [GET /v3/publications/:publication_uuid/earn/offers](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/offers): List the brand offers this publication recommends to earn from. `expand=stats` (impressions, claims, conversions, earnings). - [GET /v3/publications/:publication_uuid/earn/offers/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/offers/:uuid): Retrieve a single offer this publication recommends. `expand=stats`. - [GET /v3/publications/:publication_uuid/earn/offers/:offer_uuid/conversions](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/offers/:offer_uuid/conversions): List the conversions recorded for an offer this publication recommends. - [GET /v3/publications/:publication_uuid/earn/directory/offers](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/directory/offers): Browse the Partner Network catalog of brand offers this publication can recommend to earn. Filter with `categories`, `conversion_types`, `commission_type`, `countries`, `q`, `sort`. - [GET /v3/publications/:publication_uuid/earn/directory/offers/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/directory/offers/:uuid): Retrieve a single directory offer. - [POST /v3/publications/:publication_uuid/earn/directory/offers/:offer_uuid/recommend](https://api.sparkloop.app/v3/publications/:publication_uuid/earn/directory/offers/:offer_uuid/recommend): Start recommending an offer — creates an offer recommendation. ## Grow - [GET /v3/publications/:publication_uuid/grow/free_recommendations](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations): List free organic recommendations this publication has added (`type: free`). `expand=recommended_publication,stats` (referrals only — free recommendations don't earn). - [GET /v3/publications/:publication_uuid/grow/free_recommendations/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations/:uuid): Retrieve a single free recommendation. `expand=recommended_publication,stats`. - [GET /v3/publications/:publication_uuid/grow/directory/free_recommendations](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/directory/free_recommendations): Browse the Partner Network catalog of newsletters you can recommend for free. Filter with `q`, `categories`, `language`. - [GET /v3/publications/:publication_uuid/grow/directory/free_recommendations/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/directory/free_recommendations/:uuid): Retrieve a single directory newsletter. - [POST /v3/publications/:publication_uuid/grow/directory/free_recommendations/:free_recommendation_uuid/recommend](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/directory/free_recommendations/:free_recommendation_uuid/recommend): Add a free recommendation for this newsletter. - [POST /v3/publications/:publication_uuid/grow/directory/free_recommendations/:free_recommendation_uuid/partnership_request](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/directory/free_recommendations/:free_recommendation_uuid/partnership_request): Request a mutual partnership with this newsletter. - [GET /v3/publications/:publication_uuid/grow/partner_program](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/partner_program): Retrieve this publication's own partner program that pays others to refer subscribers. `expand=stats` (referrals + spend). - [GET /v3/publications/:publication_uuid/grow/partner_program/partners](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/partner_program/partners): List the program's active partners. `expand=recommending_publication,stats`; `order_by=newest|confirmed_referrals|earnings`. - [GET /v3/publications/:publication_uuid/grow/partner_program/partners/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/partner_program/partners/:uuid): Retrieve a single partner. `expand=recommending_publication,stats`. - [GET /v3/publications/:publication_uuid/grow/partner_program/referrals](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/partner_program/referrals): List subscribers the program received from its partners. `expand=recommending_partner`. - [GET /v3/publications/:publication_uuid/grow/partner_program/referrals/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/partner_program/referrals/:uuid): Retrieve a single referral. `expand=recommending_partner`. - [GET /v3/publications/:publication_uuid/grow/partner_program/partner_requests](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/partner_program/partner_requests): List newsletters awaiting approval to join the program. `expand=recommending_publication,partner_track_record`. - [POST /v3/publications/:publication_uuid/grow/partner_program/partner_requests/:partner_request_uuid/approval](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/partner_program/partner_requests/:partner_request_uuid/approval): Approve a request, turning it into a partner. - [GET /v3/publications/:publication_uuid/grow/offers](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/offers): List offers this publication created as a brand and funds for others to recommend (read-only). `expand=stats` (impressions, claims, conversions). - [GET /v3/publications/:publication_uuid/grow/offers/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/grow/offers/:uuid): Retrieve a single created offer. `expand=stats`. ## Tools - [GET /v3/publications/:publication_uuid/tools/signup_flow](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow): Retrieve the publication's on-site subscriber signup flow (renamed from v2 `upscribe`). `expand=stats` (visits, earnings, plus recommendation/survey/offer breakdowns). - [GET /v3/publications/:publication_uuid/tools/in_email_campaigns](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/in_email_campaigns): List in-email tracking links, each targeting a recommendation or an offer. `expand=stats` (clicks, referrals/conversions, earnings). - [GET /v3/publications/:publication_uuid/tools/in_email_campaigns/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/in_email_campaigns/:uuid): Retrieve a single in-email campaign. `expand=target,stats`. - [GET /v3/publications/:publication_uuid/tools/surveys](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys): List the welcome surveys shown in the publication's signup flow. `expand=stats` (completion funnel). - [GET /v3/publications/:publication_uuid/tools/surveys/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:uuid): Retrieve a single survey. `expand=stats`. - [GET /v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions): List a survey's questions. - [GET /v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions/:uuid): Retrieve a single question. `expand=stats` (answer distribution). - [GET /v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions/:question_uuid/answers](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/questions/:question_uuid/answers): List the answers to a question. - [GET /v3/publications/:publication_uuid/tools/surveys/:survey_uuid/submissions](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/submissions): List a survey's submissions. - [GET /v3/publications/:publication_uuid/tools/surveys/:survey_uuid/submissions/:uuid](https://api.sparkloop.app/v3/publications/:publication_uuid/tools/surveys/:survey_uuid/submissions/:uuid): Retrieve a single submission. ## Analytics & Payouts - [GET /v3/publications/:publication_uuid/earnings](https://api.sparkloop.app/v3/publications/:publication_uuid/earnings): Aggregated earnings across a publication's recommendations and offers. Slice with `group_by=utm_campaign|recommendation|offer` (total only), `granularity=total|daily|weekly`, `channel`, `from`, `to`. - [GET /v3/payouts](https://api.sparkloop.app/v3/payouts): List partner-network payments SparkLoop has made or is preparing for your team. `expand=details,unpaid_details`. - [GET /v3/payouts/:uuid](https://api.sparkloop.app/v3/payouts/:uuid): Retrieve a single payout. `expand=details,unpaid_details` (line-item breakdowns). ## Webhooks - [GET /v3/webhooks](https://api.sparkloop.app/v3/webhooks): List your team's webhooks. - [GET /v3/webhooks/:uuid](https://api.sparkloop.app/v3/webhooks/:uuid): Retrieve a single webhook. - [POST /v3/webhooks](https://api.sparkloop.app/v3/webhooks): Create a webhook (body: `url`, `events[]`). - [PATCH /v3/webhooks/:uuid](https://api.sparkloop.app/v3/webhooks/:uuid): Update a webhook. - [DELETE /v3/webhooks/:uuid](https://api.sparkloop.app/v3/webhooks/:uuid): Delete a webhook. ## Optional - [SparkLoop API v2](https://api.sparkloop.app/v2): The previous API version — still supported and unchanged.