# Submitator > Submitator submits your startup to the directories you pick, for a one-time payment from $29. You add your product once, choose from a catalogue of 170+ directories and follow every submission in a dashboard. Agencies resell it under their own brand. Plans, each a one-time payment: - Starter: $29 for 40 directories - Growth: $49 for 70 directories - Scale: $79 for 110 directories - All Directories: $149 for every directory in the catalogue (170 today) and every one added after purchase - White label for agencies: from $40 per client, in bundles of 3, 10 or 50 launches; one launch submits one client's product to up to 110 directories; agencies run it from a console, the API or an MCP server Delivery: most directories go out within 24-48 hours; in peak periods we give ourselves up to 21 days to deliver every directory in a package. Refunds: you can request a refund within 30 days of purchase, on the conditions in our [Terms](https://submitator.com/terms#refunds). ## Pages - [Home and pricing](https://submitator.com/): what Submitator does, the plans with checkout and the FAQ - [White label for agencies](https://submitator.com/white-label): resell directory submissions under your own brand, from $40 per client, from a console, the API or an MCP server - [API docs](https://submitator.com/docs): the Submitator API for agencies; every docs page is listed below - [SEO MCP server for directory submissions](https://submitator.com/mcp): lets claude.ai, ChatGPT, Claude Code, Cursor or another MCP client create an agency's client projects, launch them on up to 110 directories each and track the listings - [Badge package](https://submitator.com/badge-package): the open-source npm package that renders your directory badges into the HTML your server sends, for Next.js, Nuxt, SvelteKit and Astro - [Where to submit your startup](https://submitator.com/where-to-submit-your-startup): 100+ directories for dofollow backlinks, banded by Domain Rating, with step-by-step submission guides - [Best directory submission tools](https://submitator.com/best-directory-submission-tools): directory submission tools compared on price, directory choice, speed and automation - [Product Hunt alternatives](https://submitator.com/product-hunt-alternatives): Product Hunt alternatives compared on Domain Rating, whether the outbound link is followed and what it costs - [Free Domain Rating checker](https://submitator.com/domain-rating-checker): check any website's Domain Rating by Ahrefs for free, no signup - [Free Stripe fee calculator](https://submitator.com/stripe-fee-calculator): Stripe's fee and your payout on any payment and what to charge to receive an exact amount, for US, UK, euro area, Canadian and Australian accounts - [Free MRR calculator](https://submitator.com/mrr-calculator): MRR and ARR from a customer count or a plan mix, with net new MRR, churn rate and a 12-month projection - [Free link preview checker](https://submitator.com/link-preview-checker): how a page's link shows on Google, X, LinkedIn and Slack, which Open Graph tags are broken and fixed tags to copy - [Free landing page roast](https://submitator.com/roast-my-landing-page): an AI review of a landing page: a score out of 10 for the offer, headline, CTA, proof and clarity, with one fix for each - [Directory submission sites](https://submitator.com/blog/directory-submission-sites): every directory in our catalogue grouped by the link a listing gives, with DR, link type and badge rule - [Dofollow vs nofollow links](https://submitator.com/blog/dofollow-vs-nofollow): what dofollow links are, the HTML for each rel value, what nofollow, ugc and sponsored tell Google, what link juice and link equity mean and how to check the rel of any link - [Web directories](https://submitator.com/blog/web-directories): what a web directory is, the history from Yahoo! and DMOZ and which kinds still work in 2026 - [Reciprocal links](https://submitator.com/blog/reciprocal-links): what Google's link spam policy says about link backs, why a directory badge is one and what directories charge to skip it - [Website submission sites](https://submitator.com/blog/website-submission-sites): how to submit a website to Google, Bing and IndexNow for free, then the 30 strongest directories with what each submission takes - [Free backlink sites](https://submitator.com/blog/free-backlink-sites): where free backlinks come from by type (directories, DEV and Hashnode posts, communities, profiles) and the rel each one carries live - [Directories list](https://submitator.com/blog/directories-list): the directories we submit to grouped by the product they take (AI, SaaS and software, developer tools, launches), with DR, link type and badge rule - [How to index backlinks](https://submitator.com/blog/how-to-index-backlinks): why Google has not seen a new directory listing yet, how long crawling takes, how to check it and how Submitator pushes listings through IndexMachine - [Dofollow directories](https://submitator.com/blog/dofollow-directories): the dofollow directories in our catalog sorted by DR, each beside what a count of its live listings found and when - [Free dofollow directories](https://submitator.com/blog/free-dofollow-directories): free dofollow directories confirmed by our guides, split into those that ask nothing and those that want a badge, a link back or a wait - [What is a good domain rating](https://submitator.com/blog/what-is-a-good-domain-rating): DR bands from our directory catalog and our own sites, how Ahrefs DR differs from Moz DA and what raises a domain rating - [High DR directories](https://submitator.com/blog/high-dr-directories): dofollow directories at DR 50 and up, split at DR 70, with referring domains, badge rules and the free ones - [Badge-free directories](https://submitator.com/blog/badge-free-directories): the directories we submit to that need no badge on your site, grouped by link type - [Instant approval directories](https://submitator.com/blog/instant-approval-directories): directories that publish a listing with no review queue, each confirmed by its guide or its own site, plus the ones that sell instant approval - [LLM SEO](https://submitator.com/blog/llm-seo): which AI crawlers the directories we submit to let in (robots.txt read on 2 Nov 2026), what 27 Google AI Mode answers cited and a checklist for ChatGPT, Perplexity and AI Overviews - [Automated link building](https://submitator.com/blog/automated-link-building): what link building software can run at each stage, what a person or the site still decides and what Google's link spam policy says about automation - [How to get backlinks](https://submitator.com/blog/how-to-get-backlinks): where the strongest followed backlinks of six of our own sites came from (Ahrefs, 23 Oct 2026) and 11 ways to get backlinks, ranked by cost and by who decides the link - [White label link building](https://submitator.com/blog/white-label-link-building): the link types agencies resell under their own brand, who decides each link, what providers charge per link and the margin on a white label launch - [Dofollow backlinks](https://submitator.com/blog/dofollow-backlinks): how many of six real sites' strongest backlinks pass a followed link by source and by DR (Ahrefs, 23 Oct 2026) and what a dofollow backlink costs where a directory sells one - [SEO for startups](https://submitator.com/blog/seo-for-startups): an SEO plan for a startup on a new domain: the first 30 days, keyword research from low difficulty up (47% of 3,823 phrases in our own research had KD 10 or less), the pages a SaaS needs and its first links - [SaaS link building](https://submitator.com/blog/saas-link-building): where a SaaS gets its links, source by source: what each costs and who decides it, the SaaS directories we submit to counted from our catalog, app marketplace links measured and what agencies charge per link (read 5 Nov 2026) - [Link building tools](https://submitator.com/blog/link-building-tools): which tools the top-ranking lists of link building tools name most (counted 5 Nov 2026), each tool's price by job from its own page, a free stack and the step no tool takes: placing the link - [Link building services](https://submitator.com/blog/link-building-services): what link building services and companies sell and what one link costs, priced on the sellers' own pages (10 Nov 2026) by link type, with the checks to run before paying and where directory listings sit - [High quality backlinks](https://submitator.com/blog/high-quality-backlinks): seven markers of a high quality backlink, a free check for each and what our catalog records against them for the directories we submit to - [White hat link building](https://submitator.com/blog/white-hat-link-building): white hat link building read against Google's own link spam policy (10 Nov 2026): each kind of link, who decides it and where directory submissions sit - [SaaS SEO](https://submitator.com/blog/saas-seo): SaaS SEO by page type and the search each answers, content as the channel, technical SEO for an app and what SaaS SEO agencies charge on their own sites (10 Nov 2026) - [Product launch checklist](https://submitator.com/blog/product-launch-checklist): a product launch checklist for a SaaS or AI tool from eight weeks out to 30 days after, with the launch sites we submit to counted, free launch queues read on 10 Nov 2026 and a template to copy - [Product description examples](https://submitator.com/blog/product-description-examples): taglines, one-line, short and long descriptions for a software listing, written to the field limits we record for 54 directories, with a template - [Directory submission cost](https://submitator.com/blog/directory-submission-cost): what directory submission costs three ways, priced on 10 Nov 2026: a free listing's work, nine directories' paid tiers and 25 services' packages, per directory - [Directory submission checklist](https://submitator.com/blog/directory-submission-checklist): everything to prepare once before submitting to directories: product facts, the logo and screenshot sizes directories ask for, accounts, badges, a tracking sheet and the checks once a listing is live - [Directory submission statistics](https://submitator.com/blog/directory-submission-statistics): what happened to our submissions for paid orders from July to November 2026: the share that landed, how fast, how many were closed without a listing, by DR band and by kind of directory - [SEO reseller programs](https://submitator.com/blog/seo-reseller): what SEO reseller programs resell line by line, who does the work, what each line costs per client (10 Nov 2026), white label against private label and directory submissions as the line to resell first - [SaaS marketing](https://submitator.com/blog/saas-marketing): SaaS marketing channels by stage from before launch to growth: what each costs, what it leaves behind and what SaaS marketing agencies charge on their own sites (10 Nov 2026) - [How to promote a website](https://submitator.com/blog/how-to-promote-a-website): how to promote a website for a software product: twelve free and paid channels with what each one asks and costs (10 Nov 2026) and the kinds of website promotion sites - [What is a backlink](https://submitator.com/blog/what-is-a-backlink): what a backlink is in Google's own words, how backlinks work, the types of backlinks with who does the work for each and five real backlinks read on live pages (12 Nov 2026) - [Early adopters](https://submitator.com/blog/early-adopters): who early adopters are on the adoption curve, how they differ from innovators and the early majority and where software founders find their first users, each channel priced (12 Nov 2026) - [Off-page SEO](https://submitator.com/blog/off-page-seo): what off-page SEO is next to on-page and technical SEO, the off-page techniques with what each costs on its provider's page (12 Nov 2026) and a checklist for a new product - [Anchor text](https://submitator.com/blog/anchor-text): what anchor text is, its types with HTML examples, what the anchor text ratio question comes down to and what the directories we submit to put on the link to a listing (12 Nov 2026) - [SaaS landing page](https://submitator.com/blog/saas-landing-page): what a SaaS landing page carries section by section, counted on live SaaS home pages (12 Nov 2026), with examples, best practices and where landing pages get listed - [Social bookmarking sites](https://submitator.com/blog/social-bookmarking-sites): which social bookmarking, profile creation and web 2.0 sites from the usual SEO lists still load, still show a signup and still give a followed link (12 Nov 2026) - [Disavow backlinks](https://submitator.com/blog/disavow-backlinks): when Google's own help page says to disavow backlinks, the disavow file and its steps in Search Console, the tool's status in 2026, negative SEO and what Moz Spam Score measures - [SaaS metrics](https://submitator.com/blog/saas-metrics): the SaaS metrics and KPIs with their formulas worked on one made-up company: ARR vs MRR, churn, GRR, CAC, LTV:CAC, CAC payback, the rule of 40 and burn multiple, each benchmark from its named source (16 Nov 2026) - [Programmatic SEO](https://submitator.com/blog/programmatic-seo): what programmatic SEO is, six real page families counted from their own sitemaps (16 Nov 2026), what Google's scaled content abuse policy says and the tools that build template pages - [SaaS pricing models](https://submitator.com/blog/saas-pricing-models): the SaaS pricing models (per seat, tiered, usage based, hybrid, freemium and free trials) counted on the live pricing pages of well-known SaaS (17 Nov 2026) and how to price a SaaS product - [llms.txt](https://submitator.com/blog/llms-txt): what llms.txt is, the format from the spec, how to write and check one and which software sites and directories served one (17 Nov 2026) - [Micro SaaS](https://submitator.com/blog/micro-saas): what micro SaaS is, with real examples and ideas from products launched on launch boards (1 to 18 Nov 2026) and how to start, price and market one - [.ai domain vs .io vs .com](https://submitator.com/blog/ai-domain): what the .ai and .io domains are, what they cost at registrars, how Google treats them and which extensions AI products and startups use, counted (18 Nov 2026) - [Vibe coding](https://submitator.com/blog/vibe-coding): what vibe coding is and who coined the term, the tools and platforms with their prices and how many November launches carry a vibe coding platform's mark (19 Nov 2026) - [Startup credits](https://submitator.com/blog/startup-credits): the startup credit programs of cloud, AI and software vendors read on their own pages: amounts, who qualifies and what needs no investor (19 Nov 2026) - [Website not showing up on Google](https://submitator.com/blog/website-not-showing-up-on-google): why a new website does not show up on Google and how to fix it, with a site: search and a search for each product's own name across November launches (19 Nov 2026) - [AI wrapper](https://submitator.com/blog/ai-wrapper): what an AI wrapper or GPT wrapper is, what model APIs cost per request and which models new AI tools name on their home pages (19 Nov 2026) - [Stripe alternatives](https://submitator.com/blog/stripe-alternatives): payment processors and merchants of record read on their own pricing pages, with the fee on one small sale and who files sales tax (19 Nov 2026) - [Google Analytics alternatives](https://submitator.com/blog/google-analytics-alternatives): Google Analytics alternatives priced from each vendor's own pages, plus the analytics tools November launches load in the pages they serve (19 Nov 2026) - [Product-market fit](https://submitator.com/blog/product-market-fit): what product-market fit is from the primary sources, the 40% survey as survey tools ship it, how to measure it and its stages (19 Nov 2026) - [Solopreneur](https://submitator.com/blog/solopreneur): what a solopreneur is, how it differs from an entrepreneur, a freelancer or a solo founder, plus who November launches name as their maker (19 Nov 2026) - [All Directories](https://submitator.com/all-directories): one payment for every directory in the catalogue and every one we add - [Reviews](https://submitator.com/reviews): real customer messages, published unedited, with links to the public ones ## Submitator API > The Submitator API launches your clients' products on up to 110 directories each, under your agency's brand. Each link below is the Markdown of a page of https://submitator.com/docs; the same URL without .md is the page. Every page in one file: https://submitator.com/llms-full.txt. The OpenAPI 3.1 document of the API: https://api.submitator.com/v1/openapi.json. The MCP server puts the same API in claude.ai, ChatGPT, Claude Code, Cursor or another MCP client: run `npx -y submitator-mcp` on your machine or connect to the remote server at https://mcp.submitator.com/mcp. Setup for each client: https://submitator.com/docs/mcp.md. --- # Introduction URL: https://submitator.com/docs > The Submitator API launches your clients' products on up to 110 directories each, under your agency's brand. **Launch every client from your code** Create a project for each client, launch it on up to 110 directories, and follow every listing until it is live. The work the console does, over REST and JSON. The API is for agencies that sell directory listings to their own clients. You create a project from your client's URL, add a logo and a screenshot, and launch it. We submit the product to each directory and report every listing back to you. Your client sees your brand: reports carry your agency's name, and the badge links to your site. You see every status, live link and proof in one place. ## You can use it to - **Add a client by URL.** Send the site's address and we fill in the name, tagline and description we find there. You add a logo, 1 to 5 screenshots and a contact email. - **Preview a launch before you spend.** A free readiness call shows how many directories the project gets now, up to 110, and what would add more. - **Launch with one call.** One launch picks up to 110 directories the project qualifies for and starts a listing at each. - **Track every listing.** Read each listing's status and live link, or get every change pushed to your endpoint as a signed webhook. - **Build it for free.** A test key runs every call in test mode: listings move on their own in about 15 minutes, and nothing is spent. ## How a launch works 1. You create a project. It stays a draft until you launch it, and a draft costs nothing. 2. You launch it. That uses 1 launch from your balance and creates up to 110 listings, one per directory. 3. Each listing moves from `pending` to `live`, or ends `not_accepted` or `cancelled`. Most listings go live within a week. [How it works](https://submitator.com/docs/how-it-works) covers every status and the words these docs use. ## Base URL Every request goes to `https://api.submitator.com/v1` with your key in the `Authorization` header. Requests and responses are JSON, ids are strings with a type prefix such as `prj_`, and times are ISO 8601 in UTC. v1 is stable: a change that can break working code only ever ships in a new version. [Versioning](https://submitator.com/docs/versioning) has the policy. ## Next steps - [Quickstart](https://submitator.com/docs/quickstart): From a free test key to a signed webhook, step by step. - [Test mode](https://submitator.com/docs/test-mode): What a test key does, and what it simulates. - [API reference](https://submitator.com/docs/api): Every route on one screen, then each operation in full. - [Webhooks](https://submitator.com/docs/webhooks/signatures): Signed events at your endpoint as they happen. --- # Quickstart URL: https://submitator.com/docs/quickstart > Get a free test key, launch a client's project in test mode and receive a signed webhook when one of its listings goes live. This guide takes one client's product from a URL to a live listing in test mode, and receives that change as a signed webhook. Test mode is free: nothing reaches a directory and nothing is spent. Each step shows the request in cURL, Node and Python, and the response under it. ## Before you start - **A free account.** Create your agency at [app.submitator.com/agency/start](https://app.submitator.com/agency/start?next=/agency/developers). Test mode needs no payment. - **A test key.** In the console, open Developers, choose the TEST tab and create a key. It starts with `sbm_test_` and is shown once. - **An HTTPS URL that answers a POST**, for step 6. Your own server works, or a request inspector for a first look. Put the key in an environment variable, so it stays out of your code: ```bash export SUBMITATOR_API_KEY="sbm_test_..." ``` The Node examples run as ES modules (`.mjs`) on Node 20 or later. The Python examples need `pip install requests`. ## 1. Check your key `GET /ping` returns the account and the key behind the request. ```bash curl https://api.submitator.com/v1/ping \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/ping", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/ping", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200: ```json { "object": "ping", "ok": true, "livemode": false, "account": { "name": "Northlight Studio", "state": "setup" }, "key": { "id": "key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW", "permissions": "full" } } ``` `livemode` is `false`: every call with this key runs in test mode. A 401 means the key is missing or wrong, see [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid). ## 2. Create a project Send the site's URL and a contact email; `external_id` holds your own reference. Test mode accepts sites on `.test`, so the example runs as it is. ```bash curl https://api.submitator.com/v1/projects \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://ledgerly.test", "contact_email": "founder@ledgerly.test", "external_id": "crm_8812"}' ``` ```js const res = await fetch("https://api.submitator.com/v1/projects", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://ledgerly.test", contact_email: "founder@ledgerly.test", external_id: "crm_8812", }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={ "url": "https://ledgerly.test", "contact_email": "founder@ledgerly.test", "external_id": "crm_8812", }, ) print(res.json()) ``` Response 201 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "draft", "url": "https://ledgerly.test", "name": "Ledgerly", "contact_email": "founder@ledgerly.test", "logo": null, "screenshots": [], "autofill": { "status": "running", "name_source": "domain", "filled": [], "image_candidates": [] }, "readiness": { "ready": false, "missing": ["logo", "screenshots"] }, "external_id": "crm_8812", "created_at": "2026-10-03T13:58:12Z", "launched_at": null } ``` Keep the `id`: every next step uses it. ## 3. Add a logo and a screenshot Import each image from a URL, or upload the file as `multipart/form-data` with a `file` field. In test mode we check the request but download and keep nothing, so an image's `url` is a placeholder. ```bash curl -X PUT https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/logo \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://ledgerly.test/press/logo.png"}' curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/screenshots \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -F "file=@dashboard.png" ``` ```js import fs from "node:fs"; const base = "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP"; const auth = { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }; await fetch(`${base}/logo`, { method: "PUT", headers: { ...auth, "Content-Type": "application/json" }, body: JSON.stringify({ url: "https://ledgerly.test/press/logo.png" }), }); const form = new FormData(); form.append("file", await fs.openAsBlob("dashboard.png"), "dashboard.png"); const res = await fetch(`${base}/screenshots`, { method: "POST", headers: auth, body: form }); console.log(await res.json()); ``` ```python import os import requests base = "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP" auth = {"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"} requests.put(f"{base}/logo", headers=auth, json={"url": "https://ledgerly.test/press/logo.png"}) with open("dashboard.png", "rb") as image: res = requests.post(f"{base}/screenshots", headers=auth, files={"file": image}) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "draft", "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "error": null } ], "readiness": { "ready": true, "missing": [] } } ``` A project holds 1 logo and 1 to 5 screenshots. An image URL that ends in `/fail.png` fails on purpose, so you can see how your code handles 422 `image_unreachable`. ## 4. Preview and launch `GET /projects/{project_id}/readiness` is free and shows what a launch would do now. Before your first purchase, test mode picks from the top 20 directories of the catalog, so a launch gets 20 of them at most. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` When `ready` is `true`, launch. It uses 1 of your 100 test launches, and `"auto"` takes the directories the project qualifies for. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"directories": "auto"}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ directories: "auto" }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={"directories": "auto"}, ) print(res.json()) ``` Response 202 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "in_progress", "launched_at": "2026-10-03T14:05:40Z", "allowance": { "total": 110, "used": 0, "reserved": 16, "available": 94 }, "progress": { "total": 16, "pending": 16, "in_progress": 0, "action_required": 0, "submitted": 0, "live": 0, "not_accepted": 0, "cancelled": 0 } } ``` From here the listings move on their own and the project completes in about 15 minutes. Step 7 moves one of them right away. ## 5. Find a listing Each directory gets one listing. Take the first one and keep its `id`. ```bash curl "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings?limit=1" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings?limit=1", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, params={"limit": 1}, ) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "list", "data": [ { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "domain_rating": 73 }, "status": "pending", "live_url": null } ], "has_more": true, "next_cursor": "cur_8Tq2Xn5Wb1Lz7Pd3" } ``` ## 6. Add a webhook endpoint Register the URL that should receive events. Replace `https://hooks.northlight.test/listings` with yours: it must be a public `https` URL. ```bash curl https://api.submitator.com/v1/webhook_endpoints \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://hooks.northlight.test/listings", "events": ["listing.*", "project.*"]}' ``` ```js const res = await fetch("https://api.submitator.com/v1/webhook_endpoints", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://hooks.northlight.test/listings", events: ["listing.*", "project.*"], }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/webhook_endpoints", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={ "url": "https://hooks.northlight.test/listings", "events": ["listing.*", "project.*"], }, ) print(res.json()) ``` Response 201 (some fields left out): ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "events": ["listing.*", "project.*"], "enabled": true, "secret": "whsec_9laRgOMT0C3d8Je6FbArCUY0bGJM+r2emaNUGJCH+aw=", "created_at": "2026-10-06T12:00:04Z" } ``` The `secret` is shown in this response only. Store it as `SUBMITATOR_WEBHOOK_SECRET` for step 8. ## 7. Move the listing to live The test helper moves a test listing 1 step along the usual path on each call: `in_progress`, then `submitted`, then `live`. Each move records its event and sends it to your endpoint. ```bash for step in 1 2 3; do curl https://api.submitator.com/v1/test_helpers/listings/lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK/advance \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' done ``` ```js let listing; for (let step = 0; step < 3; step++) { const res = await fetch( "https://api.submitator.com/v1/test_helpers/listings/lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK/advance", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: "{}", }, ); listing = await res.json(); } console.log(listing); ``` ```python import os import requests for step in range(3): res = requests.post( "https://api.submitator.com/v1/test_helpers/listings/lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK/advance", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={}, ) print(res.json()) ``` Response 200 to the third call (some fields left out): ```json { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "domain_rating": 73 }, "status": "live", "live_url": "https://betalist.com/startups/ledgerly", "live_at": "2026-10-08T14:00:00Z" } ``` If the simulation moved the listing first, a call can return 422 `validation_failed`. Pick another listing from step 5. ## 8. Check the webhook Your endpoint received `listing.in_progress`, `listing.submitted` and `listing.live` for this listing. The last one looks like this: The delivery, its body cut short: ```http POST /listings HTTP/1.1 Host: hooks.northlight.test Content-Type: application/json webhook-id: evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ webhook-timestamp: 1791469022 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= {"object":"event","id":"evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ","type":"listing.live","livemode":false,"project":"prj_4QzX1m9Lr2Vb7Nc8Tk3HwP","data":{"object":{"object":"listing","id":"lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK","status":"live"},"previous_status":"submitted"}} ``` Check the signature before you trust the body, with the official Standard Webhooks library and your secret. A delivery that fails the check did not come from us: answer 400 and ignore it. verify-webhook.mjs: ```js import { Webhook } from "standardwebhooks"; // The whsec_ secret of your endpoint, shown once when you added it. const secret = process.env.SUBMITATOR_WEBHOOK_SECRET; // Returns the event when the delivery is ours. Throws a // WebhookVerificationError when the signature does not match or the // timestamp is more than 5 minutes from your clock. export function verifyWebhook(rawBody, headers, whsec = secret) { return new Webhook(whsec).verify(rawBody, headers); } ``` ```python # pip install standardwebhooks import os from standardwebhooks.webhooks import Webhook webhook = Webhook(os.environ["SUBMITATOR_WEBHOOK_SECRET"]) # raw_body: the request body as bytes. Raises WebhookVerificationError # when the delivery is not ours. def verify_webhook(raw_body, headers): return webhook.verify(raw_body, headers) ``` [Signatures](https://submitator.com/docs/webhooks/signatures) has the same check in Ruby, PHP and Go, and without a library. ## Check it worked - `GET /webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/deliveries` shows the `listing.live` delivery as `succeeded`. - `GET /events?project=prj_4QzX1m9Lr2Vb7Nc8Tk3HwP` lists `project.launched` and every listing event since. - `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP` shows `progress.live` of 1 or more. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`not_ready`](https://submitator.com/docs/errors#not_ready) | 422 | The project misses a logo, a screenshot or the contact email. Nothing was spent. | | [`endpoint_url_invalid`](https://submitator.com/docs/errors#endpoint_url_invalid) | 422 | The webhook URL must be a public `https` URL, without a user name or password. | | [`test_mode_only`](https://submitator.com/docs/errors#test_mode_only) | 403 | The test helper got a live key. Check that `SUBMITATOR_API_KEY` starts with `sbm_test_`. | | [`quota_exceeded`](https://submitator.com/docs/errors#quota_exceeded) | 422 | Before your first purchase, test mode allows 25 projects, 100 new projects a day and 3 webhook endpoints. | ## Next steps - [Onboard a client's product](https://submitator.com/docs/guides/onboard-a-clients-product): autofill, images and the fields directories ask for. - [Test mode](https://submitator.com/docs/test-mode): what is simulated, and the inputs that fail on purpose. - [Receive webhooks](https://submitator.com/docs/guides/receive-webhooks): an endpoint that handles every event once. - [Go-live checklist](https://submitator.com/docs/guides/go-live-checklist): from test mode to your first live launch. --- # MCP server URL: https://submitator.com/docs/mcp > Connect claude.ai, ChatGPT, Claude Code, Cursor, VS Code or another MCP client to the API, so your assistant creates client projects, previews and launches them and follows their listings. The Submitator MCP server lets an AI assistant use the API for your agency. MCP, the Model Context Protocol, is how assistants such as claude.ai, ChatGPT, Claude Code, Cursor and VS Code call outside tools. Your assistant creates a client's project from a URL, shows the free preview and launches the project once you agree. Then it follows the listings as they go live. It calls the API with your agency key and does nothing the API does not. It comes two ways: - **The npm package** [`submitator-mcp`](https://www.npmjs.com/package/submitator-mcp) runs on your machine with `npx` (Node.js 20 or newer). It can also read local images and save reports to disk. - **The remote server** at `https://mcp.submitator.com/mcp` needs no install. It reads and saves no files, and claude.ai and ChatGPT connect to it by signing in instead of with a key. Both run the same code, open source under the MIT license on [GitHub](https://github.com/submitator/submitator-mcp). What it does for an agency, in short, is on [the MCP server page](https://submitator.com/mcp). ## Connect claude.ai With claude.ai you need no key: you sign in with your agency account, and the sign-in creates one. ChatGPT signs in the same way ([Connect ChatGPT](#chatgpt)), and the other clients on this page connect with an agency key: for those, start at [Get a key](#get-a-key). You need an agency before step 1: create it at [app.submitator.com/agency/start](https://app.submitator.com/agency/start). Test mode needs no payment. 1. In claude.ai, open **Customize**, then **Connectors**. Press **+ Add**, then **Add custom connector**. 2. Name it `Submitator` and enter `https://mcp.submitator.com/mcp` as the URL, or open [the dialog with both filled in](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Submitator&connectorUrl=https%3A%2F%2Fmcp.submitator.com%2Fmcp). Press **Continue**, check the settings it detects and press **Continue** again. 3. Under **Authentication**, pick **Sign in now**. Under **OAuth client**, pick **Use Claude's published identity (Recommended)**. Leave **Request headers** empty and press **Add**. 4. Submitator's sign-in opens: log in to the agency console. The page names the client and its host, Claude from claude.ai. 5. Pick **Test** or **Live** and **Full** or **Read only**, then press **Allow Claude**. 6. In a chat, press **+**, then **Connectors**, and switch Submitator on. Live needs a paid agency: a new agency gets Test only, and test mode submits nothing ([Start in test mode](#start-in-test-mode)). Full creates, launches and reports as the API does, and Read only checks statuses and refuses every change. The sign-in creates a key labelled `MCP: Claude` on the console's Developers page, and Claude receives that key only inside encrypted tokens. Revoke the key there to disconnect claude.ai: the server answers its next call by asking it to sign in again. A connector you add on claude.ai also works in Claude Desktop and in the Claude apps for iOS and Android, on the same Claude account. ### For an organization On a Claude Team or Enterprise plan, an Owner adds the connector once under **Organization settings**, then **Connectors**: **Add**, **Custom**, then **Web**, with the same name, URL and sign-in settings. Each member then opens **Customize**, then **Connectors**, presses **Connect** next to Submitator and signs in to the agency console. Each sign-in creates a key of its own on Developers. ## Connect ChatGPT ChatGPT on the web adds the remote server as a custom MCP server, and you sign in with your agency account instead of copying a key. Create the agency first, as for claude.ai. ChatGPT's workspace permissions and security restrictions apply to custom MCP servers. 1. Open [ChatGPT Plugins](https://chatgpt.com/plugins), press the plus button, then **Add custom MCP server**. 2. Name it `Submitator`. Under **Connection**, enter `https://mcp.submitator.com/mcp` as the **Server URL**. 3. For authentication, pick **OAuth**, with a Client ID Metadata Document (CIMD) as the way ChatGPT identifies itself. Enter no client ID or secret: Submitator needs neither. 4. Review the risk warning and select **I understand and want to continue**, then **Create as a plugin**. 5. Install the plugin. In a chat, type `@` and pick it. When ChatGPT sends you to Submitator's sign-in, log in to the agency console, pick **Test** or **Live** and **Full** or **Read only**, and allow it. The sign-in creates a key labelled `MCP:` and the client's name on the console's Developers page, and ChatGPT receives that key only inside encrypted tokens. Revoke the key there to disconnect ChatGPT. ChatGPT treats a tool without a read-only hint as a write and asks you to confirm writes by default. You can let it remember an approval for the rest of a chat. Do not do that for `launch_project`, `add_directories` and `update_project`, as [Keys and safety](#keys-and-safety) says: a launch spends one of your launches. ## Get a key Claude Code, Cursor, VS Code and the other clients below connect with an agency key. 1. Create your agency at [app.submitator.com/agency/start](https://app.submitator.com/agency/start?next=/agency/developers/mcp). Test mode needs no payment. 2. In the console, open Developers, then MCP. Pick your client and create a test key: the key is shown once, together with that client's setup with the key already in it. A `sbm_test_` key is free from the day you create your agency and runs in [test mode](https://submitator.com/docs/test-mode). A `sbm_live_` key comes with your first purchase, and each launch it starts spends one of your launches. ## Install The package runs with `npx`, so there is nothing to install by hand. Keep the key in your user-level config, never in a file that lives in a repository. Claude Code, in user scope: ```bash claude mcp add --scope user submitator --env SUBMITATOR_API_KEY=sbm_test_... -- npx -y submitator-mcp ``` Cursor, in ~/.cursor/mcp.json: ```json { "mcpServers": { "submitator": { "command": "npx", "args": ["-y", "submitator-mcp"], "env": { "SUBMITATOR_API_KEY": "sbm_test_..." } } } } ``` VS Code, in .vscode/mcp.json: ```json { "inputs": [ { "type": "promptString", "id": "submitator-key", "description": "Submitator API key", "password": true } ], "servers": { "submitator": { "type": "stdio", "command": "npx", "args": ["-y", "submitator-mcp"], "env": { "SUBMITATOR_API_KEY": "${input:submitator-key}" } } } } ``` Claude Desktop, in claude_desktop_config.json: ```json { "mcpServers": { "submitator": { "command": "npx", "args": ["-y", "submitator-mcp"], "env": { "SUBMITATOR_API_KEY": "sbm_test_...", "SUBMITATOR_FILES_DIR": "/path/to/client/images" } } } } ``` - **Claude Code:** user scope keeps the key out of the project's `.mcp.json`. - **Cursor:** `~/.cursor/mcp.json` is the user-level file. - **VS Code** asks for the key when the server starts and keeps it out of the file. - **Claude Desktop** starts servers in the disk root, so `SUBMITATOR_FILES_DIR` names the folder of the [local images](#local-files) you want to upload. Leave it out if you add images by URL only. - **Devin Desktop (formerly Windsurf), Cline and other MCP clients:** add a server that runs `npx -y submitator-mcp` with `SUBMITATOR_API_KEY` in its environment, or use the remote server below. ## Remote server A client that connects over HTTP can use the remote server instead of the package. Send your key in the `Authorization` header as `Bearer` and the key, or in an `X-API-Key` header. With claude.ai or ChatGPT you sign in instead ([Connect claude.ai](#claude-ai), [Connect ChatGPT](#chatgpt)). Claude Code, remote server: ```bash claude mcp add --transport http submitator https://mcp.submitator.com/mcp \ --header "Authorization: Bearer $SUBMITATOR_API_KEY" ``` The remote server passes your key on to the API and keeps nothing between requests. It reads and saves no files, so `save_report_file` and local image paths work only with the package. ## Start in test mode With a test key, projects and listings are test data: nothing is submitted, and test launches are not bought ones. Ask your assistant to run `whoami` first: it names the agency, the mode and the launches left. Then let your assistant create a project, preview it and launch it. Test listings move on their own in about 15 minutes. `advance_test_listing` moves one on at once, and `set_test_launches` sets how many test launches you have. [Test mode](https://submitator.com/docs/test-mode) has the rules. ## What the tools do | Tool | What it does | | --- | --- | | `whoami` | The agency and mode behind the key, its permissions, launches left and the hourly budget. | | `list_projects`, `get_project` | Find client projects; read one in full. | | `create_project`, `update_project`, `delete_draft` | Create a project from a URL, change its fields, delete a draft. | | `set_logo`, `add_screenshot`, `remove_image` | Images from a public URL, or a local file with the package. | | `preview_launch` | A free dry run of a launch or an add with the same arguments: how many directories, top and median DR, what is missing and the cost. | | `find_directories`, `project_directories` | Search the catalog; see one project's directory choices. | | `launch_project` | Starts submissions and spends one launch, a test launch with a test key. It refuses unless `confirm_selected` equals the count `preview_launch` shows for the same arguments. | | `add_directories` | Reaches more directories from a launched project's free allowance, with the same check. | | `list_listings`, `list_events` | Follow the listings and what changed since a given time. | | `get_badge`, `verify_badge` | The badge install code for the client's site, and a check that it is there. | | `create_report`, `get_report`, `save_report_file` | Build a PDF or XLSX report; save it to disk with the package. | | `get_share_link`, `create_share_link`, `delete_share_link` | The client's progress page, with a live key. | | `advance_test_listing`, `set_test_launches` | Test mode helpers, with a test key. | Two prompts come with it: `launch_client_project` walks through a launch, and `client_progress_update` drafts a note for your client that does not name Submitator. ## Keys and safety - Keep the key in your MCP client's user-level config on your own machine. Never put it in a file that lives in a repository. - A read-only key fits an assistant that only checks status: projects, listings, events and existing reports. Building a report or a client page link needs a key with full permissions, and share links work with a live key only. - Keep your client's approval prompt on for `launch_project`, `add_directories` and `update_project` instead of allowing them always: a launch spends one of your launches. - `launch_project` and `add_directories` refuse unless `confirm_selected` equals the count `preview_launch` shows for the same arguments. With a live key, clients that support questions to their user (MCP elicitation) also ask you before a launch or an add, and the answer never passes through the model. The remote server keeps no session, so there the question reaches only clients on MCP protocol 2026-07-28. - The package reads the key from its environment and sends it only to `https://api.submitator.com`. - Logins and their passwords do not pass through the MCP server. Read them in the console. - Revoke a key in the console under Developers at any time. ## Local files Only the package reads or writes files on your machine. - **Images:** `set_logo` and `add_screenshot` read a `file_path` only inside `SUBMITATOR_FILES_DIR`, or inside the folder the client starts the server in when it is not set. Only real PNG, JPEG, GIF or WebP files up to 5 MB are read, and never through a symlink. - **No folder, no files:** started in your home folder or the disk root without `SUBMITATOR_FILES_DIR`, the server reads no local files at all. - **Reports:** `save_report_file` saves to your Downloads folder unless you name another one, and never over an existing file. A report that includes logins is not saved: download it from the console. ## Troubleshooting | What the tool answers | What to do | | --- | --- | | No Submitator API key | Set `SUBMITATOR_API_KEY` for the package, or the `Authorization` header for the remote server, then restart the server. | | Not a whole Submitator agency key | Paste the key again in full, with no quotes or spaces, then restart the server. | | [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid) (HTTP 401) | The key is unknown, revoked or expired. Create a new one in the console under Developers. | | [`permission_denied`](https://submitator.com/docs/errors#permission_denied) (HTTP 403) | The key is read-only. Use a key with full permissions for anything that changes data. | | [`rate_limited`](https://submitator.com/docs/errors#rate_limited) (HTTP 429) | The answer gives the seconds from `Retry-After`: wait that long, then ask again. The hourly budget is shared by every key of your agency in that mode ([Rate limits](https://submitator.com/docs/rate-limits)). | | A tool is missing | Share link tools show with a live key only, the test helpers with a test key only and `save_report_file` with the package only. Restart the server in your client after you change the key. | Every call the server makes is in the console's request log, under Developers: open a request to see its id, which starts with `mcp-`. When a tool fails, its answer ends with that request id. Quote it when you write to [support](https://submitator.com/docs/support). --- # How it works URL: https://submitator.com/docs/how-it-works > The life of a project and its listings, every status, how long it takes, and the words these docs use. ## The life of a project 1. **Draft.** You create a project from your client's URL and we fill in the name, tagline and short description from the site. You add a logo, 1 to 5 screenshots and a contact email; a draft costs nothing and you can delete it. 2. **Launch.** The launch uses 1 launch from your balance and gives the project an allowance of 110 directories. It creates one listing per directory picked, each in `pending`. 3. **Listings move.** Each listing is prepared, sent to its directory and reviewed there. Most listings go live within a week. 4. **Completed.** The project is `completed` when no listing is `pending`, `in_progress` or `action_required` and nothing is left to add. Listings in `submitted` can still go live after that. A launched project stays: it cannot be deleted, and its `contact_email` can no longer change. ## Listing statuses | Status | What it means | What you do | | --- | --- | --- | | `pending` | Waiting to start. Up to 100 of your listings are in progress at once; the rest wait here. | Nothing. | | `in_progress` | Being prepared and sent to the directory. | Nothing. | | `action_required` | Waiting on you or your client; `action` says what. | Follow `action`. | | `submitted` | The directory has the listing and is reviewing it. | Nothing. | | `live` | Published. `live_url` points to the listing. | Share it with your client. | | `not_accepted` | The directory declined it, could not take it, or took it down; `reason` says which. | Nothing: its place in the allowance comes back. | | `cancelled` | Withdrawn before it reached the directory. | Nothing: its place in the allowance comes back. | The usual path is `pending` → `in_progress` → `submitted` → `live`. A listing can go from `in_progress` to `action_required` and back, and some listings go live without `submitted`. ### Corrections Rarely a status changes after it looked final, and each change sends its own event: - `live` → `not_accepted` with `reason` `removed`, when a directory takes a listing down. - `live` → `submitted`, when a published listing goes back under review. - `not_accepted` or `cancelled` → `pending`, `in_progress`, `submitted` or `live`. The listing keeps its `lst_` id. To keep your records right, store the status of each event as it arrives. Do not assume that `live`, `not_accepted` or `cancelled` are the end. ## Project statuses When more than one fits, the first in this list wins. | Status | When | | --- | --- | | `on_hold` | Work is paused. `hold_reason` is `review` while we review the project, which clears without action from you, or `paused`. | | `action_required` | You or your client need to act; `action` says what. | | `in_progress` | Listings are moving and nobody needs to act. | | `completed` | No listing is `pending`, `in_progress` or `action_required`, and nothing is left to add. | | `draft` | Not launched yet. | ## Actions A project or a listing in `action_required` carries an `action` with a `code` and the side it waits on in `waiting_on`. - **`install_badge`** waits on your client. Some directories list a product only while their badge shows on its site: forward `client_message` to your client as it is, then verify the badge. - **`add_assets`** waits on you. The project needs a logo or a screenshot. New codes can appear. For a code you do not know, show `client_message`, or a general prompt when it is `null`. ## Timing Most listings go live within a week. Each directory reviews on its own schedule, and the listing shows `submitted` while it waits. Up to 100 of your listings are in progress at once, across all your projects. Above that, new listings wait in `pending` and start as others finish; a launch is accepted either way. `GET /account` shows the count in `capacity`. Listing times (`created_at`, `submitted_at`, `live_at`) are rounded down to the hour. An event's `created_at` is exact to the second and comes within about a minute of the change. In test mode the same life takes about 15 minutes, and nothing reaches a directory: see [Test mode](https://submitator.com/docs/test-mode). Every change is an event you can read from `GET /events` or receive as a webhook. ## The allowance Each launch covers up to 110 directories for one project. A project launched before 15 November 2026 keeps 100, and `allowance.total` says which. The allowance counts them in `total`, `used`, `reserved` and `available`. - A listing in `pending`, `in_progress` or `action_required` reserves its place. - A listing that reached its directory, `submitted` or `live`, uses its place. - A listing that ends `not_accepted` or `cancelled` gives its place back, and `POST /projects/{project_id}/listings` adds directories from the available places. With `auto_replace` on, we fill the available places with fitting directories for you within a day: the rest of a launch that took fewer than its `allowance.total`, a place a listing gives back when it ends `not_accepted` or `cancelled`, and directories that join the catalog. Turning it on fills them right away, and so does the badge passing verification. Auto-replace never adds a directory in `excluded_directories`, nor an article platform, which a launch or an add takes only from `include`. New projects start with it on, and a launch with `include` turns it off unless the launch sends `"auto_replace": true`. ## Glossary | Term | Meaning | | --- | --- | | Project | One of your client's products, from draft to its last listing. Ids start with `prj_`. | | Launch | What you buy: 1 launch starts 1 project on up to 110 directories. Your balance is in `GET /account`. | | Allowance | The directories a launch covers for its project (110), and how many are used, reserved and available. | | Listing | One project at one directory, with its status and, once published, its `live_url`. Ids start with `lst_`. | | Directory | A site that lists products, such as BetaList or SaaSHub. Ids start with `dir_`; `GET /directories` is the catalog. | | Domain Rating | A 0 to 100 score of a site's backlink profile, measured by Ahrefs. Directories and projects carry it as `domain_rating`. | | Event | One recorded change to a project, listing or report. Ids start with `evt_`, and the feed keeps 90 days. | | Test mode | Every call made with a `sbm_test_` key: test data, listings that move on their own, nothing spent. | | Webhook endpoint | An HTTPS URL of yours that receives events as they happen. Ids start with `we_`. | --- # Authentication URL: https://submitator.com/docs/authentication > Send your secret key in the Authorization header, from your server or an MCP client on your own machine only. Every request carries your secret key as a bearer token. A request without a valid key gets 401 and changes nothing. ```bash curl https://api.submitator.com/v1/ping \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` The key goes in the `Authorization` header only: the API reads it from nowhere else, such as the query string. ## Keys A key is a prefix, 8 letters or digits, an underscore and 43 more letters or digits: ```text sbm_live_8fK2qL7x_Vb3Nc8Tk3HwPm2Lr9Xz5Qa1Ws4Ed7Rf0Tg6Yh8Uj3Ik ``` | Prefix | Mode | What it does | | --- | --- | --- | | `sbm_live_` | Live | Works on real listings and spends real launches. Live keys come with your first purchase. | | `sbm_test_` | Test | Runs every call on test data: nothing is submitted and nothing is spent. Test keys are free from the day you create your agency. | The key decides the mode: there is no `livemode` parameter, and sending one returns 400 `unknown_parameter`. Each mode has its own projects, listings, events and webhook endpoints. An id from one mode returns 404 `not_found` with a key of the other. `GET /ping` shows which key you sent: its `key.id` (such as `key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW`) is safe to log and to quote to support, the key itself is not. ## Permissions You choose a key's permissions when you create it, and `GET /ping` returns them in `key.permissions`. | Permissions | What the key can do | | --- | --- | | `full` | Read and write: create projects, launch them and spend launches. | | `read_only` | Read only. A call that changes data returns 403 `permission_denied` and changes nothing. | A read-only key reads everything but logins: the [Logins](https://submitator.com/docs/api/logins) operations, and the file of a report with logins, answer it with 403 `permission_denied`. Give a read-only key to anything that only reads, such as a dashboard or the job that copies statuses into your CRM. If that key leaks, it cannot spend a launch. ## Create, roll and revoke Keys live in the console, under Developers: live keys on the LIVE tab, test keys on the TEST tab. A new key is shown once: store it in your secret manager right away. - **Roll** replaces a key. You choose when the old key stops working: now, in 1 hour or in 24 hours, so your servers can switch without downtime. - **Revoke** stops a key at once. The console asks you to type the key's label first. If a key leaks, roll it with "now" and deploy the new one. ## Keep keys on your server A key acts for your whole agency: it can create projects and spend launches. Keep it out of anything a person outside your team can open. - Never put a key in a browser, a mobile app or a desktop app. The API sends no CORS headers, so browser calls fail anyway; call it from your server. - Never commit a key to a repository. Read it from an environment variable, such as `SUBMITATOR_API_KEY` in these docs. - Give each server or integration its own key, so you can roll one without touching the others. An MCP client on your own machine is the one exception to the desktop app rule: its config may hold the key the [MCP server](https://submitator.com/docs/mcp) uses. Give it a key of its own, so you can roll or revoke it alone. Never put a key in an app you ship to others, a browser page or a repository. ## Errors | Code | Status | When | | --- | --- | --- | | [`api_key_missing`](https://submitator.com/docs/errors#api_key_missing) | 401 | The request has no `Authorization` header. | | [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid) | 401 | The key is unknown, revoked or expired. | | [`account_suspended`](https://submitator.com/docs/errors#account_suspended) | 403 | Your account is suspended: reads work, writes do not. | | [`permission_denied`](https://submitator.com/docs/errors#permission_denied) | 403 | A read-only key called an operation that changes data. | | [`not_found`](https://submitator.com/docs/errors#not_found) | 404 | The id belongs to the other mode: a live id sent with a test key, or the other way round. | A read-only key also gets `permission_denied` from the [Logins](https://submitator.com/docs/api/logins) operations and from the file of a report with logins. --- # Test mode URL: https://submitator.com/docs/test-mode > A free sbm_test_ key runs the API on test data. Listings move on their own in about 15 minutes, and nothing is submitted or spent. A key that starts with `sbm_test_` runs every call in test mode: the same routes, objects and errors as live mode, on test data of their own. Nothing reaches a directory and nothing is spent. Test keys are free, so you can build and check an integration before your first purchase. Share links are the one exception: a client page needs a live project, so creating a link with a test key answers 422 `validation_failed`, and reading or turning one off answers 404. ## Get a test key 1. Create your agency at [app.submitator.com/agency/start](https://app.submitator.com/agency/start?next=/agency/developers). Test mode needs no payment. 2. In the console, open Developers, choose the TEST tab and create a key. It is shown once. 3. Call `GET /ping` with it. The response shows `livemode` `false`. ```bash curl https://api.submitator.com/v1/ping \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/ping", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/ping", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200: ```json { "object": "ping", "ok": true, "livemode": false, "account": { "name": "Northlight Studio", "state": "setup" }, "key": { "id": "key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW", "permissions": "full" } } ``` `state` is `setup` until your first purchase and `active` after it. Your test key keeps working either way. ## What works the same - Every route takes the same parameters and returns the same objects, with `livemode` `false`. - Events are recorded as in live mode. Webhooks reach the endpoints you add with a test key, signed the same way. - Errors use the same codes, plus 422 `quota_exceeded` for the limits below. Test data and live data never meet. A live key cannot read a test project, and a test key cannot read a live one: the id returns 404 `not_found`. ## What is simulated | What | In test mode | | --- | --- | | Listings | Each listing moves to `in_progress` after 1 to 5 minutes, to `submitted` after 3 to 8 minutes, and to its outcome after 6 to 15 minutes. | | Outcomes | 80% of listings go `live`, 12% end `not_accepted` and 8% stay `submitted`. The outcome depends only on the listing's id, so a listing always ends the same way. | | Autofill and Domain Rating | Simulated. We do not read your client's site. | | Images | Image URLs are not downloaded, and uploaded files are checked but not stored. An image's `url` is a placeholder. | | Badge feed | Feed URLs have the right shape but return 404. | | Reports | A sample PDF or XLSX, marked TEST MODE. | | Launches | 100 test launches to start. They are not the launches you buy. | A project launched in test mode completes in about 15 minutes. Apart from webhook deliveries, nothing leaves our servers in test mode. [Logins](https://submitator.com/docs/api/logins) are placeholders: about 45% of test listings get one, on the project's contact email or on an address at `login.test`, with a password made from the project's id. A login at `login.test` comes with sample emails whose links point there, and nothing signs up anywhere. A report with logins is the same sample report plus sample logins on `.test` addresses: a Directory logins section in the PDF, a Logins sheet in the XLSX. ## Inputs that fail on purpose | Input | What happens | | --- | --- | | A site whose host starts with `nobadge.`, such as `https://nobadge.ledgerly.test` | The badge never passes: `POST /projects/{project_id}/badge/verify` returns 422 `badge_not_found`. | | An image URL that ends in `/fail.png` | The import returns 422 `image_unreachable`, as an image that cannot be downloaded does in live mode. | Sites on `.test` and `.example` are accepted in test mode. Live mode rejects them with `not_public_url`, so use your client's real site there. ## Move a listing yourself To skip the wait, `POST /test_helpers/listings/{listing_id}/advance` moves a test listing 1 step along the usual path, or to the status you name in `to`. The move must be one the listing could make in live mode, and its event and webhook fire as they would there. ```bash curl https://api.submitator.com/v1/test_helpers/listings/lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK/advance \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "live"}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/test_helpers/listings/lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK/advance", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ to: "live" }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/test_helpers/listings/lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK/advance", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={"to": "live"}, ) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "status": "live", "live_url": "https://betalist.com/startups/ledgerly", "live_at": "2026-10-08T14:00:00Z" } ``` The example moves a listing from `submitted` to `live`. A listing in `pending` goes there in 3 calls without `to`: `in_progress`, `submitted`, then `live`. `POST /test_helpers/account/launches` sets your test launches to any number from 0 to 1,000. Set 0 to see how your code handles 402 `no_launches_left`. Both helpers work with test keys only. A live key gets 403 `test_mode_only`. ## Limits before your first purchase | What | Before your first purchase | After it | | --- | --- | --- | | Directories a launch picks from | The top 20 directories of the catalog, and no article platform | The full catalog | | Test projects | 25 at a time, and 100 new ones a day | No test quota | | Webhook endpoints in test mode | 3 | No test quota | | Requests per UTC hour | 600 | 3,600 | Above a quota, the call returns 422 `quota_exceeded` and changes nothing. Delete test data you no longer need, or wait for the next day. ## Test data Test data is deleted after 30 days without activity. To start over at any time, delete all of it in the console, under Developers. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`quota_exceeded`](https://submitator.com/docs/errors#quota_exceeded) | 422 | A test quota is used up. Delete test data, wait for the next day, or buy launches. | | [`test_mode_only`](https://submitator.com/docs/errors#test_mode_only) | 403 | A live key called a test helper. Send a `sbm_test_` key. | | [`not_found`](https://submitator.com/docs/errors#not_found) | 404 | The id belongs to the other mode. Check which key you sent. | | [`badge_not_found`](https://submitator.com/docs/errors#badge_not_found) | 422 | The site's host starts with `nobadge.`, which never passes in test mode. | ## Next steps - [Quickstart](https://submitator.com/docs/quickstart): from a test key to a signed webhook, step by step. - [Signatures](https://submitator.com/docs/webhooks/signatures): check that a delivery came from us. - [How it works](https://submitator.com/docs/how-it-works): every listing status and when it changes. - [Go-live checklist](https://submitator.com/docs/guides/go-live-checklist): from test mode to your first live launch. --- # Onboard a client's product URL: https://submitator.com/docs/guides/onboard-a-clients-product > Turn a client's URL into a project that is ready to launch, with what we read from the site, images, a contact email and your own references. ## What you'll build A draft project for one client: the name, tagline and short description read from their site, a logo, screenshots and a contact email, plus your CRM's id so you can find it later. When `readiness.ready` is `true`, the project is ready to [launch](https://submitator.com/docs/guides/launch-and-track). A draft costs nothing. ## Before you start - **A key.** A test key works for every step, and test mode accepts sites on `.test`. With a live key, use your client's real site. - **What your client gives you.** The site's URL, an email address they read, and their logo and 1 to 5 screenshots, as files or URLs. The contact email matters: some directories register the listing to it and send their emails there. It cannot change once the project launches. ## 1. Create the project from the URL Only `url` is required. Send the contact email, your own id in `external_id`, and anything else you keep about the client in `metadata`. ```bash curl https://api.submitator.com/v1/projects \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: crm_8812-create" \ -H "Content-Type: application/json" \ -d '{"url": "https://ledgerly.test", "contact_email": "founder@ledgerly.test", "external_id": "crm_8812", "metadata": {"account_owner": "Priya"}}' ``` ```js const res = await fetch("https://api.submitator.com/v1/projects", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Idempotency-Key": "crm_8812-create", "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://ledgerly.test", contact_email: "founder@ledgerly.test", external_id: "crm_8812", metadata: { account_owner: "Priya" }, }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects", headers={ "Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}", "Idempotency-Key": "crm_8812-create", }, json={ "url": "https://ledgerly.test", "contact_email": "founder@ledgerly.test", "external_id": "crm_8812", "metadata": {"account_owner": "Priya"}, }, ) print(res.json()) ``` Response 201 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "draft", "url": "https://ledgerly.test", "name": "Ledgerly", "contact_email": "founder@ledgerly.test", "logo": null, "screenshots": [], "autofill": { "status": "running", "name_source": "domain", "filled": [], "image_candidates": [] }, "readiness": { "ready": false, "missing": ["logo", "screenshots"] }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya" } } ``` The `Idempotency-Key` makes the call safe to send twice: a repeat within 24 hours returns this same project. Each `url`, `contact_email` and `external_id` belongs to one project per mode, so a second project with any of them returns 409 `project_exists`, with the first one in `existing`. ## 2. Wait for the site to be read Right after the create call, `autofill.status` is `running` and `name` comes from the domain. Read the project again until the status is `complete`: by then the name, tagline and short description you left empty are filled in. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js let project; do { await new Promise((resolve) => setTimeout(resolve, 5000)); const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); project = await res.json(); } while (project.autofill.status === "running"); console.log(project.autofill); ``` ```python import os import time import requests while True: time.sleep(5) project = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ).json() if project["autofill"]["status"] != "running": break print(project["autofill"]) ``` autofill once complete: ```json { "status": "complete", "name_source": "site", "filled": ["name", "tagline", "short_description"], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] } ``` Autofill fills only the fields you left empty, and never sets an image by itself. When it ends `failed`, the site could not be read: fill in the fields yourself in step 4. ## 3. Add the images `image_candidates` lists images on the site that could serve: the site's icon as a logo, its social preview as a screenshot. Pass one as `url`, or upload your client's own file as `multipart/form-data`. A project needs 1 logo and 1 to 5 screenshots, in PNG, JPEG, GIF or WebP up to 5 MB. ```bash curl -X PUT https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/logo \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://ledgerly.test/apple-touch-icon.png"}' curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/screenshots \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -F "file=@dashboard.png" ``` ```js import fs from "node:fs"; const base = "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP"; const auth = { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }; await fetch(`${base}/logo`, { method: "PUT", headers: { ...auth, "Content-Type": "application/json" }, body: JSON.stringify({ url: "https://ledgerly.test/apple-touch-icon.png" }), }); const form = new FormData(); form.append("file", await fs.openAsBlob("dashboard.png"), "dashboard.png"); const res = await fetch(`${base}/screenshots`, { method: "POST", headers: auth, body: form }); console.log(await res.json()); ``` ```python import os import requests base = "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP" auth = {"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"} requests.put(f"{base}/logo", headers=auth, json={"url": "https://ledgerly.test/apple-touch-icon.png"}) with open("dashboard.png", "rb") as image: res = requests.post(f"{base}/screenshots", headers=auth, files={"file": image}) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "error": null } ], "readiness": { "ready": true, "missing": [] } } ``` Directories that take a single screenshot use the first one, so add the strongest first. You can also pass `logo_url` and `screenshot_urls` in the create call, and they import in the background. ## 4. Fill in what directories ask for Directories ask for more than a name: a category, the pricing, tags and the maker. Send what you know with `PATCH`; a field you leave out keeps its value. ```bash curl -X PATCH https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"maker_name": "Maya Chen", "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "tags": ["accounting", "bookkeeping", "invoicing"]}' ``` ```js const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ maker_name: "Maya Chen", category: "saas", pricing_model: "freemium", price_amount_cents: 1200, price_period: "monthly", tags: ["accounting", "bookkeeping", "invoicing"], }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={ "maker_name": "Maya Chen", "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "tags": ["accounting", "bookkeeping", "invoicing"], }, ) print(res.json()) ``` | Field | Rule | | --- | --- | | `tagline` / `short_description` / `long_description` | Up to 100, 500 and 2,000 characters. Most directories show the short description. | | `category` | `saas`, `ai_tools`, `dev_tools`, `no_code`, `productivity` or `other`. We map it to each directory's own list. | | `pricing_model` | `free`, `freemium`, `paid` or `open_source`, with `price_amount_cents` and `price_period` for a paid plan. | | `tags` | Up to 10, each up to 40 characters. | | `competitors`, `promo_code`, `audience` | These open more directories: [Reach more directories](https://submitator.com/docs/guides/reach-more-directories). | `null` or an empty string clears a field. A list you send, such as `tags`, replaces the whole list. ## 5. Check that it is ready `GET /projects/{project_id}/readiness` is free. It says whether the project can launch, how many directories a launch would get now, and what would unlock more. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "readiness", "ready": true, "missing": [], "directories": { "selected": 87, "limit": 110, "top_domain_rating": 92, "median_domain_rating": 48 }, "unlocks": [ { "requirement": "badge", "directories": 9, "how": "Install the badge on https://ledgerly.test and verify it." } ], "cost": { "launches": 1, "available": 100 } } ``` Until `ready` is `true`, `missing` names what to add: `contact_email`, `logo` or `screenshots`. ## Check it worked - `GET /projects?external_id=crm_8812` returns the project, so your CRM can find it by its own id. - `readiness.ready` is `true` on the project and on `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness`. - `autofill.status` is `complete`, or you filled in the name, tagline and short description yourself. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`project_exists`](https://submitator.com/docs/errors#project_exists) | 409 | Another project has this `url`, `contact_email` or `external_id`. Use the one in `existing`, or change the field. | | [`validation_failed`](https://submitator.com/docs/errors#validation_failed) | 422 | A field breaks a rule; `errors` names each one. With a live key, a `.test` site fails with `not_public_url`. | | [`image_unreachable`](https://submitator.com/docs/errors#image_unreachable) | 422 | The image URL did not return an image. Upload the file instead. | | [`quota_exceeded`](https://submitator.com/docs/errors#quota_exceeded) | 422 | Before your first purchase, test mode allows 25 projects and 100 new ones a day. | ## Next steps - [Launch and track](https://submitator.com/docs/guides/launch-and-track): spend 1 launch and follow each listing. - [Reach more directories](https://submitator.com/docs/guides/reach-more-directories): what the unlocks mean and how to get them. - [Install the badge](https://submitator.com/docs/guides/install-the-badge): the unlock most projects can get. --- # Launch and track URL: https://submitator.com/docs/guides/launch-and-track > Preview a launch, spend 1 launch on the directories a project qualifies for or on your own pick, and follow each listing until it is live. ## What you'll build A launched project, and the reads that tell you where each listing stands: which ones are live and where, which ones wait on you or your client, and which ones the directory turned down. Most listings go live within a week, and in test mode within about 15 minutes. ## Before you start - **A project that is ready.** Its `readiness.ready` is `true`: see [Onboard a client's product](https://submitator.com/docs/guides/onboard-a-clients-product). - **1 launch on your balance.** A live launch is one you bought; test mode starts with 100 test launches. A live launch cannot be undone. A launch that fails spends nothing. ## 1. Check your balance `GET /account` shows the launches you have, and how many listings run across all your projects. ```bash curl https://api.submitator.com/v1/account \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/account", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/account", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "account", "livemode": false, "state": "active", "launches": { "available": 97, "used": 3, "total": 100 }, "capacity": { "in_flight": 25, "limit": 100 } } ``` Up to `capacity.limit` listings run at once across your projects. Above it, new listings wait in `pending` and start as others finish; a launch is accepted either way. ## 2. Preview the launch `GET /projects/{project_id}/readiness` is free: it shows how many directories a launch would get now, their top and median Domain Rating, and what it costs. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "readiness", "ready": true, "directories": { "selected": 87, "limit": 110, "top_domain_rating": 92, "median_domain_rating": 48 }, "unlocks": [ { "requirement": "badge", "directories": 9, "how": "Install the badge on https://ledgerly.test and verify it." } ], "cost": { "launches": 1, "available": 97 } } ``` The numbers follow the catalog and can change from one hour to the next. Directories that `unlocks` names can be added after the launch too, so you do not need to wait for them. ### See which directories it takes `GET /projects/{project_id}/directories` shows the same launch one directory at a time: every directory of the catalog, highest Domain Rating first, with what it is to this project. `limit` is the most directories a launch takes, 110 for a draft. Before your first purchase it covers the top 20 directories only, and no article platform. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/directories \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/directories", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); const { limit, directories } = await res.json(); const suggested = directories.filter((row) => row.state === "suggested"); console.log(limit, suggested.map((row) => row.directory.name)); ``` ```python import os import requests choices = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/directories", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ).json() suggested = [row["directory"]["name"] for row in choices["directories"] if row["state"] == "suggested"] print(choices["limit"], suggested) ``` Response 200 (some fields left out): ```json { "object": "project_directories", "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "limit": 110, "directories": [ { "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73 }, "state": "suggested", "reason": null, "message": null, "listing": null }, { "directory": { "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "name": "SaaSHub", "kind": "directory", "domain_rating": 61 }, "state": "suggested", "reason": null, "message": null, "listing": null }, { "directory": { "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "name": "Uneed", "kind": "directory", "domain_rating": 58 }, "state": "locked", "reason": "badge", "message": "Uneed needs the badge on https://ledgerly.test first. Verify the badge, then include it.", "listing": null } ] } ``` Each directory shows the first `state` of this table that holds for it: | `state` | What it means | | --- | --- | | `listed` | The project has it already, and `listing` is the listing's id. | | `locked` | The project cannot take it, not even from `include`. `reason` says why, and `message` says it in words you can show. | | `excluded` | It is in the project's `excluded_directories`, so `"auto"` and auto-replace skip it. `include` still takes it. | | `suggested` | `"auto"` takes it now: the best directories the project qualifies for, up to `limit`. | | `open` | You can name it in `include`: a directory beyond `limit`, or an article platform, which only `include` takes. | `reason` is `badge`, `competitors`, `promo_code`, `contact_email`, `b2b_only`, `ai_only`, `directories_only`, `free_only`, `under_maintenance` or `other`, and new values can appear: show `message` for one you do not know. [Reach more directories](https://submitator.com/docs/guides/reach-more-directories) unlocks most of them. `under_maintenance` means the directory is temporarily turned off while we tune it, and no change to the project opens it until it is back. It is the `reason` unless a missing contact email, the directory's audience, its free-products rule (`free_only`) or a reason no project field changes (`other`) closes the directory first. Once it is back, a directory locked with `under_maintenance` opens on its own, unless the project lacks something the directory requires (`directory.requires`): `reason` then names that, or `other` when it lacks more than one. ## 3. Launch `"auto"` takes the `suggested` directories: the best ones the project qualifies for, up to 110, never one in `excluded_directories` and never an article platform. To choose yourself, send `{"include": [...]}` with the directories to use, as shown below, or `{"exclude": [...]}` with the ones to skip. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: crm_8812-launch" \ -H "Content-Type: application/json" \ -d '{"directories": "auto"}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Idempotency-Key": "crm_8812-launch", "Content-Type": "application/json", }, body: JSON.stringify({ directories: "auto" }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch", headers={ "Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}", "Idempotency-Key": "crm_8812-launch", }, json={"directories": "auto"}, ) print(res.json()) ``` Response 202 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "in_progress", "launched_at": "2026-10-03T14:05:40Z", "allowance": { "total": 110, "used": 0, "reserved": 87, "available": 23 }, "progress": { "total": 87, "pending": 87, "in_progress": 0, "action_required": 0, "submitted": 0, "live": 0, "not_accepted": 0, "cancelled": 0 } } ``` With the `Idempotency-Key`, a launch you send twice after a timeout runs once. A second launch of the same project, with another key, returns 409 `already_launched`. ### Launch your own pick `include` launches exactly the directories you name, `open` and `excluded` ones included, and it is the only way to an article platform. Send `excluded_directories` with it to replace the project's exclusions in the same request: list the suggested directories you leave out, and auto-replace never adds them later. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: crm_8812-launch" \ -H "Content-Type: application/json" \ -d '{"directories": {"include": ["dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN"]}, "excluded_directories": ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG"], "auto_replace": true}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Idempotency-Key": "crm_8812-launch", "Content-Type": "application/json", }, body: JSON.stringify({ directories: { include: ["dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN"] }, excluded_directories: ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG"], auto_replace: true, }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch", headers={ "Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}", "Idempotency-Key": "crm_8812-launch", }, json={ "directories": {"include": ["dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN"]}, "excluded_directories": ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG"], "auto_replace": True, }, ) print(res.json()) ``` Response 202 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "in_progress", "auto_replace": true, "excluded_directories": ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG"], "allowance": { "total": 110, "used": 0, "reserved": 2, "available": 108 }, "progress": { "total": 2, "pending": 2, "in_progress": 0, "action_required": 0, "submitted": 0, "live": 0, "not_accepted": 0, "cancelled": 0 } } ``` Here the launch takes BetaList and SaaSHub, and Uneed stays out even once the badge opens it. A launch with `include` turns `auto_replace` off unless it sends `"auto_replace": true`, as this one does: - **Off** keeps exactly your pick. A listing that ends `not_accepted` or `cancelled` gives its place back, and you pick the next directory, as [Reach more directories](https://submitator.com/docs/guides/reach-more-directories) shows. - **On** adds the best fitting directories up to the launch's `allowance.total` within a day, and another for each place a listing gives back: never one in `excluded_directories`, and never an article platform. If a directory you name cannot be used, the launch fails with 422 [`invalid_directories`](https://submitator.com/docs/errors#invalid_directories) and spends and changes nothing, the exclusions included. Each item of `errors` names one directory: its `param` is `directories.include[i]`, where `i` is its index in the list you sent, and its `message` says why. ## 4. Follow the project The project's `status` and `progress` sum up its listings. Read it, or follow the `project.*` events, to learn about changes. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); const project = await res.json(); console.log(project.status, project.progress, project.action); ``` ```python import os import requests project = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ).json() print(project["status"], project["progress"], project["action"]) ``` Response 200 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "action_required", "action": { "code": "install_badge", "waiting_on": "client", "client_message": "Please add the directory badges block to https://ledgerly.test. 9 directories list Ledgerly once their badges show on the site." }, "progress": { "total": 96, "pending": 0, "in_progress": 5, "action_required": 9, "submitted": 8, "live": 70, "not_accepted": 3, "cancelled": 1 } } ``` | `status` | What to do | | --- | --- | | `in_progress` | Nothing: listings are moving. | | `action_required` | Follow `action`: `waiting_on` says whether it is you or your client. | | `on_hold` | Nothing for `hold_reason` `review`, which clears by itself; write to support for `paused`. | | `completed` | Nothing is left to run. Listings in `submitted` can still go live. | ## 5. List the listings Each directory has one listing. Filter by `status` to see the live ones with their links, or the ones that need someone. ```bash curl "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings?status=live&limit=100" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js let cursor; const live = []; do { const url = new URL("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings"); url.search = new URLSearchParams({ status: "live", limit: "100", ...(cursor && { cursor }) }); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }); const page = await res.json(); live.push(...page.data); cursor = page.has_more ? page.next_cursor : undefined; } while (cursor); console.log(live.map((listing) => [listing.directory.name, listing.live_url])); ``` ```python import os import requests live, params = [], {"status": "live", "limit": 100} while True: page = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, params=params, ).json() live += page["data"] if not page["has_more"]: break params["cursor"] = page["next_cursor"] print([(listing["directory"]["name"], listing["live_url"]) for listing in live]) ``` One listing from the response: ```json { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "domain_rating": 73 }, "status": "live", "reason": null, "action": null, "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "live_at": "2026-10-08T14:00:00Z" } ``` A listing in `not_accepted` carries a `reason`: `declined`, `unavailable` or `removed`. Its place in the allowance comes back, and auto-replace or [Reach more directories](https://submitator.com/docs/guides/reach-more-directories) can use it. Where a directory needed an account, `GET /projects/{project_id}/logins` lists the login created there for your client: where it signs in, its email and username, whether it is ready, and the project's one password. For a confirmation code or a password reset link, `GET /listings/{listing_id}/emails` returns the emails the directory sent to the login, unless they go to your client's own address. See [Logins](https://submitator.com/docs/api/logins). ## 6. Act on what waits for someone A listing or project in `action_required` has an `action`. The two codes today: - **`install_badge`** waits on your client. Forward `client_message` as it is, then verify the badge: [Install the badge](https://submitator.com/docs/guides/install-the-badge). - **`add_assets`** waits on you. Add the missing logo or screenshot, and the listings move on. New codes can appear. For a code you do not know, show `client_message`, or a general prompt when it is `null`. ## Check it worked - `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP` shows a `launched_at` time and a `progress.total` above 0. - `GET /events?project=prj_4QzX1m9Lr2Vb7Nc8Tk3HwP` starts with `project.launched`. - `GET /account` shows 1 more launch in `launches.used`. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`not_ready`](https://submitator.com/docs/errors#not_ready) | 422 | The project misses a logo, a screenshot or the contact email; `errors` lists them. Nothing was spent. | | [`no_launches_left`](https://submitator.com/docs/errors#no_launches_left) | 402 | Your balance is 0. Buy launches in the console, then send the same request again. | | [`already_launched`](https://submitator.com/docs/errors#already_launched) | 409 | The project launched before. Add directories with `POST /projects/{project_id}/listings` instead. | | [`nothing_to_submit`](https://submitator.com/docs/errors#nothing_to_submit) | 422 | No directory fits the project now. Check `unlocks` and `not_matching` in the preview. Nothing was spent. | ## Next steps - [Keep your data in sync](https://submitator.com/docs/guides/keep-your-data-in-sync): follow every change without polling. - [Reports for clients](https://submitator.com/docs/guides/reports-for-clients): a PDF or XLSX under your agency's name. - [How it works](https://submitator.com/docs/how-it-works): every status, and the corrections that can follow. --- # Reach more directories URL: https://submitator.com/docs/guides/reach-more-directories > See what keeps a project from more directories, unlock them with the badge, competitors, a promo code and the audience marks, and fill the free allowance after launch with your own pick, article platforms included. ## What you'll build A project that reaches as many of its 110 directories as it can. Before the launch you raise the number the preview shows; after it, you add directories from the places in the allowance that free up. ## Before you start - **A project**, a draft or launched: see [Onboard a client's product](https://submitator.com/docs/guides/onboard-a-clients-product). - **What your client can offer**: the products theirs is an alternative to, a discount code, and the badge on their site. ## 1. Read what would unlock more The readiness preview lists the changes that would add directories, most directories first, and the directories that do not take this kind of product. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); const { unlocks, not_matching } = await res.json(); console.log(unlocks, not_matching); ``` ```python import os import requests readiness = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ).json() print(readiness["unlocks"], readiness["not_matching"]) ``` Response 200 (some fields left out): ```json { "object": "readiness", "directories": { "selected": 87, "limit": 110, "top_domain_rating": 92, "median_domain_rating": 48 }, "unlocks": [ { "requirement": "badge", "directories": 9, "how": "Install the badge on https://ledgerly.test and verify it." }, { "requirement": "competitors", "directories": 3, "how": "Add at least 1 competitor in competitors." }, { "requirement": "promo_code", "directories": 1, "how": "Add a promo code in promo_code." } ], "not_matching": { "b2b_only": 4, "ai_only": 7, "directories_only": 2, "other": 0 } } ``` `unlocks[].requirement` is an open list: show `how` for a value you do not know. `not_matching.other` counts directories that no field of the project changes. ## 2. Add competitors and a promo code Some directories list a product only next to its competitors, and some only with a discount for their readers. Both are fields of the project. ```bash curl -X PATCH https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"competitors": [{"name": "Bookwell", "url": "https://bookwell.test"}], "promo_code": "LEDGER30", "promo_description": "30% off the first 3 months"}' ``` ```js const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ competitors: [{ name: "Bookwell", url: "https://bookwell.test" }], promo_code: "LEDGER30", promo_description: "30% off the first 3 months", }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={ "competitors": [{"name": "Bookwell", "url": "https://bookwell.test"}], "promo_code": "LEDGER30", "promo_description": "30% off the first 3 months", }, ) print(res.json()) ``` A project takes up to 20 competitors, each a name of up to 100 characters and a URL of up to 500. Sending `competitors` replaces the whole list, so send every one each time. ## 3. Check the audience marks `audience` has 3 marks: `b2b` for a product that sells to businesses, `ai` for one built around AI, and `directory` for one that is itself a list of products. Each mark opens the directories that take only that kind of product, which `not_matching` counts. ```bash curl -X PATCH https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"audience": {"b2b": true, "ai": false, "directory": false}}' ``` ```js const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ audience: { b2b: true, ai: false, directory: false } }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={"audience": {"b2b": True, "ai": False, "directory": False}}, ) print(res.json()) ``` Set a mark only when it is true for the product: those directories review what they list. Send all 3 marks each time, since `audience` replaces the whole object. Some directories take only free products: `free_only` is `true` on them. Only a `pricing_model` of `free` opens them, and until then `not_matching.free_only` counts them. Set `pricing_model` to `free` only when the product is free. ## 4. Browse the catalog `GET /directories` is the catalog a launch picks from, highest Domain Rating first. Filter it by `kind`, `topic`, `min_dr`, `requires` or `audience`, or search names with `q`. ```bash curl "https://api.submitator.com/v1/directories?requires=none&min_dr=50&limit=50" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/directories?requires=none&min_dr=50&limit=50", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/directories", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, params={"requires": "none", "min_dr": 50, "limit": 50}, ) print(res.json()) ``` One directory from the response: ```json { "object": "directory", "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "url": "https://betalist.com", "domain_rating": 73, "monthly_organic_visits": 24000, "topic": "startups", "backlink": "dofollow", "backlink_condition": null, "requires": [], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false } ``` `outdated: true` marks a directory that lately seems to publish few new products. It is a sign, not a verdict, and it changes nothing a launch picks. `monthly_organic_visits` estimates the visits a month the directory's site gets from Google search, rounded: `100` means 100 or fewer, and `null` means no estimate above zero. Before your first purchase, test keys see the top 20 directories only, and no article platform. Use a directory's `id` in `include`, `exclude` and `excluded_directories`. ### Article platforms Dev.to, Medium and Hashnode are article platforms: the listing is a post about the product, in front of the platform's readers, and `kind` is `article` where a directory's is `directory`. A launch or an add takes an article platform only when you name it in `include`, since `"auto"`, `exclude` and auto-replace never take one. Find them with `kind=article`: ```bash curl "https://api.submitator.com/v1/directories?kind=article" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ## 5. Add directories after the launch The allowance counts what a launch covers: 110 places (100 on a project launched before 15 November 2026), `used` by listings that reached their directory and `reserved` by those on their way. A listing that ends `not_accepted` or `cancelled` gives its place back, and `POST /projects/{project_id}/listings` fills `available` places. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: crm_8812-add-1" \ -H "Content-Type: application/json" \ -d '{"directories": "auto"}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Idempotency-Key": "crm_8812-add-1", "Content-Type": "application/json", }, body: JSON.stringify({ directories: "auto" }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings", headers={ "Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}", "Idempotency-Key": "crm_8812-add-1", }, json={"directories": "auto"}, ) print(res.json()) ``` Response 202 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "in_progress", "allowance": { "total": 110, "used": 53, "reserved": 39, "available": 18 }, "progress": { "total": 96, "pending": 9, "in_progress": 30, "action_required": 0, "submitted": 31, "live": 22, "not_accepted": 3, "cancelled": 1 } } ``` On a launched project, the readiness preview counts what this call would add, and `GET /projects/{project_id}/directories` lists it: `limit` is the free allowance, and the `suggested` directories are what `"auto"` adds now. ### Add your own pick The list of choices tells you what you can name. After the add above, 8 places are free and none is `suggested`, since `"auto"` took every directory it could. BetaList and SaaSHub have listings, Uneed is `excluded`, and Dev.to is `open` as an article platform: Response 200 (some fields left out): ```json { "object": "project_directories", "limit": 8, "directories": [ { "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory" }, "state": "listed", "listing": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK" }, { "directory": { "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "name": "SaaSHub", "kind": "directory" }, "state": "listed", "listing": "lst_5Wq9Lm2Xr7Kt3Vb8Nz1HcD" }, { "directory": { "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "name": "Uneed", "kind": "directory" }, "state": "excluded", "listing": null }, { "directory": { "id": "dir_5Qc9Lm3Wx7Kt2Vb8Nr4HzD", "name": "Dev.to", "kind": "article" }, "state": "open", "listing": null } ] } ``` Send the directories you choose as `include`, up to `limit`, and the ones to keep out as `excluded_directories`. This add takes Uneed and a post on Dev.to, and since Uneed was the only directory kept out, it keeps none out from now on: ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: crm_8812-add-2" \ -H "Content-Type: application/json" \ -d '{"directories": {"include": ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "dir_5Qc9Lm3Wx7Kt2Vb8Nr4HzD"]}, "excluded_directories": []}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Idempotency-Key": "crm_8812-add-2", "Content-Type": "application/json", }, body: JSON.stringify({ directories: { include: ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "dir_5Qc9Lm3Wx7Kt2Vb8Nr4HzD"] }, excluded_directories: [], }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings", headers={ "Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}", "Idempotency-Key": "crm_8812-add-2", }, json={ "directories": {"include": ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "dir_5Qc9Lm3Wx7Kt2Vb8Nr4HzD"]}, "excluded_directories": [], }, ) print(res.json()) ``` Response 202 (some fields left out): ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "excluded_directories": [], "allowance": { "total": 110, "used": 53, "reserved": 41, "available": 16 }, "progress": { "total": 98, "pending": 11, "in_progress": 30, "action_required": 0, "submitted": 31, "live": 22, "not_accepted": 3, "cancelled": 1 } } ``` `excluded_directories` replaces the project's list together with the add, so an add that fails adds nothing and leaves the list as it was. It fails with 422 `allowance_exhausted` when you name more directories than `limit`, and with 422 `invalid_directories` when one cannot be used: `errors` names it by its index in your list, as `directories.include[i]`. A listing that ends `not_accepted` or `cancelled` gives its place back: `limit` grows by 1, and you pick the next directory the same way. With `auto_replace` on, we pick it for you. ## 6. Let auto-replace do it, or not `auto_replace` is on for new projects. Within a day it fills the free allowance with fitting directories for you: the rest of a launch that took fewer than its `allowance.total`, the place a listing gives back when it ends `not_accepted` or `cancelled`, and directories that join the catalog. Turning it on fills it right away, and so does the badge passing verification. Auto-replace never adds a directory in `excluded_directories`, nor an article platform. List a directory there to keep it out of `"auto"` launches and adds too, with `PATCH /projects/{project_id}` or in the launch or add itself; `include` still takes it. A launch with `include` turns `auto_replace` off unless the launch sends `"auto_replace": true`. ## Check it worked - `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness` shows a higher `directories.selected`, or fewer `unlocks`. - After the launch, `allowance.available` falls as directories are added, and `progress.total` grows. - Each addition sends a `project.listings_added` event with the count in `data.listings_added`. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`allowance_exhausted`](https://submitator.com/docs/errors#allowance_exhausted) | 422 | Listings use or reserve every place of the allowance, the project has not launched, or `include` names more directories than the free allowance. | | [`invalid_directories`](https://submitator.com/docs/errors#invalid_directories) | 422 | A directory you named is unknown, already has a listing, or is not open to the project yet; `errors` says which, by its index in `include`. | | [`nothing_to_submit`](https://submitator.com/docs/errors#nothing_to_submit) | 422 | No directory fits right now. Nothing was added. | | [`validation_failed`](https://submitator.com/docs/errors#validation_failed) | 422 | A field breaks a rule, such as a 21st competitor or an unknown id in `excluded_directories`. | ## Next steps - [Install the badge](https://submitator.com/docs/guides/install-the-badge): the unlock that often adds the most directories. - [Launch and track](https://submitator.com/docs/guides/launch-and-track): spend the launch and follow the listings. - [Directories](https://submitator.com/docs/api/directories): the catalog's filters in full. --- # Install the badge URL: https://submitator.com/docs/guides/install-the-badge > Some directories list a product only while their badge is on its site. Get the install kit, forward it to your client, check the install and verify it. ## What you'll build One block in the footer of your client's site that shows your agency's badge and every directory badge the project needs, under your brand. Once it is verified, the directories that ask for a badge open to the project. The block updates by itself, so your client installs it once. ## Before you start - **A project.** The badge can go up before or after the launch. - **Someone who can change the site**: your client's developer, or you. The last section of this page is a note to forward to them. ## 1. See what the badge unlocks Before the launch, the readiness preview counts the directories that wait for the badge. After it, those listings show `action_required` with `action.code` `install_badge`. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` unlocks from the response: ```json [{ "requirement": "badge", "directories": 9, "how": "Install the badge on https://ledgerly.test and verify it." }] ``` ## 2. Get the install kit `GET /projects/{project_id}/badge` returns the feed URLs, 6 ready snippets, a command that checks the install and a message to forward. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/badge \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/badge", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/badge", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200 (recipes cut to 1): ```json { "object": "badge", "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "not_checked", "checked_at": null, "feed": { "json_url": "https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.json", "html_url": "https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html" }, "recipes": [ { "platform": "html", "title": "Static site", "language": "shell", "code": "curl -fsS https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html -o partials/directory-badges.html" } ], "check_command": "curl -sL https://ledgerly.test | grep -c 'ref=91bb683b-04df-68e5-fea1-c01f13987d91'", "client_message": "Please add the directory badges block to the footer of https://ledgerly.test. Some directories list Ledgerly only while their badge shows on the site, and the block keeps those badges up to date by itself. Your developer can pick a ready snippet for Next.js, PHP, WordPress, nginx or a static site." } ``` The recipes cover `nextjs`, `php`, `wordpress`, `nginx_ssi`, `html` for a static site, and `ai_prompt`, a prompt for an AI coding tool. Each has a `title` for a tab and the project's feed URL already in its `code`. ## 3. Forward it to your client Send `client_message` as it is, with the recipe for your client's site and the note at the end of this page. The message names the product and nobody else, so it reads as yours. In test mode the feed URLs have the right shape but return 404, so a recipe renders nothing there. ## 4. Check the install Once the block is up, `check_command` prints how many badge links the site's home page shows, following redirects as our check does. ```bash curl -sL https://ledgerly.test | grep -c 'ref=91bb683b-04df-68e5-fea1-c01f13987d91' ``` `0` means the badges are not in the HTML the site serves. The usual cause is a block loaded in the browser with JavaScript, which the check does not run. ## 5. Verify it `POST /projects/{project_id}/badge/verify` reads the site now and looks for the badge. You can verify a project 10 times per hour. ```bash curl -X POST https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/badge/verify \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/badge/verify", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/badge/verify", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.status_code, res.json()) ``` Response 200 (some fields left out): ```json { "object": "badge", "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "installed", "checked_at": "2026-10-04T09:58:03Z" } ``` A badge that is not on the site returns 422 `badge_not_found`: run `check_command`, fix the install and verify again. ## 6. What happens next Once the badge is verified, the directories that need it open to the project. With `auto_replace` on, they are added from the free allowance by themselves, and the listings that waited in `action_required` move on. With it off, add them with `POST /projects/{project_id}/listings`. Keep the block on the site. Directories that list a product only while their badge shows can take the listing down when it goes. ## Check it worked - `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/badge` shows `status` `installed`. - The readiness preview no longer lists `badge` in `unlocks`. - Listings with `action.code` `install_badge` move to `in_progress`, and their `listing.in_progress` events arrive. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`badge_not_found`](https://submitator.com/docs/errors#badge_not_found) | 422 | The site does not show the badge. Run `check_command`, fix the install, verify again. In test mode, a host that starts with `nobadge.` never passes. | | [`rate_limited`](https://submitator.com/docs/errors#rate_limited) | 429 | More than 10 checks this hour for the project. Wait the seconds in `Retry-After`. | | [`not_found`](https://submitator.com/docs/errors#not_found) | 404 | The project id belongs to the other mode, or to no project. | ## A note for your client's developer Forward this section as it is. The badge block holds small badges, each an image link. Some directories keep a listing only while their badge shows on the site, and the block keeps the set current by itself: new badges appear without a change on your side. - **Put it in the footer of every page**, or at least of the home page. - **Render it on the server.** The badges must be in the HTML your server sends: a block loaded with client-side JavaScript is not seen. Every snippet does it this way. - **Never let it break the page.** Fetch the feed with a timeout of 3 seconds or less, and render nothing on an error or any status other than 200. The snippets do both. - **Keep the links as the feed sends them.** Each badge links to its directory, and the `ref=` in the links is how the install is checked. - **Cache it if you like.** A response can be cached for 60 seconds; the Next.js snippet refreshes every 5 minutes. To check the install, run the `check_command` you were sent: any number above `0` means the badges are live on the page. ## Next steps - [Reach more directories](https://submitator.com/docs/guides/reach-more-directories): the other unlocks. - [Launch and track](https://submitator.com/docs/guides/launch-and-track): follow the listings the badge opens. - [Badge](https://submitator.com/docs/api/badge): the install kit and its fields in full. --- # Receive webhooks URL: https://submitator.com/docs/guides/receive-webhooks > Add an HTTPS endpoint, check the signature of every delivery, answer within 10 seconds, and handle repeats and order. ## What you'll build An endpoint on your server that receives every change to your projects, listings and reports as it happens. It checks each delivery's signature, answers within 10 seconds, and acts on each event once, even when a delivery comes twice or out of order. ## Before you start - **A key.** Live and test keys have their own endpoints; build with a test key first. - **A public HTTPS URL** that reaches your server. Deliveries do not follow redirects, so use the final URL. - **Node 20 or later, or Python 3 with Flask,** for the example endpoints. ## 1. Add the endpoint Register the URL, and the events it should receive: types such as `listing.live`, groups such as `listing.*`, or `["*"]` for all. ```bash curl https://api.submitator.com/v1/webhook_endpoints \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://hooks.northlight.test/listings", "events": ["listing.*", "project.*"], "description": "Northlight CRM sync"}' ``` ```js const res = await fetch("https://api.submitator.com/v1/webhook_endpoints", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://hooks.northlight.test/listings", events: ["listing.*", "project.*"], description: "Northlight CRM sync", }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/webhook_endpoints", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={ "url": "https://hooks.northlight.test/listings", "events": ["listing.*", "project.*"], "description": "Northlight CRM sync", }, ) print(res.json()) ``` Response 201 (some fields left out): ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "description": "Northlight CRM sync", "events": ["listing.*", "project.*"], "enabled": true, "secret": "whsec_9laRgOMT0C3d8Je6FbArCUY0bGJM+r2emaNUGJCH+aw=", "created_at": "2026-10-06T12:00:04Z" } ``` The `secret` is shown in this response only: store it as `SUBMITATOR_WEBHOOK_SECRET`. The endpoint receives the events recorded after this moment, not the ones before. ## 2. Run the endpoint The endpoint reads the raw body, checks the signature with the official Standard Webhooks library, skips an event it has handled, and answers 204. A delivery that fails the check gets 400. verify-webhook.mjs: ```js import { Webhook } from "standardwebhooks"; // The whsec_ secret of your endpoint, shown once when you added it. const secret = process.env.SUBMITATOR_WEBHOOK_SECRET; // Returns the event when the delivery is ours. Throws a // WebhookVerificationError when the signature does not match or the // timestamp is more than 5 minutes from your clock. export function verifyWebhook(rawBody, headers, whsec = secret) { return new Webhook(whsec).verify(rawBody, headers); } import { createServer } from "node:http"; import { fileURLToPath } from "node:url"; // Event ids you have handled. Keep them in your database: a delivery can come // more than once, always with the same webhook-id. const handled = new Set(); export async function handleDelivery(request, response) { const chunks = []; for await (const chunk of request) chunks.push(chunk); const rawBody = Buffer.concat(chunks).toString("utf8"); let event; try { event = verifyWebhook(rawBody, request.headers); } catch { response.writeHead(400).end(); return; } // Answer within 10 seconds: queue slow work instead of doing it here. if (!handled.has(event.id)) { handled.add(event.id); console.log(event.type, event.data.object.id, "was", event.data.previous_status); } response.writeHead(204).end(); } // `node verify-webhook.mjs` receives deliveries on port 3000. if (process.argv[1] === fileURLToPath(import.meta.url)) { createServer(handleDelivery).listen(3000); } ``` app.py: ```python # pip install flask standardwebhooks import os from flask import Flask, request from standardwebhooks.webhooks import Webhook, WebhookVerificationError app = Flask(__name__) webhook = Webhook(os.environ["SUBMITATOR_WEBHOOK_SECRET"]) # Event ids you have handled. Keep them in your database: a delivery can # come more than once, always with the same webhook-id. handled = set() @app.post("/listings") def receive(): try: event = webhook.verify(request.get_data(), dict(request.headers)) except WebhookVerificationError: return "", 400 # Answer within 10 seconds: queue slow work instead of doing it here. if event["id"] not in handled: handled.add(event["id"]) print(event["type"], event["data"]["object"]["id"], "was", event["data"]["previous_status"]) return "", 204 ``` Keep the handled ids in your database, not in memory, so a restart does not handle an event twice. [Signatures](https://submitator.com/docs/webhooks/signatures) has the check in Ruby, PHP and Go. ## 3. Send a test event `POST /webhook_endpoints/{webhook_endpoint_id}/test` sends a `ping` event to the endpoint now, whatever its `events` filter. Your endpoint should log `ping`, the endpoint's id and `null`. ```bash curl -X POST https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/test \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/test", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/test", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 202: ```json { "object": "webhook_delivery", "id": "wd_0Tp4Kx9Wq2Lt7Vb3Rz8NmF", "livemode": false, "endpoint": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "event": "evt_7Aa2Kq8Wx3Lt9Vb5Rz1NdM", "event_type": "ping", "status": "pending", "attempts": 0, "next_attempt_at": "2026-10-06T12:01:15Z", "last_attempt": null, "created_at": "2026-10-06T12:01:15Z" } ``` ## 4. Check the delivery Each delivery records its attempts. Read them to see what your endpoint answered and how long it took. ```bash curl "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/deliveries?limit=1" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/deliveries?limit=1", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/deliveries", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, params={"limit": 1}, ) print(res.json()) ``` One delivery from the response: ```json { "object": "webhook_delivery", "id": "wd_0Tp4Kx9Wq2Lt7Vb3Rz8NmF", "event_type": "ping", "status": "succeeded", "attempts": 1, "last_attempt": { "attempted_at": "2026-10-06T12:01:15Z", "http_status": 204, "duration_ms": 182, "error": null } } ``` A `last_attempt.http_status` of 400 means your endpoint rejected the signature: check that it reads the raw body and the right secret. ## 5. Act on the events `type` says what happened and `data.object` holds the project, listing or report right after it. Deliveries can arrive out of order, so compare `data.previous_status` with the status you stored before you act. | When `type` is | A common action | | --- | --- | | `listing.live` | Store `data.object.live_url` and tell your client. | | `listing.action_required`, `project.action_required` | Forward `client_message` when `action.waiting_on` is `client`, or act when it is `agency`. | | `listing.not_accepted` | Show `data.object.reason`; its place in the allowance comes back. | | `report.ready` | Download the file before `data.object.expires_at`. | | A type you do not know | Answer 2xx and ignore it: new types can appear. | [Event types](https://submitator.com/docs/webhooks/event-types) lists all 15 and what each `data` holds. ## 6. Change what it receives `PATCH /webhook_endpoints/{webhook_endpoint_id}` changes the URL, the `events` list or the description, or disables the endpoint with `enabled` `false`. A new `events` list replaces the old one. ```bash curl -X PATCH https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"events": ["listing.live", "listing.not_accepted", "project.*"]}' ``` ## Check it worked - Your endpoint logged the `ping` with the endpoint's id. - `GET /webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT` shows `delivery_summary.last_http_status` `204`. - In test mode, a listing you move with `POST /test_helpers/listings/{listing_id}/advance` reaches your endpoint within about a minute. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`endpoint_url_invalid`](https://submitator.com/docs/errors#endpoint_url_invalid) | 422 | The URL is not a public `https` URL, or holds a user name or password. | | [`validation_failed`](https://submitator.com/docs/errors#validation_failed) | 422 | An `events` value is not a type or a group, such as `listing.published`. | | [`quota_exceeded`](https://submitator.com/docs/errors#quota_exceeded) | 422 | Before your first purchase, test mode allows 3 endpoints. Delete one first. | Deliveries that time out or get a status other than 2xx are tried again: [Retries and failures](https://submitator.com/docs/webhooks/retries-and-failures) has the schedule and the rule that disables an endpoint. ## Next steps - [Keep your data in sync](https://submitator.com/docs/guides/keep-your-data-in-sync): webhooks and the events feed together. - [Signatures](https://submitator.com/docs/webhooks/signatures): the check in other languages, and rolling the secret. - [Go-live checklist](https://submitator.com/docs/guides/go-live-checklist): your live endpoint before the first real launch. --- # Keep your data in sync URL: https://submitator.com/docs/guides/keep-your-data-in-sync > Mirror projects and listings in your own system with no gaps and no doubles, by reading the events feed from a cursor, letting webhooks say when, and retrying writes with Idempotency-Key. ## What you'll build A sync job that keeps your system's copy of each project and listing current. It reads every change in order from the events feed, so it misses nothing, and applies each event once. Webhooks tell it when to run, and writes it repeats after a timeout run once. ## Before you start - **Your own ids on the projects.** Set `external_id` to your CRM's id when you create a project, as [Onboard a client's product](https://submitator.com/docs/guides/onboard-a-clients-product) does. - **A place to store 1 cursor** per mode, and the ids of the events you applied. ## 1. Link your records to ours Store our ids, `prj_` and `lst_`, next to your records: they never change, and a listing keeps its id after a correction. To find a project from your side, ask by `external_id`. ```bash curl "https://api.submitator.com/v1/projects?external_id=crm_8812" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/projects?external_id=crm_8812", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); const { data } = await res.json(); console.log(data[0]?.id); ``` ```python import os import requests page = requests.get( "https://api.submitator.com/v1/projects", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, params={"external_id": "crm_8812"}, ).json() print(page["data"][0]["id"] if page["data"] else None) ``` `external_id` matches the whole value, case-sensitive, and is unique in each mode. `metadata` holds up to 20 more keys of your own and comes back on every read. ## 2. Read the feed from your cursor `GET /events` returns every change oldest first, and `next_cursor` is never `null`. Apply a page, store its `next_cursor`, and ask again with it until `has_more` is `false`; next time, start from the cursor you stored. ```bash curl "https://api.submitator.com/v1/events?cursor=cur_Ev7Kq2Wx9Lt3Nb5R&limit=100" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js // loadCursor, saveCursor and apply are yours: your database and your records. let cursor = await loadCursor(); for (;;) { const url = new URL("https://api.submitator.com/v1/events"); url.search = new URLSearchParams({ limit: "100", ...(cursor && { cursor }) }); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }); const page = await res.json(); for (const event of page.data) await apply(event); cursor = page.next_cursor; await saveCursor(cursor); if (!page.has_more) break; } ``` ```python import os import requests # load_cursor, save_cursor and apply are yours: your database and your records. cursor = load_cursor() while True: params = {"limit": 100, **({"cursor": cursor} if cursor else {})} page = requests.get( "https://api.submitator.com/v1/events", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, params=params, ).json() for event in page["data"]: apply(event) cursor = page["next_cursor"] save_cursor(cursor) if not page["has_more"]: break ``` Response 200 (one event shown): ```json { "object": "list", "data": [ { "object": "event", "id": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ", "type": "listing.live", "created_at": "2026-10-08T14:17:01Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "status": "live" }, "previous_status": "submitted" } } ], "has_more": false, "next_cursor": "cur_Ev7Kq2Wx9Lt3Nb5R" } ``` The feed has no gaps: a cursor returns every event recorded after it, in order. Without a cursor it starts at the oldest event it keeps, 90 days back. ## 3. Apply each event `data.object` is the whole object right after the change, so write it over your copy by its `id`. Skip an event whose `id` you have applied: after a crash between applying a page and storing its cursor, that page comes again. ```js async function apply(event) { if (await alreadyApplied(event.id)) return; const object = event.data.object; if (object.object === "listing") await saveListing(object.id, object.status, object.live_url); if (object.object === "project") await saveProject(object.id, object.status, object.progress); await markApplied(event.id); } ``` Statuses can move back. A live listing can become `not_accepted` or `submitted` again, and a `not_accepted` one can return: [How it works](https://submitator.com/docs/how-it-works#corrections) lists the corrections, and each comes as its own event. ## 4. Let webhooks say when A webhook tells you about a change within about a minute of it. The simplest way to use one: answer 2xx and run the feed reader from step 2. The cursor then keeps the order and fills any gap, and a delivery that comes twice changes nothing. To act on a delivery's body directly, compare its `data.previous_status` with what you stored, since deliveries can arrive out of order. [Receive webhooks](https://submitator.com/docs/guides/receive-webhooks) builds the endpoint. ## 5. Retry a write safely A `POST` that timed out may have run. Send each one with an `Idempotency-Key`, and send the same key when you retry: a repeat with the same key and body within 24 hours returns the first response, with `Idempotent-Replayed: true`, and changes nothing twice. ```bash curl https://api.submitator.com/v1/projects \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: crm_8812-create" \ -H "Content-Type: application/json" \ -d '{"url": "https://ledgerly.test", "contact_email": "founder@ledgerly.test", "external_id": "crm_8812"}' ``` ```js async function createProject(body, key) { for (let attempt = 1; ; attempt++) { const res = await fetch("https://api.submitator.com/v1/projects", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Idempotency-Key": key, "Content-Type": "application/json", }, body: JSON.stringify(body), }); if (res.status < 500 && res.status !== 409 && res.status !== 429) return res.json(); if (attempt === 5) throw new Error(`${res.status} after 5 attempts`); await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt)); } } ``` ```python import os import time import requests def create_project(body, key): for attempt in range(1, 6): res = requests.post( "https://api.submitator.com/v1/projects", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}", "Idempotency-Key": key}, json=body, ) if res.status_code < 500 and res.status_code not in (409, 429): return res.json() time.sleep(2 ** attempt) raise RuntimeError(f"{res.status_code} after 5 attempts") ``` The examples retry a 409 too, for `idempotency_key_in_use`; check `error.code` in your own code, since `project_exists` is a 409 as well. On a 429, wait the seconds in `Retry-After` instead of the backoff. ## 6. Recover after a long gap The feed keeps 90 days. A cursor older than that returns 410 `cursor_expired`: read the projects and listings you track again, then read the feed without a cursor and store the new one. ```bash curl "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings?limit=100" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ## Check it worked - For each project, your copy's counts by status equal `progress` on `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP`. - Your stored cursor moves forward after each run, and a run with nothing new reads 1 page with `has_more` `false`. - Running the job twice in a row changes nothing the second time. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor) | 400 | The cursor came from another list or was changed. Send `next_cursor` exactly as you received it. | | [`cursor_expired`](https://submitator.com/docs/errors#cursor_expired) | 410 | The cursor is older than 90 days. Read your objects again, then read the feed without a cursor. | | [`idempotency_key_in_use`](https://submitator.com/docs/errors#idempotency_key_in_use) | 409 | The first request with this key still runs. Retry in 1 second with the same key. | | [`idempotency_key_reused`](https://submitator.com/docs/errors#idempotency_key_reused) | 422 | The key came with another body before. Use a new key for each new request. | ## Next steps - [Receive webhooks](https://submitator.com/docs/guides/receive-webhooks): the endpoint that triggers the job. - [Event types](https://submitator.com/docs/webhooks/event-types): every event and what its `data` holds. - [Events](https://submitator.com/docs/api/events): the feed's parameters in full. --- # Reports for clients URL: https://submitator.com/docs/guides/reports-for-clients > Build a PDF or XLSX report of a project's listings under your agency's name, wait until it is ready, and download it within 7 days. ## What you'll build A report to forward to your client: every directory with its status, and the link once a listing is live, prepared under your agency's name. The PDF reads as a document; the XLSX has 1 row per listing for your own sheets. For a client portal of your own, the same data comes from the listings. ## Before you start - **A launched project.** A report lists its listings, so a draft has nothing to show. - **Somewhere to keep the file.** Reports are deleted 7 days after they are ready. ## 1. Build the report `POST /projects/{project_id}/reports` starts a report in `pdf` or `xlsx`. Each project can start 1 PDF every 30 seconds and 1 XLSX every 10 seconds. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/reports \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"format": "pdf"}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/reports", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ format: "pdf" }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/reports", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={"format": "pdf"}, ) print(res.json()) ``` Response 202: ```json { "object": "report", "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "pdf", "include_logins": false, "status": "building", "file_name": null, "created_at": "2026-10-08T15:02:10Z", "ready_at": null, "expires_at": null } ``` ## 2. Wait until it is ready The report moves from `building` to `ready`, or to `failed`. Wait for the `report.ready` webhook, or read the report every 3 seconds. ```bash curl https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js let report; do { await new Promise((resolve) => setTimeout(resolve, 3000)); const res = await fetch("https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); report = await res.json(); } while (report.status === "building"); console.log(report.status, report.file_name); ``` ```python import os import time import requests while True: time.sleep(3) report = requests.get( "https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ).json() if report["status"] != "building": break print(report["status"], report["file_name"]) ``` Response 200: ```json { "object": "report", "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "pdf", "include_logins": false, "status": "ready", "file_name": "ledgerly-listings-2026-10-08.pdf", "created_at": "2026-10-08T15:02:10Z", "ready_at": "2026-10-08T15:02:41Z", "expires_at": "2026-10-15T15:02:41Z" } ``` A `failed` report sends `report.failed`. Build a new one, and write to support with the event's id if it fails again. ## 3. Download the file `GET /reports/{report_id}/file` returns the file itself, with its name in `Content-Disposition`. Keep a copy: after `expires_at` the call returns 410 `gone`. ```bash curl https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP/file \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -o ledgerly-listings.pdf ``` ```js import fs from "node:fs/promises"; const res = await fetch("https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP/file", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); await fs.writeFile("ledgerly-listings.pdf", Buffer.from(await res.arrayBuffer())); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP/file", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) with open("ledgerly-listings.pdf", "wb") as file: file.write(res.content) ``` The report shows statuses with the labels the console uses: Pending, In progress, Needs you, Submitted, Live, Not accepted and Cancelled. In test mode the file is a sample marked TEST MODE. ## 4. Or build your own view For a page in your own portal, read the listings and show what you like. Each live listing has its `live_url`, and `proof_url` is a screenshot of it when there is one. ```bash curl "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings?status=live&limit=100" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` One listing from the response: ```json { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "domain_rating": 73 }, "status": "live", "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "live_at": "2026-10-08T14:00:00Z" } ``` The images in `proof_url` and the directory logos load from a neutral host with no brand on it, so they can go on your client's page as they are. A Domain Rating you show should credit Ahrefs, which measures it. ## 5. Include the logins Some directories need an account to list a product, and we create one there for your client. Send `include_logins: true` to hand those logins over with the report: the PDF gets a Directory logins page and the XLSX a Logins sheet, with each directory, where to sign in, the email, the username where the directory uses one, and whether the account is ready. Both show the project's one password, which every login uses. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/reports \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"format": "pdf", "include_logins": true}' ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/reports", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ format: "pdf", include_logins: true }), }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/reports", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={"format": "pdf", "include_logins": True}, ) print(res.json()) ``` Response 202 (some fields left out): ```json { "object": "report", "id": "rep_3Vx8Lm2Qt7Kn5Wb9Rz4HcJ", "format": "pdf", "include_logins": true, "status": "building" } ``` Wait for it and download it as in steps 2 and 3. The limits of step 1 count reports with logins separately, so a PDF with logins can start right after a PDF without. The file holds credentials, so only a key with full permissions and your team in the console can download it: a read-only key gets 403 `permission_denied`. The page of a [share link](https://submitator.com/docs/api/share-links) never offers it, even when it is the newest report, so send the file to your client yourself. Ask your client to keep the password unchanged while listings are in progress: every account signs in with it. For your own portal, [Logins](https://submitator.com/docs/api/logins) returns the same logins as JSON, and the emails each directory sent to its login, unless they go to your client's own address. ## Check it worked - `GET /reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP` shows `status` `ready` and an `expires_at` 7 days after `ready_at`. - The downloaded file opens, and its rows match `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings`. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`rate_limited`](https://submitator.com/docs/errors#rate_limited) | 429 | A report of the same format, with or without logins as this one, started less than 30 seconds (PDF) or 10 seconds (XLSX) ago. Wait the seconds in `Retry-After`. | | [`not_found`](https://submitator.com/docs/errors#not_found) | 404 | The report is still building, or the id is unknown in this mode. | | [`gone`](https://submitator.com/docs/errors#gone) | 410 | The file is older than 7 days and was deleted. Build a new report. | | [`validation_failed`](https://submitator.com/docs/errors#validation_failed) | 422 | `format` is not `pdf` or `xlsx`, or `include_logins` is not `true` or `false`. | ## Next steps - [Launch and track](https://submitator.com/docs/guides/launch-and-track): what the statuses in the report mean. - [Receive webhooks](https://submitator.com/docs/guides/receive-webhooks): get `report.ready` instead of polling. - [Reports](https://submitator.com/docs/api/reports): the operations in full. --- # Go-live checklist URL: https://submitator.com/docs/guides/go-live-checklist > Move an integration from test mode to live without surprises, from keys and endpoints to your clients' real sites and the first real launch. ## What you'll build The live version of an integration that works in test mode. Live data starts empty, keys and webhook endpoints are separate from test ones, and every live launch spends a launch you bought. This page walks through each change, then a first real launch to watch. ## Before you start - **An integration that works in test mode**, from creating a project to handling webhooks. - **Your first purchase.** Live keys come with it, and every launch on the live side uses 1 launch from your balance. ## 1. Create a live key In the console, open Developers and create a key on the LIVE tab. Store it in your secret manager, apart from the test key, and point your production config at it. ```bash curl https://api.submitator.com/v1/ping \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch("https://api.submitator.com/v1/ping", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/ping", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200: ```json { "object": "ping", "ok": true, "livemode": true, "account": { "name": "Northlight Studio", "state": "active" }, "key": { "id": "key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW", "permissions": "full" } } ``` - [ ] `livemode` is `true` and `state` is `active`. - [ ] Each server or job has its own key, so you can roll one without touching the others. - [ ] Anything that only reads, such as a dashboard, has a `read_only` key. A portal that shows your client their logins needs a key with full permissions. - [ ] No key is in a browser, an app or a repository. ## 2. Add your live webhook endpoint Webhook endpoints belong to a mode, so the endpoints you added with the test key receive no live events. Add the live one with the live key: it gets its own secret, and its URL must be public, since live mode rejects hosts on `.test` such as the one below. ```bash curl https://api.submitator.com/v1/webhook_endpoints \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://hooks.northlight.test/listings", "events": ["listing.*", "project.*", "report.*"]}' ``` ```js const res = await fetch("https://api.submitator.com/v1/webhook_endpoints", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://hooks.northlight.test/listings", events: ["listing.*", "project.*", "report.*"], }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/webhook_endpoints", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={ "url": "https://hooks.northlight.test/listings", "events": ["listing.*", "project.*", "report.*"], }, ) print(res.json()) ``` - [ ] The live endpoint's `secret` is stored, and your code checks live deliveries with it. - [ ] `POST /webhook_endpoints/{webhook_endpoint_id}/test` reaches the live endpoint and gets 2xx. - [ ] Your code skips an event whose id it has handled, and checks `livemode` before it writes. ## 3. Switch to your clients' real data Test projects stay in test mode: a live key gets 404 for their ids. Create each client's project again with the live key, from their real site. - [ ] Sites are public: live mode rejects `.test`, `.example`, `.invalid`, `.localhost` and IP addresses with `not_public_url`. - [ ] Each contact email is one your client reads, since some directories register the listing to it, and it cannot change after the launch. - [ ] `external_id` holds your CRM's id, so your records link to the live projects. - [ ] Tests that use `nobadge.` hosts or `/fail.png` images to force a failure run in test mode only. ## 4. Check the errors your code can get - [ ] Your code branches on `error.code`, never on `message`, and logs `request_id`. - [ ] Every `POST` you may send twice carries an `Idempotency-Key`, and a retry sends the same key. - [ ] 429 waits the seconds in `Retry-After`; 500 and 503 retry with backoff. - [ ] 402 `no_launches_left` stops your launches and tells you to buy more, instead of retrying. - [ ] A listing or project in `action_required` reaches a person: `client_message` goes to your client when `waiting_on` is `client`. [Error codes](https://submitator.com/docs/errors) says what each code means and how to fix it. ## 5. Launch one project and watch it Before the first real launch, preview it: the readiness call is free and shows what the launch would spend and get. ```bash curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); const { ready, directories, cost } = await res.json(); console.log(ready, directories.selected, cost); ``` ```python import os import requests readiness = requests.get( "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ).json() print(readiness["ready"], readiness["directories"]["selected"], readiness["cost"]) ``` - [ ] `ready` is `true`, and `cost.available` covers the launch. - [ ] After the launch, `project.launched` reaches your live endpoint. - [ ] Listings move from `pending` over the next days, and most go live within a week. ## Check it worked - `GET /ping` with the production key shows `livemode` `true`. - `GET /webhook_endpoints` with the same key lists your live endpoint, `enabled` and with a recent `delivery_summary.last_http_status` of 2xx. - Your system shows the first live project's listings, and their statuses match `progress` on the project. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`not_found`](https://submitator.com/docs/errors#not_found) | 404 | A test id sent with a live key. Create the project again in live mode. | | [`validation_failed`](https://submitator.com/docs/errors#validation_failed) | 422 | A test site, such as one on `.test`, fails with `not_public_url`. Use the client's real site. | | [`no_launches_left`](https://submitator.com/docs/errors#no_launches_left) | 402 | Your live balance is 0. Buy launches in the console. | | [`permission_denied`](https://submitator.com/docs/errors#permission_denied) | 403 | A read-only key tried to write, or to read logins. Use a key with full permissions there. | ## Next steps - [Authentication](https://submitator.com/docs/authentication): keys, permissions, rolling and revoking. - [Rate limits](https://submitator.com/docs/rate-limits): 3,600 requests per hour in each mode. - [Support](https://submitator.com/docs/support): what to send when something looks wrong. --- # Overview URL: https://submitator.com/docs/api > Every route of the v1 API on one screen, and the rules all of them share. The base URL is `https://api.submitator.com/v1`. Every route below takes your key in `Authorization: Bearer $SUBMITATOR_API_KEY`, except `GET /openapi.json`. ## Routes Each path links to its full reference: parameters, the request and its responses, and the errors it returns. **Basics** | Method | Path | What it does | | --- | --- | --- | | GET | `/ping` | Check your key | | GET | `/account` | Read your account | | GET | `/openapi.json` | Download this reference | **Projects** | Method | Path | What it does | | --- | --- | --- | | GET | `/projects` | List projects | | POST | `/projects` | Create a project | | GET | `/projects/{project_id}` | Read a project | | PATCH | `/projects/{project_id}` | Update a project | | DELETE | `/projects/{project_id}` | Delete a draft | | PUT | `/projects/{project_id}/logo` | Set the logo | | DELETE | `/projects/{project_id}/logo` | Remove the logo | | POST | `/projects/{project_id}/screenshots` | Add a screenshot | | DELETE | `/projects/{project_id}/screenshots/{image_id}` | Remove a screenshot | **Launch** | Method | Path | What it does | | --- | --- | --- | | GET | `/projects/{project_id}/readiness` | Preview a launch | | POST | `/projects/{project_id}/launch` | Launch a project | | GET | `/projects/{project_id}/listings` | List a project's listings | | POST | `/projects/{project_id}/listings` | Add directories | | GET | `/listings/{listing_id}` | Read a listing | **Badge** | Method | Path | What it does | | --- | --- | --- | | GET | `/projects/{project_id}/badge` | Get the badge install kit | | POST | `/projects/{project_id}/badge/verify` | Verify the badge | **Reports** | Method | Path | What it does | | --- | --- | --- | | POST | `/projects/{project_id}/reports` | Build a report | | GET | `/reports/{report_id}` | Read a report | | GET | `/reports/{report_id}/file` | Download a report file | **Events** | Method | Path | What it does | | --- | --- | --- | | GET | `/events` | List events | | GET | `/events/{event_id}` | Read an event | **Webhooks** | Method | Path | What it does | | --- | --- | --- | | GET | `/webhook_endpoints` | List webhook endpoints | | POST | `/webhook_endpoints` | Add a webhook endpoint | | GET | `/webhook_endpoints/{webhook_endpoint_id}` | Read a webhook endpoint | | PATCH | `/webhook_endpoints/{webhook_endpoint_id}` | Update a webhook endpoint | | DELETE | `/webhook_endpoints/{webhook_endpoint_id}` | Delete a webhook endpoint | | POST | `/webhook_endpoints/{webhook_endpoint_id}/rotate_secret` | Roll the signing secret | | POST | `/webhook_endpoints/{webhook_endpoint_id}/test` | Send a test event | | GET | `/webhook_endpoints/{webhook_endpoint_id}/deliveries` | List deliveries | | POST | `/webhook_deliveries/{webhook_delivery_id}/retry` | Retry a delivery | **Directories** | Method | Path | What it does | | --- | --- | --- | | GET | `/directories` | List directories | | GET | `/directories/{directory_id}` | Read a directory | | GET | `/projects/{project_id}/directories` | List a project's directory choices | **Test mode** | Method | Path | What it does | | --- | --- | --- | | POST | `/test_helpers/listings/{listing_id}/advance` | Move a test listing forward | | POST | `/test_helpers/account/launches` | Set your test launches | **Share links** | Method | Path | What it does | | --- | --- | --- | | GET | `/projects/{project_id}/share_link` | Read the share link | | POST | `/projects/{project_id}/share_link` | Create a share link | | DELETE | `/projects/{project_id}/share_link` | Turn the share link off | **Logins** | Method | Path | What it does | | --- | --- | --- | | GET | `/projects/{project_id}/logins` | List a project's logins | | GET | `/listings/{listing_id}/emails` | List the emails a login received | ## Requests Send JSON with `Content-Type: application/json`. Image uploads also take `multipart/form-data` with a `file` field; any other body type returns 415 `unsupported_media_type`. A parameter the operation does not list returns 400 `unknown_parameter` and changes nothing. An empty string counts as `null`. ## Objects and lists Every object names its type in `object` and its mode in `livemode`: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": true } ``` A list wraps its items in the same envelope every time: ```json { "object": "list", "data": [{ "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK" }], "has_more": true, "next_cursor": "cur_8Tq2Xn5Wb1Lz7Pd3" } ``` ## Ids An id is a type prefix and 22 letters and digits, such as `prj_4QzX1m9Lr2Vb7Nc8Tk3HwP`. Treat ids as opaque strings: compare them whole and store them as text. | Prefix | Object | | --- | --- | | `prj_` | Project | | `lst_` | Listing | | `dir_` | Directory | | `img_` | Image: a logo or a screenshot | | `rep_` | Report | | `evt_` | Event | | `we_` | Webhook endpoint | | `wd_` | Webhook delivery | | `key_` | API key, as `GET /ping` shows it | Keep your own reference in `external_id`: up to 100 characters, unique in your account, and searchable with `GET /projects?external_id=crm_8812`. `metadata` holds up to 20 more keys of your own. ## Pagination Lists return up to `limit` items: 1 to 100, and 20 when you leave it out. When `has_more` is `true`, send `next_cursor` back as `cursor` to read the next page: ```bash curl "https://api.submitator.com/v1/projects?limit=50&cursor=cur_8Tq2Xn5Wb1Lz7Pd3" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` Cursors are opaque and belong to the list that issued them: a cursor from another list returns 400 `invalid_cursor`. The events feed always returns a `next_cursor`, so you can poll it for what is new. ## Retry a POST safely Send an `Idempotency-Key` header, such as a UUID, with a `POST` you may send twice: creating a project, launching, adding directories, building a report or adding a webhook endpoint. A repeat with the same key and the same body within 24 hours returns the first response again, with `Idempotent-Replayed: true`, and changes nothing twice. ```bash curl https://api.submitator.com/v1/projects \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: 4f9d2c1e-ledgerly-create" \ -H "Content-Type: application/json" \ -d '{"url": "https://ledgerly.test", "contact_email": "founder@ledgerly.test"}' ``` The same key with another body returns 422 `idempotency_key_reused`. A repeat while the first request still runs returns 409 `idempotency_key_in_use`: wait 1 second and send it again. ## Test mode A `sbm_test_` key runs every route below on test data, where listings move on their own and nothing is spent. The routes under `/test_helpers` work only there and return 403 `test_mode_only` with a live key. [Test mode](https://submitator.com/docs/test-mode) says what is simulated. ## Rate limits Each account and mode can make 3,600 requests per UTC hour, or 600 before your first purchase. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, and [Rate limits](https://submitator.com/docs/rate-limits) lists the operations with limits of their own. ## Request ids Every response carries an `X-Request-Id` header, and error bodies repeat it as `error.request_id`. Log it with each call and quote it when you write to support. ## Time Times are ISO 8601 in UTC with a `Z`, such as `2026-10-08T14:00:00Z`. Listing times are rounded down to the hour, and an event's `created_at` is exact to the second. Dates without a time, such as `launch_date`, are `YYYY-MM-DD`. ## Errors Every 4xx and 5xx response has the same body, with a stable `code` to branch on: ```json { "error": { "code": "not_found", "message": "No project prj_4QzX1m9Lr2Vb7Nc8Tk3HwQ in live mode. Check the id and the key's mode.", "param": "project_id", "doc_url": "https://submitator.com/docs/errors#not_found", "request_id": "0133b7c4-6a56-4793-8ada-5f7c570eefa3" } } ``` [Error format](https://submitator.com/docs/error-format) explains each field, and [Error codes](https://submitator.com/docs/errors) lists every code. ## The OpenAPI document `GET /openapi.json` returns this reference as an OpenAPI 3.1 document with the released operations. It needs no key and can be cached for 1 hour: generate a client from it, or load it into your API tool. ```bash curl https://api.submitator.com/v1/openapi.json -o submitator-v1.json ``` --- # Basics URL: https://submitator.com/docs/api/basics > Check your key, read your account and download this reference. Check your key, read your account and download this reference. Every request needs `Authorization: Bearer `. The key's prefix decides the mode, and an id from one mode is never found in the other. Ids are a type prefix (`prj_`, `lst_`, `dir_`, `evt_`, `rep_`, `img_`, `we_`, `wd_`, `key_`) and 22 letters and digits: treat them as opaque strings. Times are ISO 8601 in UTC. Lists return `object`, `data`, `has_more` and `next_cursor`; send `next_cursor` back as `cursor` to read the next page. Send JSON with `Content-Type: application/json`; image uploads also accept `multipart/form-data`. A parameter the operation does not list returns 400 `unknown_parameter`, and an empty string counts as `null`. Each account and mode can make 3,600 requests per UTC hour, or 600 before your first purchase. Every response carries `X-Request-Id`, and a request your key authenticates also gets `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` for your account and mode. Errors share one envelope: branch on `error.code`, show `error.message`, and quote `error.request_id` when you contact support. ## Check your key `GET https://api.submitator.com/v1/ping` Returns the agency and the key behind the request, and whether the key is live or test. Call it first when you set up an integration: a 200 means the key works, in the mode `livemode` shows. Response 200: ```json { "object": "ping", "ok": true, "livemode": false, "account": { "name": "Northlight Studio", "state": "active" }, "key": { "id": "key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW", "permissions": "full" } } ``` Typical errors: [`api_key_missing`](https://submitator.com/docs/errors#api_key_missing), [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Read your account `GET https://api.submitator.com/v1/account` Shows how many launches you have left, how many listings are in progress across your projects, and your request budget for the current hour. Read it before a launch: with 0 launches available, a launch returns 402 `no_launches_left`. Response 200: ```json { "object": "account", "livemode": false, "name": "Northlight Studio", "state": "active", "launches": { "available": 97, "used": 3, "total": 100 }, "capacity": { "in_flight": 25, "limit": 100 }, "rate_limit": { "limit": 3600, "remaining": 3488, "resets_at": "2026-10-08T16:00:00Z" } } ``` Typical errors: [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Download this reference `GET https://api.submitator.com/v1/openapi.json` Returns this reference as an OpenAPI 3.1 document in JSON, with the operations that are released. It needs no key, answers cross-origin GET requests and can be cached for 1 hour. Generate a client from it, or load it into your API tool. Response 200: ```json { "openapi": "3.1.0", "info": { "title": "Submitator API", "version": "1.0.0" }, "servers": [ { "url": "https://api.submitator.com/v1" } ], "paths": { "/ping": { "get": { "operationId": "getPing", "summary": "Check your key" } } } } ``` Typical errors: [`route_not_found`](https://submitator.com/docs/errors#route_not_found), [`internal_error`](https://submitator.com/docs/errors#internal_error). --- # Projects URL: https://submitator.com/docs/api/projects > A project is one of your client's products. A project is one of your client's products. Create it from a URL and we fill in what the site tells us; then add a logo, 1 to 5 screenshots and a contact email. A draft costs nothing and you can delete it. Once launched, a project stays: it cannot be deleted, and its `contact_email` can no longer change. ## List projects `GET https://api.submitator.com/v1/projects` Returns your projects in the key's mode, newest first. Filter by `status`, find one by your own `external_id`, or search names and URLs with `q`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `status` | query | No | Only projects in this status. | | `external_id` | query | No | Only the project with this `external_id`. Matches the whole value, case-sensitive. | | `q` | query | No | Only projects whose name or URL contains this text, ignoring case. 2 to 100 characters. | | `cursor` | query | No | `next_cursor` from the previous page of the same list, as you received it. Leave it out for the first page. | | `limit` | query | No | How many items to return, 1 to 100. Defaults to 20. | Response 200: ```json { "object": "list", "data": [ { "object": "project", "id": "prj_1Nc7Vd3Kq8Zr5Tx2Wm9LbH", "livemode": false, "status": "in_progress", "hold_reason": null, "action": null, "url": "https://quotafy.test", "name": "Quotafy", "maker_name": "Tom Okafor", "contact_email": "sales@quotafy.test", "tagline": "Quotes your clients sign in one click", "short_description": "Quotafy turns a price list into quotes that clients accept and sign online, with reminders and a deposit link.", "long_description": null, "category": "saas", "pricing_model": "paid", "price_amount_cents": 2900, "price_period": "monthly", "launch_date": "2026-08-20", "twitter_url": "https://x.com/quotafy", "competitors": [ { "name": "Bidsheet", "url": "https://bidsheet.test" } ], "tags": [ "quotes", "proposals", "e-signature" ], "audience": { "b2b": true, "ai": false, "directory": false }, "promo_code": "QUOTE30", "promo_description": "30% off the first 3 months", "logo": { "object": "image", "id": "img_1Qa8Kx3Wm7Lt2Vb9Rz5NcE", "status": "ready", "url": "https://feed.example.net/a/Qf2Lm8Wx.k5Tp3", "error": null }, "screenshots": [ { "object": "image", "id": "img_4Qb2Kw9Lx5Mt8Vb3Rz7NdG", "status": "ready", "url": "https://feed.example.net/a/Qg9Nt4Vb.z7Kr2", "error": null } ], "autofill": { "status": "complete", "name_source": "input", "filled": [], "image_candidates": [] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 12, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [ "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG" ], "allowance": { "total": 110, "used": 72, "reserved": 20, "available": 18 }, "progress": { "total": 92, "pending": 0, "in_progress": 20, "action_required": 0, "submitted": 33, "live": 39, "not_accepted": 0, "cancelled": 0 }, "external_id": "crm_8907", "metadata": {}, "created_at": "2026-10-05T09:40:18Z", "updated_at": "2026-10-08T13:31:52Z", "launched_at": "2026-10-05T10:12:07Z" }, { "object": "project", "id": "prj_3Ac9Kx4Wq7Lt2Vb8Rz5NmD", "livemode": false, "status": "completed", "hold_reason": null, "action": null, "url": "https://acme.test", "name": "Acme CRM", "maker_name": "Lena Park", "contact_email": "hello@acme.test", "tagline": "The CRM for teams of five", "short_description": "Acme CRM keeps contacts, deals and follow-ups in one shared list, with a weekly digest for the whole team.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 900, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "crm", "sales" ], "audience": { "b2b": true, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_3Ad7Kx2Wq8Lt4Vb9Rz1NmH", "status": "ready", "url": "https://feed.example.net/a/Ac6Rk1Wn.p4Lx8", "error": null }, "screenshots": [ { "object": "image", "id": "img_0Ae5Kw1Lq9Xt3Vb7Rz2McJ", "status": "ready", "url": "https://feed.example.net/a/Ad3Mq7Zt.v9Kc1", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline" ], "image_candidates": [] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 51, "badge": { "status": "installed", "checked_at": "2026-10-03T15:08:30Z" }, "auto_replace": false, "excluded_directories": [], "allowance": { "total": 110, "used": 85, "reserved": 0, "available": 25 }, "progress": { "total": 88, "pending": 0, "in_progress": 0, "action_required": 0, "submitted": 3, "live": 82, "not_accepted": 2, "cancelled": 1 }, "external_id": "crm_8650", "metadata": {}, "created_at": "2026-10-03T15:01:44Z", "updated_at": "2026-10-07T18:22:47Z", "launched_at": "2026-10-03T15:12:09Z" } ], "has_more": true, "next_cursor": "cur_Pq7Lx2Wm9Kt4Vb8R" } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor). ## Create a project `POST https://api.submitator.com/v1/projects` Creates a draft for one of your client's products. Only `url` is required: we read the site and fill in the name, tagline and short description you leave out. Images given as `logo_url` and `screenshot_urls` import in the background, so they show `importing` first. A draft costs nothing. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `Idempotency-Key` | header | No | A unique string, such as a UUID, that makes a retry safe. A success is kept for 24 hours: a repeat with the same key and body returns it again with `Idempotent-Replayed: true`, and the same key with another body returns 422 `idempotency_key_reused`. A repeat while the first request runs returns 409 `idempotency_key_in_use`. An error changes nothing, so a repeat after one runs again. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `url` | string | Yes | Your client's site, `http` or `https`, up to 2,048 characters. Unique among your projects in the mode. Live mode accepts public addresses only: no IP addresses and no `.test`, `.example`, `.invalid` or `.localhost` hosts. | | `name` | string | No | The product's name as directories show it, 2 to 100 characters. Until you set one, it comes from the domain, and once autofill finishes, from the site's title. | | `maker_name` | string or null | No | The person directories list as the maker, up to 100 characters. | | `contact_email` | string or null | No | Required to launch. Some directories register the listing to this address and send their emails here. Unique among your projects in the mode, and fixed once the project launches. | | `tagline` | string or null | No | One line about the product, up to 100 characters. | | `short_description` | string or null | No | A short description, up to 500 characters. Most directories show this one. | | `long_description` | string or null | No | A longer description, up to 2,000 characters, for directories that take one. | | `category` | string or null | No | The product's category. We map it to each directory's own list of categories. | | `pricing_model` | string or null | No | How the product is sold. | | `price_amount_cents` | integer or null | No | The headline price in US cents, such as `1200` for $12. Leave it `null` for a free product. | | `price_period` | string or null | No | What `price_amount_cents` pays for. | | `launch_date` | string or null | No | The day the product went public, `YYYY-MM-DD`, for directories that ask for it. Not the day the project launched here: that is `launched_at`. | | `twitter_url` | string or null | No | The product's profile on X, as an `https://x.com/` or `https://twitter.com/` URL. | | `competitors` | array | No | Up to 20 products this one is an alternative to. Some directories list a product only next to its competitors. Sending a list replaces the whole list. | | `tags` | array | No | Up to 10 keywords of up to 40 characters each. Sending a list replaces the whole list. | | `audience` | object | No | Marks that open the directories which accept only some kinds of products. | | `promo_code` | string or null | No | A discount code for the product, up to 50 characters. Some directories list only products with one. | | `promo_description` | string or null | No | What `promo_code` gives, up to 500 characters, such as 30% off the first 3 months. | | `logo_url` | string | No | A public URL of the logo, imported in the background: PNG, JPEG, GIF or WebP, up to 5 MB. `logo.status` shows `importing` until it is done. | | `screenshot_urls` | array | No | 1 to 5 public URLs of screenshots, imported in the background in this order. Directories that take a single screenshot use the first. | | `external_id` | string or null | No | Your own id for the project, up to 100 characters, such as the client's id in your CRM. Unique among your projects in the mode; find a project by it with `GET /projects?external_id=`. | | `metadata` | object | No | Your own key-value data. We store it and return it, and use it for nothing else. | | `excluded_directories` | array | No | Directories never to use for this project unless you name them in `include`: `auto` launches, `auto` adds and auto-replace skip them. A launch or an add with `exclude` adds its list here. Sending a list replaces the whole list, here and in a launch or an add. | | `auto_replace` | boolean | No | New projects start with `true`. When `true`, we fill the free allowance with fitting directories for you within a day: the rest of a launch that took fewer than its `allowance.total`, the part a listing gives back when it ends `not_accepted` or `cancelled`, and directories that join the catalog. Turning it on and the badge passing verification fill it right away. It never adds a directory in `excluded_directories` or an article platform, and a launch with `include` turns it off unless the launch sends `auto_replace: true`. | Request: ```json { "url": "https://ledgerly.test", "contact_email": "founder@ledgerly.test", "external_id": "crm_8812", "logo_url": "https://ledgerly.test/press/logo.png", "screenshot_urls": [ "https://ledgerly.test/press/dashboard.png" ] } ``` Response 201: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "draft", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": null, "contact_email": "founder@ledgerly.test", "tagline": null, "short_description": null, "long_description": null, "category": null, "pricing_model": null, "price_amount_cents": null, "price_period": null, "launch_date": null, "twitter_url": null, "competitors": [], "tags": [], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": null, "status": "importing", "url": null, "error": null }, "screenshots": [ { "object": "image", "id": null, "status": "importing", "url": null, "error": null } ], "autofill": { "status": "running", "name_source": "domain", "filled": [], "image_candidates": [] }, "readiness": { "ready": false, "missing": [ "logo", "screenshots" ] }, "domain_rating": null, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": null, "progress": null, "external_id": "crm_8812", "metadata": {}, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T13:58:12Z", "launched_at": null } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`project_exists`](https://submitator.com/docs/errors#project_exists), [`quota_exceeded`](https://submitator.com/docs/errors#quota_exceeded), [`account_suspended`](https://submitator.com/docs/errors#account_suspended). ## Read a project `GET https://api.submitator.com/v1/projects/{project_id}` Returns the project with its status, readiness, allowance and listing counts. Poll it, or follow `project.*` events, to learn about changes. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "action_required", "hold_reason": null, "action": { "code": "install_badge", "waiting_on": "client", "client_message": "Please add the directory badges block to https://ledgerly.test. 9 directories list Ledgerly once their badges show on the site." }, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_found", "checked_at": "2026-10-08T09:12:44Z" }, "auto_replace": true, "excluded_directories": [], "allowance": { "total": 110, "used": 78, "reserved": 14, "available": 18 }, "progress": { "total": 96, "pending": 0, "in_progress": 5, "action_required": 9, "submitted": 8, "live": 70, "not_accepted": 3, "cancelled": 1 }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-08T14:17:01Z", "launched_at": "2026-10-03T14:05:40Z" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Update a project `PATCH https://api.submitator.com/v1/projects/{project_id}` Changes the fields you send and leaves the others as they are. Send `null` or an empty string to clear a field. After launch `contact_email` can no longer change; other edits apply to listings that have not reached their directory yet. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `url` | string | No | Your client's site, `http` or `https`, up to 2,048 characters. Unique among your projects in the mode. Live mode accepts public addresses only: no IP addresses and no `.test`, `.example`, `.invalid` or `.localhost` hosts. | | `name` | string | No | The product's name as directories show it, 2 to 100 characters. Until you set one, it comes from the domain, and once autofill finishes, from the site's title. | | `maker_name` | string or null | No | The person directories list as the maker, up to 100 characters. | | `contact_email` | string or null | No | Required to launch. Some directories register the listing to this address and send their emails here. Unique among your projects in the mode, and fixed once the project launches. | | `tagline` | string or null | No | One line about the product, up to 100 characters. | | `short_description` | string or null | No | A short description, up to 500 characters. Most directories show this one. | | `long_description` | string or null | No | A longer description, up to 2,000 characters, for directories that take one. | | `category` | string or null | No | The product's category. We map it to each directory's own list of categories. | | `pricing_model` | string or null | No | How the product is sold. | | `price_amount_cents` | integer or null | No | The headline price in US cents, such as `1200` for $12. Leave it `null` for a free product. | | `price_period` | string or null | No | What `price_amount_cents` pays for. | | `launch_date` | string or null | No | The day the product went public, `YYYY-MM-DD`, for directories that ask for it. Not the day the project launched here: that is `launched_at`. | | `twitter_url` | string or null | No | The product's profile on X, as an `https://x.com/` or `https://twitter.com/` URL. | | `competitors` | array | No | Up to 20 products this one is an alternative to. Some directories list a product only next to its competitors. Sending a list replaces the whole list. | | `tags` | array | No | Up to 10 keywords of up to 40 characters each. Sending a list replaces the whole list. | | `audience` | object | No | Marks that open the directories which accept only some kinds of products. | | `promo_code` | string or null | No | A discount code for the product, up to 50 characters. Some directories list only products with one. | | `promo_description` | string or null | No | What `promo_code` gives, up to 500 characters, such as 30% off the first 3 months. | | `external_id` | string or null | No | Your own id for the project, up to 100 characters, such as the client's id in your CRM. Unique among your projects in the mode; find a project by it with `GET /projects?external_id=`. | | `metadata` | object | No | Your own key-value data. We store it and return it, and use it for nothing else. | | `excluded_directories` | array | No | Directories never to use for this project unless you name them in `include`: `auto` launches, `auto` adds and auto-replace skip them. A launch or an add with `exclude` adds its list here. Sending a list replaces the whole list, here and in a launch or an add. | | `auto_replace` | boolean | No | New projects start with `true`. When `true`, we fill the free allowance with fitting directories for you within a day: the rest of a launch that took fewer than its `allowance.total`, the part a listing gives back when it ends `not_accepted` or `cancelled`, and directories that join the catalog. Turning it on and the badge passing verification fill it right away. It never adds a directory in `excluded_directories` or an article platform, and a launch with `include` turns it off unless the launch sends `auto_replace: true`. | Request: ```json { "maker_name": "Maya Chen", "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "tags": [ "accounting", "bookkeeping", "invoicing" ], "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" } } ``` Response 200: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "draft", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": null, "progress": null, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T14:02:31Z", "launched_at": null } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`project_exists`](https://submitator.com/docs/errors#project_exists), [`not_found`](https://submitator.com/docs/errors#not_found). ## Delete a draft `DELETE https://api.submitator.com/v1/projects/{project_id}` Deletes a project that has not launched, with its images. A launched project cannot be deleted: the call returns 409 `already_launched` and changes nothing. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "project", "id": "prj_5Ob2Kx8Wq3Lt7Vb9Rz1NmE", "livemode": false, "deleted": true } ``` Typical errors: [`already_launched`](https://submitator.com/docs/errors#already_launched), [`not_found`](https://submitator.com/docs/errors#not_found). ## Set the logo `PUT https://api.submitator.com/v1/projects/{project_id}/logo` Uploads the logo as `multipart/form-data` with a `file` field, or imports it from `url` in a JSON body. PNG, JPEG, GIF or WebP up to 5 MB; it replaces the current logo. Imports from a URL count toward a limit of 60 per hour. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `url` | string | Yes | A public URL that returns a PNG, JPEG, GIF or WebP image of up to 5 MB. You can import 60 images per hour. | Request: ```json { "url": "https://ledgerly.test/press/logo.png" } ``` Response 200: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "draft", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": null, "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": null, "pricing_model": null, "price_amount_cents": null, "price_period": null, "launch_date": null, "twitter_url": null, "competitors": [], "tags": [], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": null, "progress": null, "external_id": "crm_8812", "metadata": {}, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T14:01:20Z", "launched_at": null } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`image_unreachable`](https://submitator.com/docs/errors#image_unreachable), [`unsupported_media_type`](https://submitator.com/docs/errors#unsupported_media_type), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Remove the logo `DELETE https://api.submitator.com/v1/projects/{project_id}/logo` Removes the logo from a draft. A launched project must keep a logo: removing it returns 422 `validation_failed`, so replace it with `PUT` instead. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "draft", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": null, "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": null, "pricing_model": null, "price_amount_cents": null, "price_period": null, "launch_date": null, "twitter_url": null, "competitors": [], "tags": [], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": null, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": false, "missing": [ "logo" ] }, "domain_rating": 34, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": null, "progress": null, "external_id": "crm_8812", "metadata": {}, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T14:00:55Z", "launched_at": null } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`not_found`](https://submitator.com/docs/errors#not_found). ## Add a screenshot `POST https://api.submitator.com/v1/projects/{project_id}/screenshots` Adds one screenshot, uploaded as `file` or imported from `url`. A project holds 1 to 5 screenshots, and directories that take a single screenshot use the first one. The new screenshot is the last item of `screenshots` in the response. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `url` | string | Yes | A public URL that returns a PNG, JPEG, GIF or WebP image of up to 5 MB. You can import 60 images per hour. | Request: ```json { "url": "https://ledgerly.test/press/reports-page.png" } ``` Response 200: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "draft", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null }, { "object": "image", "id": "img_6Wn3Kq8Lx2Rt7Vb9Mz4HcB", "status": "ready", "url": "https://feed.example.net/a/Tz5Kq1Wm.n8Lr3", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": null, "progress": null, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T14:03:05Z", "launched_at": null } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`image_unreachable`](https://submitator.com/docs/errors#image_unreachable), [`unsupported_media_type`](https://submitator.com/docs/errors#unsupported_media_type). ## Remove a screenshot `DELETE https://api.submitator.com/v1/projects/{project_id}/screenshots/{image_id}` Removes one screenshot. A launched project keeps at least 1, so removing its last screenshot returns 422 `validation_failed`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | `image_id` | path | Yes | The screenshot's id, from `screenshots[].id` on the project. | Response 200: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "draft", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": null, "progress": null, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T14:03:40Z", "launched_at": null } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`not_found`](https://submitator.com/docs/errors#not_found). --- # Launch URL: https://submitator.com/docs/api/launch > Preview, pick, launch and follow the listings. Preview, pick, launch and follow the listings. `GET /projects/{project_id}/readiness` is free and shows what a launch would do, and `GET /projects/{project_id}/directories` what each directory is to the project; `POST /projects/{project_id}/launch` uses 1 launch and creates up to 110 listings, one per directory. A launch, and an add after it, takes `auto`, an `include` list or an `exclude` list, and `excluded_directories` to replace the project's exclusions in the same request. An article platform goes only by `include`; auto-replace never adds one, nor an excluded directory. A listing moves `pending` → `in_progress` → `submitted` → `live`, or ends `not_accepted` or `cancelled`. When it waits on you or your client it shows `action_required` with an `action` to take. Listing times are rounded down to the hour. ## Preview a launch `GET https://api.submitator.com/v1/projects/{project_id}/readiness` Shows for free what a launch would do now: whether the project is ready, how many directories it would get, and what would unlock more. On a launched project it previews what `POST /projects/{project_id}/listings` would add from the free allowance. The numbers follow the catalog and can change from one hour to the next. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "readiness", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "ready": true, "missing": [], "directories": { "selected": 87, "limit": 110, "top_domain_rating": 92, "median_domain_rating": 48 }, "unlocks": [ { "requirement": "badge", "directories": 9, "how": "Install the badge on https://ledgerly.test and verify it." }, { "requirement": "competitors", "directories": 3, "how": "Add at least 1 competitor in competitors." }, { "requirement": "promo_code", "directories": 1, "how": "Add a promo code in promo_code." } ], "not_matching": { "b2b_only": 4, "ai_only": 7, "directories_only": 2, "free_only": 0, "other": 0 }, "cost": { "launches": 1, "available": 100 } } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Launch a project `POST https://api.submitator.com/v1/projects/{project_id}/launch` Uses 1 launch and creates a listing in `pending` for each directory picked, up to 110: `"auto"` takes the best directories the project qualifies for, `include` names them (the only way to an article platform), `exclude` leaves some out, and `excluded_directories` replaces the project's exclusions in the same request. A failed call spends and changes nothing, and a second launch of the same project returns 409 `already_launched`. Listings beyond your capacity of 100 in progress wait in `pending` and start as others finish. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | `Idempotency-Key` | header | No | A unique string, such as a UUID, that makes a retry safe. A success is kept for 24 hours: a repeat with the same key and body returns it again with `Idempotent-Replayed: true`, and the same key with another body returns 422 `idempotency_key_reused`. A repeat while the first request runs returns 409 `idempotency_key_in_use`. An error changes nothing, so a repeat after one runs again. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `directories` | object | No | Which directories to launch with. Defaults to `auto`. | | `auto_replace` | boolean | No | Sets the project's `auto_replace`. Leave it out to keep the project's value, except that a launch with `include` sets it to `false`. With `true`, a launch of fewer than 110 directories grows: within a day we add the best fitting directories up to 110, never one in `excluded_directories` and never an article platform. | | `excluded_directories` | array | No | Replaces the project's `excluded_directories`, as `PATCH /projects/{project_id}` would, together with the launch: a launch that fails leaves the list as it was. The launch's own pick already leaves these out, unless `include` names them. Leave it out to keep the project's list. | Request: ```json { "directories": "auto" } ``` Response 202: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "in_progress", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": { "total": 110, "used": 0, "reserved": 87, "available": 23 }, "progress": { "total": 87, "pending": 87, "in_progress": 0, "action_required": 0, "submitted": 0, "live": 0, "not_accepted": 0, "cancelled": 0 }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T14:05:40Z", "launched_at": "2026-10-03T14:05:40Z" } ``` Typical errors: [`not_ready`](https://submitator.com/docs/errors#not_ready), [`no_launches_left`](https://submitator.com/docs/errors#no_launches_left), [`already_launched`](https://submitator.com/docs/errors#already_launched), [`nothing_to_submit`](https://submitator.com/docs/errors#nothing_to_submit). ## List a project's listings `GET https://api.submitator.com/v1/projects/{project_id}/listings` Returns one listing per directory, highest Domain Rating first. Filter by `status` or `directory`. Listing times are rounded down to the hour. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | `status` | query | No | Only listings in this status. | | `directory` | query | No | Only the listing at this directory. | | `cursor` | query | No | `next_cursor` from the previous page of the same list, as you received it. Leave it out for the first page. | | `limit` | query | No | How many items to return, 1 to 100. Defaults to 20. | Response 200: ```json { "object": "list", "data": [ { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "status": "live", "reason": null, "action": null, "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-04T09:00:00Z", "live_at": "2026-10-08T14:00:00Z" } ], "has_more": true, "next_cursor": "cur_8Tq2Xn5Wb1Lz7Pd3" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor). ## Add directories `POST https://api.submitator.com/v1/projects/{project_id}/listings` Adds directories to a launched project from its free allowance, the part that listings neither use nor reserve: `auto`, `include` (the only way to an article platform) or `exclude`, and `excluded_directories` to replace the project's exclusions in the same request. A directory that already has a listing on the project cannot be added again. With `auto_replace` on, this happens for you within a day whenever allowance frees up or a fitting directory joins the catalog, never with an excluded directory or an article platform. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | `Idempotency-Key` | header | No | A unique string, such as a UUID, that makes a retry safe. A success is kept for 24 hours: a repeat with the same key and body returns it again with `Idempotent-Replayed: true`, and the same key with another body returns 422 `idempotency_key_reused`. A repeat while the first request runs returns 409 `idempotency_key_in_use`. An error changes nothing, so a repeat after one runs again. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `directories` | object | No | Which directories to add, up to the free allowance. Defaults to `auto`. | | `excluded_directories` | array | No | Replaces the project's `excluded_directories`, as `PATCH /projects/{project_id}` would, together with the add: an add that fails leaves the list as it was. The add's own pick already leaves these out, unless `include` names them, and auto-replace never adds them afterwards. Leave it out to keep the project's list. | Request: ```json { "directories": "auto" } ``` Response 202: ```json { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "in_progress", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "installed", "checked_at": "2026-10-04T09:58:03Z" }, "auto_replace": true, "excluded_directories": [], "allowance": { "total": 110, "used": 53, "reserved": 39, "available": 18 }, "progress": { "total": 96, "pending": 9, "in_progress": 30, "action_required": 0, "submitted": 31, "live": 22, "not_accepted": 3, "cancelled": 1 }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-04T10:02:15Z", "launched_at": "2026-10-03T14:05:40Z" } ``` Typical errors: [`allowance_exhausted`](https://submitator.com/docs/errors#allowance_exhausted), [`nothing_to_submit`](https://submitator.com/docs/errors#nothing_to_submit), [`invalid_directories`](https://submitator.com/docs/errors#invalid_directories). ## Read a listing `GET https://api.submitator.com/v1/listings/{listing_id}` Returns one listing with its directory, its status and, once live, its URL. A listing keeps its id for the life of the project, including after a correction. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `listing_id` | path | Yes | The listing's id. | Response 200: ```json { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "status": "live", "reason": null, "action": null, "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-04T09:00:00Z", "live_at": "2026-10-08T14:00:00Z" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). --- # Badge URL: https://submitator.com/docs/api/badge > Some directories list a product only while their badge shows on the product's site. Some directories list a product only while their badge shows on the product's site. One feed serves every badge a project needs, under your agency's brand: your client installs it once and new badges appear by themselves. Get the install kit, forward `client_message` to your client, then verify. Until the badge is verified, those directories stay out of the launch and appear in `readiness.unlocks`. ## Get the badge install kit `GET https://api.submitator.com/v1/projects/{project_id}/badge` Returns what your client needs to show the badges on their site: the feed URLs, 6 ready snippets, a command to check the install and a message you can forward. The feed serves every badge the project needs under your agency's brand, so your client installs it once. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "badge", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "not_found", "checked_at": "2026-10-08T09:12:44Z", "feed": { "json_url": "https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.json", "html_url": "https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html" }, "recipes": [ { "platform": "nextjs", "title": "Next.js (App Router)", "language": "tsx", "code": "// app/directory-badges.tsx: render in your footer\nexport default async function DirectoryBadges() {\n try {\n const res = await fetch(\"https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.json\", {\n next: { revalidate: 300 },\n });\n if (!res.ok) return null;\n const { badges } = await res.json();\n return
;\n } catch {\n return null;\n }\n}" }, { "platform": "php", "title": "PHP", "language": "php", "code": " [\"timeout\" => 3]]);\n$badges = @file_get_contents(\"https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html\", false, $context);\nif ($badges !== false && strpos($http_response_header[0] ?? \"\", \" 200 \") !== false) {\n echo $badges;\n}" }, { "platform": "wordpress", "title": "WordPress", "language": "php", "code": "// functions.php: then add the [directory_badges] shortcode to your footer\nadd_shortcode(\"directory_badges\", function () {\n $response = wp_remote_get(\"https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html\", [\"timeout\" => 3]);\n if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {\n return \"\";\n }\n return wp_remote_retrieve_body($response);\n});" }, { "platform": "nginx_ssi", "title": "nginx with SSI", "language": "nginx", "code": "# In the server block of ledgerly.test\nlocation = /directory-badges {\n internal;\n proxy_pass https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html;\n proxy_ssl_server_name on;\n proxy_set_header Accept-Encoding \"\";\n}\n\n# In the location that serves your pages\nssi on;\n\n# In the page, where the badges should appear:\n# " }, { "platform": "html", "title": "Static site", "language": "shell", "code": "# Run before each deploy, then include the file in your footer\ncurl -fsS https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html -o partials/directory-badges.html" }, { "platform": "ai_prompt", "title": "Prompt for an AI coding tool", "language": "text", "code": "Add a server-rendered block to the footer of every page of my site. When the page is built or requested, fetch https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html with a 3 second timeout. If the response status is 200, insert the returned HTML as it is. On any other status or error, render nothing. Do not load it with client-side JavaScript: the badges must be in the HTML the server sends." } ], "check_command": "curl -sL https://ledgerly.test | grep -c 'ref=91bb683b-04df-68e5-fea1-c01f13987d91'", "client_message": "Please add the directory badges block to the footer of https://ledgerly.test. Some directories list Ledgerly only while their badge shows on the site, and the block keeps those badges up to date by itself. Your developer can pick a ready snippet for Next.js, PHP, WordPress, nginx or a static site." } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Verify the badge `POST https://api.submitator.com/v1/projects/{project_id}/badge/verify` Reads the project's site now and looks for the badge. Call it after your client installs the snippet: once it passes, directories that need the badge open to the project and auto-replace can add them. You can verify a project 10 times per hour. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "badge", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "status": "installed", "checked_at": "2026-10-04T09:58:03Z", "feed": { "json_url": "https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.json", "html_url": "https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html" }, "recipes": [ { "platform": "nextjs", "title": "Next.js (App Router)", "language": "tsx", "code": "// app/directory-badges.tsx: render in your footer\nexport default async function DirectoryBadges() {\n try {\n const res = await fetch(\"https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.json\", {\n next: { revalidate: 300 },\n });\n if (!res.ok) return null;\n const { badges } = await res.json();\n return
;\n } catch {\n return null;\n }\n}" }, { "platform": "php", "title": "PHP", "language": "php", "code": " [\"timeout\" => 3]]);\n$badges = @file_get_contents(\"https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html\", false, $context);\nif ($badges !== false && strpos($http_response_header[0] ?? \"\", \" 200 \") !== false) {\n echo $badges;\n}" }, { "platform": "wordpress", "title": "WordPress", "language": "php", "code": "// functions.php: then add the [directory_badges] shortcode to your footer\nadd_shortcode(\"directory_badges\", function () {\n $response = wp_remote_get(\"https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html\", [\"timeout\" => 3]);\n if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {\n return \"\";\n }\n return wp_remote_retrieve_body($response);\n});" }, { "platform": "nginx_ssi", "title": "nginx with SSI", "language": "nginx", "code": "# In the server block of ledgerly.test\nlocation = /directory-badges {\n internal;\n proxy_pass https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html;\n proxy_ssl_server_name on;\n proxy_set_header Accept-Encoding \"\";\n}\n\n# In the location that serves your pages\nssi on;\n\n# In the page, where the badges should appear:\n# " }, { "platform": "html", "title": "Static site", "language": "shell", "code": "# Run before each deploy, then include the file in your footer\ncurl -fsS https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html -o partials/directory-badges.html" }, { "platform": "ai_prompt", "title": "Prompt for an AI coding tool", "language": "text", "code": "Add a server-rendered block to the footer of every page of my site. When the page is built or requested, fetch https://feed.example.net/badge/91bb683b-04df-68e5-fea1-c01f13987d91.html with a 3 second timeout. If the response status is 200, insert the returned HTML as it is. On any other status or error, render nothing. Do not load it with client-side JavaScript: the badges must be in the HTML the server sends." } ], "check_command": "curl -sL https://ledgerly.test | grep -c 'ref=91bb683b-04df-68e5-fea1-c01f13987d91'", "client_message": "Please add the directory badges block to the footer of https://ledgerly.test. Some directories list Ledgerly only while their badge shows on the site, and the block keeps those badges up to date by itself. Your developer can pick a ready snippet for Next.js, PHP, WordPress, nginx or a static site." } ``` Typical errors: [`badge_not_found`](https://submitator.com/docs/errors#badge_not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). --- # Reports URL: https://submitator.com/docs/api/reports > PDF and XLSX reports of a project's listings, prepared under your agency's name. PDF and XLSX reports of a project's listings, prepared under your agency's name. Build one, wait until it is `ready`, and download it within 7 days. Send `include_logins: true` to add the directory logins and their password, for your client to take over the accounts. Such a report never appears on a share link's page, and only a key with full permissions downloads it. ## Build a report `POST https://api.submitator.com/v1/projects/{project_id}/reports` Starts building a PDF or XLSX report of the project's listings, prepared under your agency's name, with the directory logins when you send `include_logins: true`. Poll the report until `status` is `ready`, or wait for the `report.ready` event. Each project can start 1 PDF every 30 seconds and 1 XLSX every 10 seconds, and as many again with logins. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | `Idempotency-Key` | header | No | A unique string, such as a UUID, that makes a retry safe. A success is kept for 24 hours: a repeat with the same key and body returns it again with `Idempotent-Replayed: true`, and the same key with another body returns 422 `idempotency_key_reused`. A repeat while the first request runs returns 409 `idempotency_key_in_use`. An error changes nothing, so a repeat after one runs again. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `format` | string | Yes | `pdf` for a document to forward, `xlsx` for a spreadsheet with 1 row per listing. | | `include_logins` | boolean | No | `true` to add the directory logins and the password they share: a page in the PDF, a sheet in the XLSX. Such a report never appears on a share link's page, and only a key with full permissions downloads its file. Defaults to `false`. | Request: ```json { "format": "pdf" } ``` Response 202: ```json { "object": "report", "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "pdf", "include_logins": false, "status": "building", "file_name": null, "created_at": "2026-10-08T15:02:10Z", "ready_at": null, "expires_at": null } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`rate_limited`](https://submitator.com/docs/errors#rate_limited), [`not_found`](https://submitator.com/docs/errors#not_found). ## Read a report `GET https://api.submitator.com/v1/reports/{report_id}` Returns the report and its status. Once `status` is `ready`, download the file from `GET /reports/{report_id}/file` until `expires_at`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `report_id` | path | Yes | The report's id. | Response 200: ```json { "object": "report", "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "pdf", "include_logins": false, "status": "ready", "file_name": "ledgerly-listings-2026-10-08.pdf", "created_at": "2026-10-08T15:02:10Z", "ready_at": "2026-10-08T15:02:41Z", "expires_at": "2026-10-15T15:02:41Z" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Download a report file `GET https://api.submitator.com/v1/reports/{report_id}/file` Returns the PDF or XLSX file of a ready report. Files are kept for 7 days; after `expires_at` this returns 410 `gone`, and you build a new report. A file with logins is credentials: a read-only key gets 403 `permission_denied` for it. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `report_id` | path | Yes | The report's id. | Typical errors: [`gone`](https://submitator.com/docs/errors#gone), [`not_found`](https://submitator.com/docs/errors#not_found). --- # Events URL: https://submitator.com/docs/api/events > Every change to your projects, listings and reports, in order. Every change to your projects, listings and reports, in order. Events are kept for 90 days. Read the feed with a cursor to keep your records in sync, or receive the same events as webhooks. An event's `created_at` is exact to the second and shows when the change was recorded, within about a minute of the change itself. Listing times inside the event stay rounded down to the hour. The feed has no gaps: a cursor returns every event recorded after it, in order. Each change sends one event, and a launch sends `project.launched` once instead of one event per new listing. ## List events `GET https://api.submitator.com/v1/events` Returns every change to your projects, listings and reports, oldest first. Store `next_cursor` and send it back as `cursor` to read only what is new; it is never `null` here. Filter by `type` or `project`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `cursor` | query | No | `next_cursor` from your last call. Leave it out to start at the oldest event kept (90 days). A cursor older than that returns 410 `cursor_expired`. | | `type` | query | No | Only events of this type. Use a type such as `listing.live`, or a group such as `listing.*`, `project.*` or `report.*`. | | `project` | query | No | Only events about this project. | | `limit` | query | No | How many items to return, 1 to 100. Defaults to 20. | Response 200: ```json { "object": "list", "data": [ { "object": "event", "id": "evt_6Lr3Kx8Wq2Nt7Vb1Rz5MpA", "type": "listing.action_required", "created_at": "2026-10-08T09:13:30Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_2Tz6Kp9Wm3Qx8Lr5Vb1NcJ", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "name": "Uneed", "kind": "directory", "domain_rating": 58, "logo_url": "https://feed.example.net/a/u7Nd3Kc.w5Rb" }, "status": "action_required", "reason": null, "action": { "code": "install_badge", "waiting_on": "client", "client_message": "Please add the directory badges block to https://ledgerly.test. Uneed lists Ledgerly once its badge shows on the site." }, "live_url": null, "proof_url": null, "created_at": "2026-10-04T10:00:00Z", "submitted_at": null, "live_at": null }, "previous_status": "in_progress" } }, { "object": "event", "id": "evt_6Mz4Kq9Wr3Lt8Vb2Nx6HcE", "type": "project.action_required", "created_at": "2026-10-08T09:13:30Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "action_required", "hold_reason": null, "action": { "code": "install_badge", "waiting_on": "client", "client_message": "Please add the directory badges block to https://ledgerly.test. 9 directories list Ledgerly once their badges show on the site." }, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_found", "checked_at": "2026-10-08T09:12:44Z" }, "auto_replace": true, "excluded_directories": [], "allowance": { "total": 110, "used": 78, "reserved": 14, "available": 18 }, "progress": { "total": 96, "pending": 0, "in_progress": 5, "action_required": 9, "submitted": 9, "live": 69, "not_accepted": 3, "cancelled": 1 }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-08T09:13:30Z", "launched_at": "2026-10-03T14:05:40Z" }, "previous_status": "in_progress" } }, { "object": "event", "id": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ", "type": "listing.live", "created_at": "2026-10-08T14:17:01Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "status": "live", "reason": null, "action": null, "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-04T09:00:00Z", "live_at": "2026-10-08T14:00:00Z" }, "previous_status": "submitted" } } ], "has_more": false, "next_cursor": "cur_Ev7Kq2Wx9Lt3Nb5R" } ``` Typical errors: [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor), [`cursor_expired`](https://submitator.com/docs/errors#cursor_expired), [`validation_failed`](https://submitator.com/docs/errors#validation_failed). ## Read an event `GET https://api.submitator.com/v1/events/{event_id}` Returns one event from the last 90 days. A webhook delivery's `webhook-id` header is the event id, so you can fetch the event to confirm a delivery came from us. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `event_id` | path | Yes | The event's id, which is also the `webhook-id` header of its deliveries. | Response 200: ```json { "object": "event", "id": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ", "type": "listing.live", "created_at": "2026-10-08T14:17:01Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "status": "live", "reason": null, "action": null, "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-04T09:00:00Z", "live_at": "2026-10-08T14:00:00Z" }, "previous_status": "submitted" } } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). --- # Webhooks URL: https://submitator.com/docs/api/webhooks > Events pushed to your HTTPS endpoint as they happen. Events pushed to your HTTPS endpoint as they happen. Each delivery is a POST with the event as JSON, signed as Standard Webhooks describes: verify it with an official Standard Webhooks library and your `whsec_` secret. Answer with any 2xx within 10 seconds (5 seconds to connect); redirects are not followed. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, then marked `failed`. An endpoint with no successful delivery for 72 hours and at least 10 failed events is disabled and you get an email; `PATCH` it with `enabled: true` to turn it back on. Deliveries can arrive out of order. Compare `data.previous_status`, or read the object again, before you act on an older event. ## List webhook endpoints `GET https://api.submitator.com/v1/webhook_endpoints` Returns your webhook endpoints in the key's mode, newest first. Secrets are not included. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `cursor` | query | No | `next_cursor` from the previous page of the same list, as you received it. Leave it out for the first page. | | `limit` | query | No | How many items to return, 1 to 100. Defaults to 20. | Response 200: ```json { "object": "list", "data": [ { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "description": "Northlight CRM sync", "events": [ "listing.*", "project.*" ], "enabled": true, "disabled_reason": null, "secret": null, "previous_secret_expires_at": null, "delivery_summary": { "last_attempted_at": "2026-10-08T14:17:02Z", "last_http_status": 200, "attempted_7d": 148, "succeeded_7d": 147 }, "created_at": "2026-10-06T12:00:04Z", "updated_at": "2026-10-06T12:00:04Z" } ], "has_more": false, "next_cursor": null } ``` Typical errors: [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Add a webhook endpoint `POST https://api.submitator.com/v1/webhook_endpoints` Registers an HTTPS URL that receives events. The response holds the signing `secret`, shown this once only. A new endpoint receives events created after it, not the ones before. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `Idempotency-Key` | header | No | A unique string, such as a UUID, that makes a retry safe. A success is kept for 24 hours: a repeat with the same key and body returns it again with `Idempotent-Replayed: true`, and the same key with another body returns 422 `idempotency_key_reused`. A repeat while the first request runs returns 409 `idempotency_key_in_use`. An error changes nothing, so a repeat after one runs again. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `url` | string | Yes | A public `https` URL without a user name or password, up to 2,048 characters. Deliveries do not follow redirects, so use the final URL. | | `events` | array | No | The event types to receive, or groups such as `listing.*`. Defaults to `["*"]`, every type. | | `description` | string or null | No | Your note about the endpoint, up to 200 characters. | | `enabled` | boolean | No | Defaults to `true`. Set `false` to create it turned off. | Request: ```json { "url": "https://hooks.northlight.test/listings", "events": [ "listing.*", "project.*" ], "description": "Northlight CRM sync" } ``` Response 201: ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "description": "Northlight CRM sync", "events": [ "listing.*", "project.*" ], "enabled": true, "disabled_reason": null, "secret": "whsec_9laRgOMT0C3d8Je6FbArCUY0bGJM+r2emaNUGJCH+aw=", "previous_secret_expires_at": null, "delivery_summary": { "last_attempted_at": null, "last_http_status": null, "attempted_7d": 0, "succeeded_7d": 0 }, "created_at": "2026-10-06T12:00:04Z", "updated_at": "2026-10-06T12:00:04Z" } ``` Typical errors: [`endpoint_url_invalid`](https://submitator.com/docs/errors#endpoint_url_invalid), [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`quota_exceeded`](https://submitator.com/docs/errors#quota_exceeded). ## Read a webhook endpoint `GET https://api.submitator.com/v1/webhook_endpoints/{webhook_endpoint_id}` Returns one endpoint with a summary of its deliveries in the last 7 days. The secret is not included. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `webhook_endpoint_id` | path | Yes | The webhook endpoint's id. | Response 200: ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "description": "Northlight CRM sync", "events": [ "listing.*", "project.*" ], "enabled": true, "disabled_reason": null, "secret": null, "previous_secret_expires_at": null, "delivery_summary": { "last_attempted_at": "2026-10-08T14:17:02Z", "last_http_status": 200, "attempted_7d": 148, "succeeded_7d": 147 }, "created_at": "2026-10-06T12:00:04Z", "updated_at": "2026-10-06T12:00:04Z" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Update a webhook endpoint `PATCH https://api.submitator.com/v1/webhook_endpoints/{webhook_endpoint_id}` Changes the URL, the event filter or the description, or turns the endpoint off and on. Setting `enabled` to `true` also turns on an endpoint that was disabled after failed deliveries. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `webhook_endpoint_id` | path | Yes | The webhook endpoint's id. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `url` | string | No | A public `https` URL without a user name or password, up to 2,048 characters. | | `events` | array | No | The event types to receive, or groups such as `listing.*`. Replaces the whole list. | | `description` | string or null | No | Your note about the endpoint, up to 200 characters. | | `enabled` | boolean | No | `false` turns it off, `true` turns it on again, including after it was disabled for failing. | Request: ```json { "events": [ "listing.live", "listing.not_accepted", "project.*" ] } ``` Response 200: ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "description": "Northlight CRM sync", "events": [ "listing.live", "listing.not_accepted", "project.*" ], "enabled": true, "disabled_reason": null, "secret": null, "previous_secret_expires_at": null, "delivery_summary": { "last_attempted_at": "2026-10-08T14:17:02Z", "last_http_status": 200, "attempted_7d": 148, "succeeded_7d": 147 }, "created_at": "2026-10-06T12:00:04Z", "updated_at": "2026-10-08T15:25:40Z" } ``` Typical errors: [`endpoint_url_invalid`](https://submitator.com/docs/errors#endpoint_url_invalid), [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`not_found`](https://submitator.com/docs/errors#not_found). ## Delete a webhook endpoint `DELETE https://api.submitator.com/v1/webhook_endpoints/{webhook_endpoint_id}` Deletes the endpoint at once. Deliveries still waiting for it are dropped; the events stay in `GET /events`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `webhook_endpoint_id` | path | Yes | The webhook endpoint's id. | Response 200: ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "deleted": true } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`permission_denied`](https://submitator.com/docs/errors#permission_denied). ## Roll the signing secret `POST https://api.submitator.com/v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret` Issues a new signing secret, shown in this response only. For the next 24 hours each delivery carries 2 signatures, one per secret, so you can switch your code without missing an event. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `webhook_endpoint_id` | path | Yes | The webhook endpoint's id. | Response 200: ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "description": "Northlight CRM sync", "events": [ "listing.*", "project.*" ], "enabled": true, "disabled_reason": null, "secret": "whsec_BFXycpAAK/Ay+ue0CxyVr5JQrZILyVqHTkjpX3GtfmY=", "previous_secret_expires_at": "2026-10-09T15:30:00Z", "delivery_summary": { "last_attempted_at": "2026-10-08T14:17:02Z", "last_http_status": 200, "attempted_7d": 148, "succeeded_7d": 147 }, "created_at": "2026-10-06T12:00:04Z", "updated_at": "2026-10-08T15:30:00Z" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`permission_denied`](https://submitator.com/docs/errors#permission_denied). ## Send a test event `POST https://api.submitator.com/v1/webhook_endpoints/{webhook_endpoint_id}/test` Sends a `ping` event to the endpoint now, whatever its `events` filter and even when it is disabled. Use it to check your signature code; the delivery shows up in the endpoint's deliveries. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `webhook_endpoint_id` | path | Yes | The webhook endpoint's id. | Response 202: ```json { "object": "webhook_delivery", "id": "wd_0Tp4Kx9Wq2Lt7Vb3Rz8NmF", "livemode": false, "endpoint": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "event": "evt_7Aa2Kq8Wx3Lt9Vb5Rz1NdM", "event_type": "ping", "status": "pending", "attempts": 0, "next_attempt_at": "2026-10-06T12:01:15Z", "last_attempt": null, "created_at": "2026-10-06T12:01:15Z" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## List deliveries `GET https://api.submitator.com/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries` Returns the deliveries to one endpoint, newest first, with the outcome of the last attempt. Filter by `status` to find the ones that are still retrying or have failed. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `webhook_endpoint_id` | path | Yes | The webhook endpoint's id. | | `status` | query | No | Only deliveries in this status. | | `cursor` | query | No | `next_cursor` from the previous page of the same list, as you received it. Leave it out for the first page. | | `limit` | query | No | How many items to return, 1 to 100. Defaults to 20. | Response 200: ```json { "object": "list", "data": [ { "object": "webhook_delivery", "id": "wd_1Bq7Xm3Kt9Lw5Rv2Nz8HdC", "livemode": false, "endpoint": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "event": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ", "event_type": "listing.live", "status": "succeeded", "attempts": 1, "next_attempt_at": null, "last_attempt": { "attempted_at": "2026-10-08T14:17:02Z", "http_status": 200, "duration_ms": 182, "error": null }, "created_at": "2026-10-08T14:17:01Z" }, { "object": "webhook_delivery", "id": "wd_3Cr8Kx2Wq7Lt4Vb9Nz1HmP", "livemode": false, "endpoint": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "event": "evt_6Lr3Kx8Wq2Nt7Vb1Rz5MpA", "event_type": "listing.action_required", "status": "pending", "attempts": 5, "next_attempt_at": "2026-10-08T17:49:31Z", "last_attempt": { "attempted_at": "2026-10-08T11:49:31Z", "http_status": null, "duration_ms": 10000, "error": "timeout" }, "created_at": "2026-10-08T09:13:30Z" } ], "has_more": true, "next_cursor": "cur_Dl5Kx2Wq8Lt3Vb7N" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor). ## Retry a delivery `POST https://api.submitator.com/v1/webhook_deliveries/{webhook_delivery_id}/retry` Sends a delivery again now, whatever its status, and resets nothing else. The endpoint must be enabled: a disabled endpoint returns 422 `validation_failed`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `webhook_delivery_id` | path | Yes | The delivery's id. | Response 202: ```json { "object": "webhook_delivery", "id": "wd_3Cr8Kx2Wq7Lt4Vb9Nz1HmP", "livemode": false, "endpoint": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "event": "evt_6Lr3Kx8Wq2Nt7Vb1Rz5MpA", "event_type": "listing.action_required", "status": "pending", "attempts": 5, "next_attempt_at": "2026-10-08T15:31:10Z", "last_attempt": { "attempted_at": "2026-10-08T11:49:31Z", "http_status": null, "duration_ms": 10000, "error": "timeout" }, "created_at": "2026-10-08T09:13:30Z" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`validation_failed`](https://submitator.com/docs/errors#validation_failed). ## A project launched The `project.launched` event, sent as a POST to your endpoint. Sent once when a project launches; the new listings send no events of their own. `data.listings_created` counts them, all in `pending`, and `data.previous_status` is `draft`. Body: ```json { "object": "event", "id": "evt_3Km7Qx2Wr9Lt5Vb8Nz1HcP", "type": "project.launched", "created_at": "2026-10-03T14:05:41Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "in_progress", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [], "allowance": { "total": 110, "used": 0, "reserved": 87, "available": 23 }, "progress": { "total": 87, "pending": 87, "in_progress": 0, "action_required": 0, "submitted": 0, "live": 0, "not_accepted": 0, "cancelled": 0 }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-03T14:05:40Z", "launched_at": "2026-10-03T14:05:40Z" }, "previous_status": "draft", "listings_created": 87 } } ``` ## Directories were added The `project.listings_added` event, sent as a POST to your endpoint. Sent when directories are added to a launched project, by `POST /projects/{project_id}/listings` or by auto-replace. `data.listings_added` counts the new listings, all in `pending`. The project's status does not change, so `data.previous_status` is `null`. Body: ```json { "object": "event", "id": "evt_4Ns2Kw9Lq5Xt8Vb3Rz7MdF", "type": "project.listings_added", "created_at": "2026-10-04T10:02:15Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "in_progress", "hold_reason": null, "action": null, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "installed", "checked_at": "2026-10-04T09:58:03Z" }, "auto_replace": true, "excluded_directories": [], "allowance": { "total": 110, "used": 53, "reserved": 39, "available": 18 }, "progress": { "total": 96, "pending": 9, "in_progress": 30, "action_required": 0, "submitted": 31, "live": 22, "not_accepted": 3, "cancelled": 1 }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-04T10:02:15Z", "launched_at": "2026-10-03T14:05:40Z" }, "previous_status": null, "listings_added": 9 } } ``` ## A project is moving again The `project.in_progress` event, sent as a POST to your endpoint. Sent when a project returns to `in_progress` from `action_required`, `on_hold` or `completed`. A launch does not send it: the project starts in `in_progress` with `project.launched`. Body: ```json { "object": "event", "id": "evt_2Zp5Kx1Wq9Lt4Vb8Nr3McU", "type": "project.in_progress", "created_at": "2026-10-06T16:40:09Z", "livemode": false, "project": "prj_1Nc7Vd3Kq8Zr5Tx2Wm9LbH", "data": { "object": { "object": "project", "id": "prj_1Nc7Vd3Kq8Zr5Tx2Wm9LbH", "livemode": false, "status": "in_progress", "hold_reason": null, "action": null, "url": "https://quotafy.test", "name": "Quotafy", "maker_name": "Tom Okafor", "contact_email": "sales@quotafy.test", "tagline": "Quotes your clients sign in one click", "short_description": "Quotafy turns a price list into quotes that clients accept and sign online, with reminders and a deposit link.", "long_description": null, "category": "saas", "pricing_model": "paid", "price_amount_cents": 2900, "price_period": "monthly", "launch_date": "2026-08-20", "twitter_url": "https://x.com/quotafy", "competitors": [ { "name": "Bidsheet", "url": "https://bidsheet.test" } ], "tags": [ "quotes", "proposals", "e-signature" ], "audience": { "b2b": true, "ai": false, "directory": false }, "promo_code": "QUOTE30", "promo_description": "30% off the first 3 months", "logo": { "object": "image", "id": "img_1Qa8Kx3Wm7Lt2Vb9Rz5NcE", "status": "ready", "url": "https://feed.example.net/a/Qf2Lm8Wx.k5Tp3", "error": null }, "screenshots": [ { "object": "image", "id": "img_4Qb2Kw9Lx5Mt8Vb3Rz7NdG", "status": "ready", "url": "https://feed.example.net/a/Qg9Nt4Vb.z7Kr2", "error": null } ], "autofill": { "status": "complete", "name_source": "input", "filled": [], "image_candidates": [] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 12, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [ "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG" ], "allowance": { "total": 110, "used": 40, "reserved": 52, "available": 18 }, "progress": { "total": 92, "pending": 30, "in_progress": 22, "action_required": 0, "submitted": 25, "live": 15, "not_accepted": 0, "cancelled": 0 }, "external_id": "crm_8907", "metadata": {}, "created_at": "2026-10-05T09:40:18Z", "updated_at": "2026-10-06T16:40:09Z", "launched_at": "2026-10-05T10:12:07Z" }, "previous_status": "on_hold" } } ``` ## A project needs you or your client The `project.action_required` event, sent as a POST to your endpoint. Sent when a project needs someone to act. `data.object.action` says what to do and who: `waiting_on` is `client` or `agency`, and `client_message` is ready to forward. Body: ```json { "object": "event", "id": "evt_6Mz4Kq9Wr3Lt8Vb2Nx6HcE", "type": "project.action_required", "created_at": "2026-10-08T09:13:30Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "project", "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "livemode": false, "status": "action_required", "hold_reason": null, "action": { "code": "install_badge", "waiting_on": "client", "client_message": "Please add the directory badges block to https://ledgerly.test. 9 directories list Ledgerly once their badges show on the site." }, "url": "https://ledgerly.test", "name": "Ledgerly", "maker_name": "Maya Chen", "contact_email": "founder@ledgerly.test", "tagline": "Double-entry bookkeeping for solo founders", "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 1200, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "accounting", "bookkeeping", "invoicing" ], "audience": { "b2b": false, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ", "status": "ready", "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4", "error": null }, "screenshots": [ { "object": "image", "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF", "status": "ready", "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline", "short_description" ], "image_candidates": [ { "url": "https://ledgerly.test/apple-touch-icon.png", "suggested_as": "logo", "width": 180, "height": 180 }, { "url": "https://ledgerly.test/og-image.png", "suggested_as": "screenshot", "width": 1200, "height": 630 } ] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 34, "badge": { "status": "not_found", "checked_at": "2026-10-08T09:12:44Z" }, "auto_replace": true, "excluded_directories": [], "allowance": { "total": 110, "used": 78, "reserved": 14, "available": 18 }, "progress": { "total": 96, "pending": 0, "in_progress": 5, "action_required": 9, "submitted": 9, "live": 69, "not_accepted": 3, "cancelled": 1 }, "external_id": "crm_8812", "metadata": { "account_owner": "Priya", "crm_stage": "onboarding" }, "created_at": "2026-10-03T13:58:12Z", "updated_at": "2026-10-08T09:13:30Z", "launched_at": "2026-10-03T14:05:40Z" }, "previous_status": "in_progress" } } ``` ## Work on a project paused The `project.on_hold` event, sent as a POST to your endpoint. Sent when work on a project pauses. `data.object.hold_reason` is `review` while we review the project, which clears without action from you, or `paused` when we paused it; contact support about a pause. Body: ```json { "object": "event", "id": "evt_1Qx9Kr4Wm8Lt3Vb7Nz2HdY", "type": "project.on_hold", "created_at": "2026-10-06T08:00:21Z", "livemode": false, "project": "prj_1Nc7Vd3Kq8Zr5Tx2Wm9LbH", "data": { "object": { "object": "project", "id": "prj_1Nc7Vd3Kq8Zr5Tx2Wm9LbH", "livemode": false, "status": "on_hold", "hold_reason": "review", "action": null, "url": "https://quotafy.test", "name": "Quotafy", "maker_name": "Tom Okafor", "contact_email": "sales@quotafy.test", "tagline": "Quotes your clients sign in one click", "short_description": "Quotafy turns a price list into quotes that clients accept and sign online, with reminders and a deposit link.", "long_description": null, "category": "saas", "pricing_model": "paid", "price_amount_cents": 2900, "price_period": "monthly", "launch_date": "2026-08-20", "twitter_url": "https://x.com/quotafy", "competitors": [ { "name": "Bidsheet", "url": "https://bidsheet.test" } ], "tags": [ "quotes", "proposals", "e-signature" ], "audience": { "b2b": true, "ai": false, "directory": false }, "promo_code": "QUOTE30", "promo_description": "30% off the first 3 months", "logo": { "object": "image", "id": "img_1Qa8Kx3Wm7Lt2Vb9Rz5NcE", "status": "ready", "url": "https://feed.example.net/a/Qf2Lm8Wx.k5Tp3", "error": null }, "screenshots": [ { "object": "image", "id": "img_4Qb2Kw9Lx5Mt8Vb3Rz7NdG", "status": "ready", "url": "https://feed.example.net/a/Qg9Nt4Vb.z7Kr2", "error": null } ], "autofill": { "status": "complete", "name_source": "input", "filled": [], "image_candidates": [] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 12, "badge": { "status": "not_checked", "checked_at": null }, "auto_replace": true, "excluded_directories": [ "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG" ], "allowance": { "total": 110, "used": 40, "reserved": 52, "available": 18 }, "progress": { "total": 92, "pending": 40, "in_progress": 12, "action_required": 0, "submitted": 25, "live": 15, "not_accepted": 0, "cancelled": 0 }, "external_id": "crm_8907", "metadata": {}, "created_at": "2026-10-05T09:40:18Z", "updated_at": "2026-10-06T08:00:21Z", "launched_at": "2026-10-05T10:12:07Z" }, "previous_status": "in_progress" } } ``` ## A project completed The `project.completed` event, sent as a POST to your endpoint. Sent when no listing is `pending`, `in_progress` or `action_required` and auto-replace has nothing to add. Listings in `submitted` can still go live and send `listing.live`. Body: ```json { "object": "event", "id": "evt_3Vw7Kq2Lx8Mt5Nb1Rz9HdT", "type": "project.completed", "created_at": "2026-10-07T18:22:47Z", "livemode": false, "project": "prj_3Ac9Kx4Wq7Lt2Vb8Rz5NmD", "data": { "object": { "object": "project", "id": "prj_3Ac9Kx4Wq7Lt2Vb8Rz5NmD", "livemode": false, "status": "completed", "hold_reason": null, "action": null, "url": "https://acme.test", "name": "Acme CRM", "maker_name": "Lena Park", "contact_email": "hello@acme.test", "tagline": "The CRM for teams of five", "short_description": "Acme CRM keeps contacts, deals and follow-ups in one shared list, with a weekly digest for the whole team.", "long_description": null, "category": "saas", "pricing_model": "freemium", "price_amount_cents": 900, "price_period": "monthly", "launch_date": null, "twitter_url": null, "competitors": [], "tags": [ "crm", "sales" ], "audience": { "b2b": true, "ai": false, "directory": false }, "promo_code": null, "promo_description": null, "logo": { "object": "image", "id": "img_3Ad7Kx2Wq8Lt4Vb9Rz1NmH", "status": "ready", "url": "https://feed.example.net/a/Ac6Rk1Wn.p4Lx8", "error": null }, "screenshots": [ { "object": "image", "id": "img_0Ae5Kw1Lq9Xt3Vb7Rz2McJ", "status": "ready", "url": "https://feed.example.net/a/Ad3Mq7Zt.v9Kc1", "error": null } ], "autofill": { "status": "complete", "name_source": "site", "filled": [ "name", "tagline" ], "image_candidates": [] }, "readiness": { "ready": true, "missing": [] }, "domain_rating": 51, "badge": { "status": "installed", "checked_at": "2026-10-03T15:08:30Z" }, "auto_replace": false, "excluded_directories": [], "allowance": { "total": 110, "used": 85, "reserved": 0, "available": 25 }, "progress": { "total": 88, "pending": 0, "in_progress": 0, "action_required": 0, "submitted": 3, "live": 82, "not_accepted": 2, "cancelled": 1 }, "external_id": "crm_8650", "metadata": {}, "created_at": "2026-10-03T15:01:44Z", "updated_at": "2026-10-07T18:22:47Z", "launched_at": "2026-10-03T15:12:09Z" }, "previous_status": "in_progress" } } ``` ## Work on a listing started The `listing.in_progress` event, sent as a POST to your endpoint. Sent when a listing leaves `pending`, or resumes after `action_required`. It is not sent again while the listing stays in progress. Body: ```json { "object": "event", "id": "evt_1Wd8Kq3Lx7Mt2Vb9Rz5NcG", "type": "listing.in_progress", "created_at": "2026-10-03T16:05:12Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_5Wq9Lm2Xr7Kt3Vb8Nz1HcD", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "name": "SaaSHub", "kind": "directory", "domain_rating": 61, "logo_url": "https://feed.example.net/a/h4Sw8Lp.q2Xn" }, "status": "in_progress", "reason": null, "action": null, "live_url": null, "proof_url": null, "created_at": "2026-10-03T14:00:00Z", "submitted_at": null, "live_at": null }, "previous_status": "pending" } } ``` ## A listing needs you or your client The `listing.action_required` event, sent as a POST to your endpoint. Sent when a listing waits on someone. `data.object.action` says what to do; for `install_badge`, forward `client_message` to your client and verify the badge once it is installed. Body: ```json { "object": "event", "id": "evt_6Lr3Kx8Wq2Nt7Vb1Rz5MpA", "type": "listing.action_required", "created_at": "2026-10-08T09:13:30Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_2Tz6Kp9Wm3Qx8Lr5Vb1NcJ", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "name": "Uneed", "kind": "directory", "domain_rating": 58, "logo_url": "https://feed.example.net/a/u7Nd3Kc.w5Rb" }, "status": "action_required", "reason": null, "action": { "code": "install_badge", "waiting_on": "client", "client_message": "Please add the directory badges block to https://ledgerly.test. Uneed lists Ledgerly once its badge shows on the site." }, "live_url": null, "proof_url": null, "created_at": "2026-10-04T10:00:00Z", "submitted_at": null, "live_at": null }, "previous_status": "in_progress" } } ``` ## A directory has the listing The `listing.submitted` event, sent as a POST to your endpoint. Sent when the directory has the listing and reviews it. Also sent, with `data.previous_status` `live`, in the rare case a live listing goes back to review. Body: ```json { "object": "event", "id": "evt_2Hq8Wn3Kx7Lt1Vb6Rz9McS", "type": "listing.submitted", "created_at": "2026-10-05T11:20:33Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_5Wq9Lm2Xr7Kt3Vb8Nz1HcD", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "name": "SaaSHub", "kind": "directory", "domain_rating": 61, "logo_url": "https://feed.example.net/a/h4Sw8Lp.q2Xn" }, "status": "submitted", "reason": null, "action": null, "live_url": null, "proof_url": null, "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-05T11:00:00Z", "live_at": null }, "previous_status": "in_progress" } } ``` ## A listing is live The `listing.live` event, sent as a POST to your endpoint. Sent when the listing is published. `data.object.live_url` points to it, or is `null` when the listing was confirmed without a link. A listing can go live without a `listing.submitted` event first. Body: ```json { "object": "event", "id": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ", "type": "listing.live", "created_at": "2026-10-08T14:17:01Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "status": "live", "reason": null, "action": null, "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-04T09:00:00Z", "live_at": "2026-10-08T14:00:00Z" }, "previous_status": "submitted" } } ``` ## A directory did not list the product The `listing.not_accepted` event, sent as a POST to your endpoint. Sent when the directory declines the listing, cannot take it, or takes down a live listing. `data.object.reason` says which, and the allowance the listing held returns to the project. Body: ```json { "object": "event", "id": "evt_0Hm6Kx3Wq8Lt2Vb7Rz4NcR", "type": "listing.not_accepted", "created_at": "2026-10-06T07:41:55Z", "livemode": false, "project": "prj_3Ac9Kx4Wq7Lt2Vb8Rz5NmD", "data": { "object": { "object": "listing", "id": "lst_3Fp8Wx2Kq6Lm9Rt4Vb1NzD", "livemode": false, "project": "prj_3Ac9Kx4Wq7Lt2Vb8Rz5NmD", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "status": "not_accepted", "reason": "declined", "action": null, "live_url": null, "proof_url": null, "created_at": "2026-10-03T15:00:00Z", "submitted_at": "2026-10-04T08:00:00Z", "live_at": null }, "previous_status": "submitted" } } ``` ## A listing was withdrawn The `listing.cancelled` event, sent as a POST to your endpoint. Sent when we withdraw a listing before it reaches the directory, with `reason` `withdrawn`. The allowance it held returns to the project. Body: ```json { "object": "event", "id": "evt_0Gn4Kw8Lq3Xt9Vb2Rz6MdQ", "type": "listing.cancelled", "created_at": "2026-10-03T18:03:26Z", "livemode": false, "project": "prj_3Ac9Kx4Wq7Lt2Vb8Rz5NmD", "data": { "object": { "object": "listing", "id": "lst_6Cv1Nb8Lz3Kx9Wq2Rt7MpH", "livemode": false, "project": "prj_3Ac9Kx4Wq7Lt2Vb8Rz5NmD", "directory": { "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "name": "Uneed", "kind": "directory", "domain_rating": 58, "logo_url": "https://feed.example.net/a/u7Nd3Kc.w5Rb" }, "status": "cancelled", "reason": "withdrawn", "action": null, "live_url": null, "proof_url": null, "created_at": "2026-10-03T15:00:00Z", "submitted_at": null, "live_at": null }, "previous_status": "pending" } } ``` ## A report is ready The `report.ready` event, sent as a POST to your endpoint. Sent when a report has been built. Download it from `GET /reports/{report_id}/file` before `data.object.expires_at`, 7 days later. Body: ```json { "object": "event", "id": "evt_6Tk3Wq9Lx2Nt8Vb5Rz1MhK", "type": "report.ready", "created_at": "2026-10-08T15:02:41Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "report", "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "pdf", "include_logins": false, "status": "ready", "file_name": "ledgerly-listings-2026-10-08.pdf", "created_at": "2026-10-08T15:02:10Z", "ready_at": "2026-10-08T15:02:41Z", "expires_at": "2026-10-15T15:02:41Z" }, "previous_status": "building" } } ``` ## A report failed The `report.failed` event, sent as a POST to your endpoint. Sent when a report could not be built. Start a new one; if it fails again, contact support with the event id. Body: ```json { "object": "event", "id": "evt_6Uf8Kx2Wq7Lt3Vb9Rz4NcW", "type": "report.failed", "created_at": "2026-10-08T15:05:31Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "report", "id": "rep_2Gk7Wn3Lq9Xt5Vb8Rz1MhC", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "xlsx", "include_logins": false, "status": "failed", "file_name": null, "created_at": "2026-10-08T15:05:00Z", "ready_at": null, "expires_at": null }, "previous_status": "building" } } ``` ## A test event The `ping` event, sent as a POST to your endpoint. Sent by `POST /webhook_endpoints/{webhook_endpoint_id}/test` and by the console's test button, to one endpoint only, whatever its `events` filter. `data.object` is the endpoint, `project` is `null`, and the event also appears in `GET /events`. Body: ```json { "object": "event", "id": "evt_7Aa2Kq8Wx3Lt9Vb5Rz1NdM", "type": "ping", "created_at": "2026-10-06T12:01:15Z", "livemode": false, "project": null, "data": { "object": { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "description": "Northlight CRM sync", "events": [ "listing.*", "project.*" ], "enabled": true, "disabled_reason": null, "secret": null, "previous_secret_expires_at": null, "delivery_summary": { "last_attempted_at": null, "last_http_status": null, "attempted_7d": 0, "succeeded_7d": 0 }, "created_at": "2026-10-06T12:00:04Z", "updated_at": "2026-10-06T12:00:04Z" }, "previous_status": null } } ``` --- # Directories URL: https://submitator.com/docs/api/directories > The catalog a launch picks from, highest Domain Rating first. The catalog a launch picks from, highest Domain Rating first. Domain Rating (DR) is a 0 to 100 score of a site's backlink profile, measured by Ahrefs. `kind` tells a directory from an article platform, where the listing is a post about the product. A launch or an add takes an article platform only when you name it in `include`: `auto`, `exclude` and auto-replace never take one. `outdated` marks a directory that lately seems to publish few new products. It is a sign, not a verdict, and it changes nothing a launch picks. `backlink_condition` says what a `dofollow` link depends on: `badge` for a directory that links dofollow only while its badge is on the product's site. Verify the project's badge before a launch or an add takes one. `under_maintenance` marks a directory that is temporarily turned off while we tune it. It stays in the catalog and comes back on its own; until then a launch, an add and auto-replace do not take it, and `include` answers 422 `invalid_directories` for it. `free_only` marks a directory that takes only free products. For a project whose `pricing_model` is not `free` it is locked: a launch, an add and auto-replace pass it by, and `include` answers 422 `invalid_directories` for it. `monthly_organic_visits` estimates the visits a month the directory's site gets from Google search, worldwide, rounded to two significant figures: `100` means 100 or fewer, and `null` means no estimate above zero. It counts search visits only and changes nothing a launch picks. `GET /projects/{project_id}/directories` shows what each directory is to one project: what `auto` would take, what else you can name, and what is excluded, listed or locked, with the reason. Pick from it and send your pick as `include`. Before your first purchase, test keys see the top 20 directories only, and no article platform. ## List directories `GET https://api.submitator.com/v1/directories` Returns the directories a launch can pick from, highest Domain Rating first, with the article platforms you can name in `include`. Filter by kind, topic, minimum Domain Rating, requirement or audience, or search names with `q`. Before your first purchase, test keys see the top 20 directories only, and no article platform. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `kind` | query | No | Only directories of this kind: `directory`, or `article` for the article platforms, which a launch or an add takes only from `include`. | | `topic` | query | No | Only directories with this topic. | | `min_dr` | query | No | Only directories with a Domain Rating of at least this value, 0 to 100. | | `requires` | query | No | Only directories with this requirement in `requires`. `none` returns the directories that require nothing. | | `audience` | query | No | Only directories limited to this kind of product in `audience`. `any` returns the directories that take every product: `audience` is empty and `free_only` is `false`. | | `q` | query | No | Only directories whose name or domain contains this text, ignoring case. 2 to 100 characters. | | `cursor` | query | No | `next_cursor` from the previous page of the same list, as you received it. Leave it out for the first page. | | `limit` | query | No | How many items to return, 1 to 100. Defaults to 20. | Response 200: ```json { "object": "list", "data": [ { "object": "directory", "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "livemode": false, "name": "BetaList", "kind": "directory", "url": "https://betalist.com", "domain_rating": 73, "monthly_organic_visits": 24000, "topic": "startups", "backlink": "dofollow", "backlink_condition": null, "requires": [], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, { "object": "directory", "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "livemode": false, "name": "SaaSHub", "kind": "directory", "url": "https://www.saashub.com", "domain_rating": 61, "monthly_organic_visits": 170000, "topic": "software", "backlink": "nofollow", "backlink_condition": null, "requires": [], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false, "logo_url": "https://feed.example.net/a/h4Sw8Lp.q2Xn" }, { "object": "directory", "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "livemode": false, "name": "Uneed", "kind": "directory", "url": "https://www.uneed.best", "domain_rating": 58, "monthly_organic_visits": 36000, "topic": "startups", "backlink": "dofollow", "backlink_condition": null, "requires": [ "badge" ], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false, "logo_url": "https://feed.example.net/a/u7Nd3Kc.w5Rb" } ], "has_more": true, "next_cursor": "cur_Dz4Kq8Wx2Lt6Vb9M" } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Read a directory `GET https://api.submitator.com/v1/directories/{directory_id}` Returns one directory from the catalog. An id that is not in the catalog, or not in the preview before your first purchase, returns 404. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `directory_id` | path | Yes | The directory's id. | Response 200: ```json { "object": "directory", "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "livemode": false, "name": "Uneed", "kind": "directory", "url": "https://www.uneed.best", "domain_rating": 58, "monthly_organic_visits": 36000, "topic": "startups", "backlink": "dofollow", "backlink_condition": null, "requires": [ "badge" ], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false, "logo_url": "https://feed.example.net/a/u7Nd3Kc.w5Rb" } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## List a project's directory choices `GET https://api.submitator.com/v1/projects/{project_id}/directories` Returns every directory of the catalog with what it is to the project now, highest Domain Rating first: `suggested` for the ones `auto` would take, up to `limit`, `open` for the others you can name in `include`, and `excluded`, `listed` or `locked`, with the reason. Send the ones you pick as `include` to `POST /projects/{project_id}/launch` or, once launched, `POST /projects/{project_id}/listings`. Before your first purchase it covers the top 20 directories only. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "project_directories", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "limit": 110, "directories": [ { "directory": { "object": "directory", "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "livemode": false, "name": "BetaList", "kind": "directory", "url": "https://betalist.com", "domain_rating": 73, "monthly_organic_visits": 24000, "topic": "startups", "backlink": "dofollow", "backlink_condition": null, "requires": [], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "state": "suggested", "reason": null, "message": null, "listing": null }, { "directory": { "object": "directory", "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "livemode": false, "name": "SaaSHub", "kind": "directory", "url": "https://www.saashub.com", "domain_rating": 61, "monthly_organic_visits": 170000, "topic": "software", "backlink": "nofollow", "backlink_condition": null, "requires": [], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false, "logo_url": "https://feed.example.net/a/h4Sw8Lp.q2Xn" }, "state": "suggested", "reason": null, "message": null, "listing": null }, { "directory": { "object": "directory", "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG", "livemode": false, "name": "Uneed", "kind": "directory", "url": "https://www.uneed.best", "domain_rating": 58, "monthly_organic_visits": 36000, "topic": "startups", "backlink": "dofollow", "backlink_condition": null, "requires": [ "badge" ], "audience": [], "free_only": false, "outdated": false, "under_maintenance": false, "logo_url": "https://feed.example.net/a/u7Nd3Kc.w5Rb" }, "state": "locked", "reason": "badge", "message": "Uneed needs the badge on https://ledgerly.test first. Verify the badge, then include it.", "listing": null } ] } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). --- # Test mode URL: https://submitator.com/docs/api/test-mode > With a sbm_test_ key every call works as in live mode, on separate data, and nothing is submitted or spent. With a `sbm_test_` key every call works as in live mode, on separate data, and nothing is submitted or spent. Share links are the one exception: a client page needs a live project, so creating one answers 422 `validation_failed` and reading or turning one off answers 404. Listings move on their own: `in_progress` after 1 to 5 minutes, `submitted` after 3 to 8 minutes and an outcome after 6 to 15 minutes, where 80% go `live`, 12% end `not_accepted` and 8% stay `submitted`. The outcome depends only on the listing's id, so a listing always ends the same way. Apart from webhook deliveries, nothing leaves our servers in test mode. Image URLs are not downloaded and files are checked but not stored, feed URLs have the right shape but return 404, and autofill and Domain Ratings are simulated. Hosts on `.test` and `.example` are accepted here and rejected in live mode. Logins are placeholders: about 45% of test listings get one, on the project's contact email or on an address at `login.test`, with a password made from the project's id and sample emails whose links point to `login.test`. Nothing signs up anywhere. Two inputs fail on purpose: a host that starts with `nobadge.` never passes badge verification, and an image URL ending in `/fail.png` returns `image_unreachable`. Test data is deleted after 30 days without activity. ## Move a test listing forward `POST https://api.submitator.com/v1/test_helpers/listings/{listing_id}/advance` Moves a test listing to its next status now, or to the status you name in `to`. Events and webhooks fire as they would in live mode. Live keys get 403 `test_mode_only`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `listing_id` | path | Yes | The listing's id. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `to` | string | No | The status to move to. It must be a move the listing could make in live mode. | Request: ```json { "to": "live" } ``` Response 200: ```json { "object": "listing", "id": "lst_5Wq9Lm2Xr7Kt3Vb8Nz1HcD", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "name": "SaaSHub", "kind": "directory", "domain_rating": 61, "logo_url": "https://feed.example.net/a/h4Sw8Lp.q2Xn" }, "status": "live", "reason": null, "action": null, "live_url": "https://www.saashub.com/ledgerly", "proof_url": "https://feed.example.net/a/Ps6Wn2Kx.h8Lq4", "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-05T11:00:00Z", "live_at": "2026-10-08T15:00:00Z" } ``` Typical errors: [`test_mode_only`](https://submitator.com/docs/errors#test_mode_only), [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`not_found`](https://submitator.com/docs/errors#not_found). ## Set your test launches `POST https://api.submitator.com/v1/test_helpers/account/launches` Sets how many test launches are available, from 0 to 1,000. Set 0 to try the `no_launches_left` path. Live keys get 403 `test_mode_only`. | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `available` | integer | Yes | Test launches to make available, 0 to 1,000. | Request: ```json { "available": 0 } ``` Response 200: ```json { "object": "account", "livemode": false, "name": "Northlight Studio", "state": "active", "launches": { "available": 0, "used": 3, "total": 3 }, "capacity": { "in_flight": 25, "limit": 100 }, "rate_limit": { "limit": 3600, "remaining": 3488, "resets_at": "2026-10-08T16:00:00Z" } } ``` Typical errors: [`test_mode_only`](https://submitator.com/docs/errors#test_mode_only), [`validation_failed`](https://submitator.com/docs/errors#validation_failed). --- # Share links URL: https://submitator.com/docs/api/share-links > A read-only page that shows your client how their launch is going, in your agency's name and colors. A read-only page that shows your client how their launch is going, in your agency's name and colors. It lists live directories with links, the ones still in progress and the latest reports, and shows no prices. Each project has at most one active link. Creating a new link turns the old URL off. ## Read the share link `GET https://api.submitator.com/v1/projects/{project_id}/share_link` Returns the project's active link with its view count. A project without an active link returns 404. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "share_link", "livemode": true, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "url": "https://example.net/r/6Tq2Wm9Kx4Lr8Vb3Nz7HcP", "created_at": "2026-10-08T15:20:00Z", "expires_at": null, "revoked_at": null, "last_viewed_at": "2026-10-08T18:42:10Z", "view_count": 3 } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## Create a share link `POST https://api.submitator.com/v1/projects/{project_id}/share_link` Creates a read-only progress page for the project that you can send to your client. It shows your agency's name and colors. A project has 1 active link: creating a new one turns the previous URL off. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | | Body field | Type | Required | What it is | | --- | --- | --- | --- | | `expires_at` | string or null | No | When the link should stop working. Leave it out or send `null` for a link that works until you turn it off. | Request: ```json { "expires_at": null } ``` Response 201: ```json { "object": "share_link", "livemode": true, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "url": "https://example.net/r/6Tq2Wm9Kx4Lr8Vb3Nz7HcP", "created_at": "2026-10-08T15:20:00Z", "expires_at": null, "revoked_at": null, "last_viewed_at": null, "view_count": 0 } ``` Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`not_found`](https://submitator.com/docs/errors#not_found), [`account_suspended`](https://submitator.com/docs/errors#account_suspended). ## Turn the share link off `DELETE https://api.submitator.com/v1/projects/{project_id}/share_link` Turns the active link off at once; its URL then returns 404 to anyone who opens it. Create a new link to share the page again. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "share_link", "livemode": true, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "url": "https://example.net/r/6Tq2Wm9Kx4Lr8Vb3Nz7HcP", "created_at": "2026-10-08T15:20:00Z", "expires_at": null, "revoked_at": "2026-10-09T09:00:00Z", "last_viewed_at": "2026-10-08T18:42:10Z", "view_count": 3 } ``` Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`permission_denied`](https://submitator.com/docs/errors#permission_denied). --- # Logins URL: https://submitator.com/docs/api/logins > The accounts created for your client on directories that need one: where each signs in, its email and username, whether it is ready, and the one password they all use. The accounts created for your client on directories that need one: where each signs in, its email and username, whether it is ready, and the one password they all use. Hand them to your client, so your client owns the listings. Logins are credentials. A read-only key gets 403 `permission_denied`, responses carry `Cache-Control: no-store`, and logins never appear in events or webhooks. ## List a project's logins `GET https://api.submitator.com/v1/projects/{project_id}/logins` Returns the accounts created for the project on directories that need one, by directory name, with the one password they all use. A login is ready once its account exists; until then it is being set up. Logins are credentials: a read-only key gets 403 `permission_denied`, and responses carry `Cache-Control: no-store`. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `project_id` | path | Yes | The project's id. | Response 200: ```json { "object": "project_logins", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "password": "Kq7mZt3vRw9x!Pa2", "logins": [ { "object": "login", "listing": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "kind": "directory", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "site_url": "https://betalist.com", "email": "founder@ledgerly.test", "username": null, "ready": true, "emails_count": null }, { "object": "login", "listing": "lst_5Wq9Lm2Xr7Kt3Vb8Nz1HcD", "directory": { "id": "dir_6Pw3Kx9Ty2Rq7Lm1Zb5VcN", "name": "SaaSHub", "kind": "directory", "domain_rating": 61, "logo_url": "https://feed.example.net/a/h4Sw8Lp.q2Xn" }, "site_url": "https://www.saashub.com", "email": "ledgerly84@login.test", "username": "ledgerly91", "ready": true, "emails_count": 2 } ] } ``` Typical errors: [`permission_denied`](https://submitator.com/docs/errors#permission_denied), [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). ## List the emails a login received `GET https://api.submitator.com/v1/listings/{listing_id}/emails` Returns up to 25 emails the listing's directory sent to its login, newest first, as text with their links. Use it for a confirmation code or a password reset link. A login whose `emails_count` is `null` receives its emails at your client's own address, and this returns 404 for it. | Parameter | In | Required | What it is | | --- | --- | --- | --- | | `listing_id` | path | Yes | The listing's id. | Response 200: ```json { "object": "login_emails", "livemode": false, "listing": "lst_5Wq9Lm2Xr7Kt3Vb8Nz1HcD", "email": "ledgerly84@login.test", "emails": [ { "from": "SaaSHub", "from_email": "noreply@login.test", "subject": "Your sign-in code for SaaSHub", "received_at": "2026-10-05T11:02:00Z", "text": "Your code is 482913. It expires in 10 minutes.\n\nThis is a test mode sample: nothing was sent.", "links": [] }, { "from": "SaaSHub", "from_email": "noreply@login.test", "subject": "Confirm your email for SaaSHub", "received_at": "2026-10-03T14:04:00Z", "text": "Confirm the account you created on SaaSHub: https://login.test/saashub/confirm/9f2c4e7a1b3d5f60a8c2e4b6\n\nThis is a test mode sample: nothing was sent.", "links": [ "https://login.test/saashub/confirm/9f2c4e7a1b3d5f60a8c2e4b6" ] } ] } ``` Typical errors: [`permission_denied`](https://submitator.com/docs/errors#permission_denied), [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited). --- # Signatures URL: https://submitator.com/docs/webhooks/signatures > Every delivery is signed as Standard Webhooks describes. Check it with an official library and your whsec_ secret, or with HMAC-SHA256 in any language. Every webhook delivery is signed as [Standard Webhooks](https://www.standardwebhooks.com) describes. Anyone can send a POST to your URL, so check the signature before you trust the body. ## The headers | Header | What it holds | | --- | --- | | `webhook-id` | The event's id, such as `evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ`. Every attempt of the same event carries the same id, so store it and skip the deliveries you have handled. | | `webhook-timestamp` | When this attempt was signed, in Unix seconds. | | `webhook-signature` | `v1,` and a base64 HMAC-SHA256. For 24 hours after you roll the secret it holds 2 signatures, separated by a space. | The body is the event as JSON, the same object `GET /events/{event_id}` returns. [Event types](https://submitator.com/docs/webhooks/event-types) lists what it can hold. A delivery, its body cut short: ```http POST /listings HTTP/1.1 Host: hooks.northlight.test Content-Type: application/json webhook-id: evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ webhook-timestamp: 1791469022 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= {"object":"event","id":"evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ","type":"listing.live","created_at":"2026-10-08T14:17:01Z","livemode":false,"project":"prj_4QzX1m9Lr2Vb7Nc8Tk3HwP","data":{...}} ``` ## Your secret Adding an endpoint returns its secret once: `whsec_` and the base64 of 32 random bytes. Store it in your secret manager; these docs read it from `SUBMITATOR_WEBHOOK_SECRET`. Each endpoint has its own secret, and live and test endpoints are separate. ## Check it with a library The official Standard Webhooks libraries check each signature in the header, and reject a timestamp more than 5 minutes from your clock. Pass them the raw body exactly as it arrived, the headers and your `whsec_` secret. They return the event, or raise an error when the delivery is not ours. verify-webhook.mjs: ```js import { Webhook } from "standardwebhooks"; // The whsec_ secret of your endpoint, shown once when you added it. const secret = process.env.SUBMITATOR_WEBHOOK_SECRET; // Returns the event when the delivery is ours. Throws a // WebhookVerificationError when the signature does not match or the // timestamp is more than 5 minutes from your clock. export function verifyWebhook(rawBody, headers, whsec = secret) { return new Webhook(whsec).verify(rawBody, headers); } ``` ```python # pip install standardwebhooks import os from standardwebhooks.webhooks import Webhook webhook = Webhook(os.environ["SUBMITATOR_WEBHOOK_SECRET"]) # raw_body: the request body as bytes. Raises WebhookVerificationError # when the delivery is not ours. With Flask: # event = verify_webhook(request.get_data(), dict(request.headers)) def verify_webhook(raw_body, headers): return webhook.verify(raw_body, headers) ``` ```ruby # gem install standardwebhooks require "standardwebhooks" WEBHOOK = StandardWebhooks::Webhook.new(ENV.fetch("SUBMITATOR_WEBHOOK_SECRET")) # In a Rails controller. Raises StandardWebhooks::WebhookVerificationError # when the delivery is not ours. def verify_webhook WEBHOOK.verify(request.raw_post, { "webhook-id" => request.headers["webhook-id"], "webhook-timestamp" => request.headers["webhook-timestamp"], "webhook-signature" => request.headers["webhook-signature"], }) end ``` ```php verify(file_get_contents("php://input"), [ "webhook-id" => $_SERVER["HTTP_WEBHOOK_ID"] ?? "", "webhook-timestamp" => $_SERVER["HTTP_WEBHOOK_TIMESTAMP"] ?? "", "webhook-signature" => $_SERVER["HTTP_WEBHOOK_SIGNATURE"] ?? "", ]); ``` ```go // go get github.com/standard-webhooks/standard-webhooks/libraries/go import ( "io" "net/http" "os" standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go" ) func handleWebhook(w http.ResponseWriter, r *http.Request) { wh, err := standardwebhooks.NewWebhook(os.Getenv("SUBMITATOR_WEBHOOK_SECRET")) if err != nil { http.Error(w, "bad secret", http.StatusInternalServerError) return } body, err := io.ReadAll(r.Body) if err != nil || wh.Verify(body, r.Header) != nil { http.Error(w, "not ours", http.StatusBadRequest) return } // body is the event as JSON. w.WriteHeader(http.StatusNoContent) } ``` Answer 400 to a delivery that fails the check: it did not come from us. [Receive webhooks](https://submitator.com/docs/guides/receive-webhooks) puts the check into a complete endpoint. ## Check it without a library The check takes 5 steps in any language: 1. Take your secret without `whsec_` and decode it from base64. That is the key. 2. Join `webhook-id`, `webhook-timestamp` and the raw body with dots: `{webhook-id}.{webhook-timestamp}.{body}`. 3. Sign that text with HMAC-SHA256 and the key, and encode the result in base64. 4. Compare it, in constant time, with each `v1,` signature in `webhook-signature`. One match is enough. 5. Reject the delivery when `webhook-timestamp` is more than 5 minutes from your clock. verify-webhook.mjs: ```js import { createHmac, timingSafeEqual } from "node:crypto"; // The same check without a library. rawBody is the body exactly as received. export function verifySignature(rawBody, headers, whsec = process.env.SUBMITATOR_WEBHOOK_SECRET) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; const key = Buffer.from(whsec.replace(/^whsec_/, ""), "base64"); const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest(); const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 5 * 60; const matches = String(headers["webhook-signature"] ?? "") .split(" ") .some((part) => { const [version, signature = ""] = part.split(","); const given = Buffer.from(signature, "base64"); return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected); }); return fresh && matches; } ``` ```python import base64 import hashlib import hmac import time def verify_signature(raw_body, headers, secret): key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.".encode() + raw_body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() fresh = abs(time.time() - int(headers["webhook-timestamp"])) <= 5 * 60 signatures = [part.split(",", 1) for part in headers["webhook-signature"].split(" ") if "," in part] return fresh and any(version == "v1" and hmac.compare_digest(value, expected) for version, value in signatures) ``` ## Mistakes that break the check - **Parsing the body before the check.** JSON parsed and written again has other bytes, and the signature no longer matches. Check the raw body first, then parse it. - **A clock that drifts.** A server clock more than 5 minutes off rejects every delivery. Keep it in sync with NTP. - **One secret for every endpoint.** Each endpoint has its own secret, and test endpoints have their own too. Check with the secret of the endpoint the delivery came to. ## Roll the secret `POST /webhook_endpoints/{webhook_endpoint_id}/rotate_secret` returns a new secret, shown in that response only. For the next 24 hours each delivery carries 2 signatures, one per secret, so it passes with either and you can deploy the new secret without missing an event. ```bash curl -X POST https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/rotate_secret \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/rotate_secret", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.post( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/rotate_secret", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, ) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "livemode": false, "url": "https://hooks.northlight.test/listings", "secret": "whsec_BFXycpAAK/Ay+ue0CxyVr5JQrZILyVqHTkjpX3GtfmY=", "previous_secret_expires_at": "2026-10-09T15:30:00Z" } ``` `previous_secret_expires_at` says when the old secret stops signing. Roll the secret right away if it leaks. ## Send yourself a test event `POST /webhook_endpoints/{webhook_endpoint_id}/test` sends a `ping` event to the endpoint now, whatever its `events` filter. Use it to check your signature code before a real event arrives; the delivery shows up in the endpoint's deliveries. ```bash curl -X POST https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/test \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ## Next steps - [Event types](https://submitator.com/docs/webhooks/event-types): every event and what its `data` holds. - [Retries and failures](https://submitator.com/docs/webhooks/retries-and-failures): what counts as delivered, and the retry schedule. - [Receive webhooks](https://submitator.com/docs/guides/receive-webhooks): an endpoint from start to finish. --- # Event types URL: https://submitator.com/docs/webhooks/event-types > The 15 events a webhook endpoint can receive, when each one is sent, and what its data holds. Every delivery's body is an event, the same object `GET /events` returns. Its `type` is always `.`, and `data.previous_status` holds the status before the change. listing.live: ```json { "object": "event", "id": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ", "type": "listing.live", "created_at": "2026-10-08T14:17:01Z", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "data": { "object": { "object": "listing", "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "directory": { "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF", "name": "BetaList", "domain_rating": 73, "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm" }, "status": "live", "reason": null, "action": null, "live_url": "https://betalist.com/startups/ledgerly", "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9", "created_at": "2026-10-03T14:00:00Z", "submitted_at": "2026-10-04T09:00:00Z", "live_at": "2026-10-08T14:00:00Z" }, "previous_status": "submitted" } } ``` ## The event object | Field | What it holds | | --- | --- | | `id` | The event's id, which is also the `webhook-id` header of its deliveries. | | `type` | One of the types below. | | `created_at` | When the change was recorded, exact to the second and within about a minute of the change. | | `livemode` | `true` for live events, `false` for test events. | | `project` | The project the event is about, or `null` for `ping`. | | `data.object` | The project, listing, report or webhook endpoint right after the change. | | `data.previous_status` | The status before the change, or `null` for `project.listings_added` and `ping`. | | `data.listings_created` | On `project.launched` only: how many listings the launch created. | | `data.listings_added` | On `project.listings_added` only: how many listings were added. | Listing times inside `data.object` stay rounded down to the hour, as everywhere else. ## Project events | Type | Sent when | | --- | --- | | `project.launched` | A project launches. It is the launch's only event: `data.listings_created` counts the new listings, all in `pending`, and `data.previous_status` is `draft`. | | `project.listings_added` | Directories are added to a launched project, by `POST /projects/{project_id}/listings` or by auto-replace. `data.listings_added` counts the new listings. | | `project.in_progress` | A project moves again after `action_required`, `on_hold` or `completed`. A launch does not send it. | | `project.action_required` | A project needs you or your client. `data.object.action` says what and who, and `client_message` is ready to forward. | | `project.on_hold` | Work on a project pauses. `data.object.hold_reason` is `review` while we review the project, which clears without action from you, or `paused`. | | `project.completed` | No listing is `pending`, `in_progress` or `action_required`, and auto-replace has nothing to add. Listings in `submitted` can still go live. | ## Listing events | Type | Sent when | | --- | --- | | `listing.in_progress` | A listing leaves `pending`, or moves on after `action_required`. | | `listing.action_required` | A listing waits on you or your client. For `install_badge`, forward `client_message` to your client and verify the badge once it is on the site. | | `listing.submitted` | The directory has the listing and reviews it. Also sent, with `data.previous_status` `live`, when a live listing goes back to review. | | `listing.live` | The listing is published. `data.object.live_url` points to it, or is `null` when it went live without a link. | | `listing.not_accepted` | The directory declined the listing, could not take it, or took a live listing down. `data.object.reason` says which, and the place in the allowance comes back. | | `listing.cancelled` | We withdrew the listing before it reached the directory. The place in the allowance comes back. | A new listing sends no event of its own: `project.launched` and `project.listings_added` count them. A listing can go `live` without a `listing.submitted` first. ## Report events | Type | Sent when | | --- | --- | | `report.ready` | A report has been built. Download it with `GET /reports/{report_id}/file` before `data.object.expires_at`, 7 days later. | | `report.failed` | A report could not be built. Start a new one, and write to support with the event's id if it fails again. | ## The test event | Type | Sent when | | --- | --- | | `ping` | You send a test event with `POST /webhook_endpoints/{webhook_endpoint_id}/test` or the console's test button. It goes to that endpoint only, whatever its `events` filter, and `data.object` is the endpoint. | ## Choose what an endpoint receives An endpoint's `events` lists the types it receives: types such as `listing.live`, groups such as `listing.*`, `project.*` and `report.*`, or `["*"]` for every type, which is the default. A new endpoint receives the events created after it, not the ones before. `PATCH /webhook_endpoints/{webhook_endpoint_id}` with a new `events` list replaces the whole list. ## Order and repeats Deliveries can arrive out of order, and the same event can arrive more than once. Store each `webhook-id` and skip the ones you have handled. Before you act on an event, compare `data.previous_status` with what you stored, or read the object again with its id. A status can change after it looked final: [How it works](https://submitator.com/docs/how-it-works#corrections) lists the corrections, and each sends its own event. New event types can appear, so answer 2xx to a type you do not know and ignore it. ## Next steps - [Signatures](https://submitator.com/docs/webhooks/signatures): check that a delivery came from us. - [Retries and failures](https://submitator.com/docs/webhooks/retries-and-failures): what counts as delivered, and what happens when it is not. - [How it works](https://submitator.com/docs/how-it-works): the statuses behind the events. - [Keep your data in sync](https://submitator.com/docs/guides/keep-your-data-in-sync): webhooks and the events feed together. --- # Retries and failures URL: https://submitator.com/docs/webhooks/retries-and-failures > Answer 2xx within 10 seconds. A delivery is tried up to 7 times over about 33 hours, and an endpoint that fails for 72 hours is disabled until you enable it again. ## What counts as delivered An attempt succeeds when your endpoint answers any 2xx status within 10 seconds, with 5 seconds to connect. Any other status, a timeout, a failed connection, a TLS error or a redirect is a failed attempt. Deliveries do not follow redirects, so register the final URL. Answer first and work later: store the event, queue what it starts and return 204. Work that takes longer than 10 seconds makes a delivered event look failed, and it comes again. ## The retry schedule A failed attempt is tried again after a wait that grows each time. Each wait counts from the attempt before it. | Attempt | When | | --- | --- | | 1 | Right after the event is recorded. | | 2 | 1 minute after attempt 1. | | 3 | 5 minutes after attempt 2. | | 4 | 30 minutes after attempt 3. | | 5 | 2 hours after attempt 4. | | 6 | 6 hours after attempt 5. | | 7 | 24 hours after attempt 6. | When attempt 7 fails, about 33 hours after the event, the delivery is `failed`. The event stays in `GET /events` for 90 days, so you can still read it from the feed. ## See your deliveries `GET /webhook_endpoints/{webhook_endpoint_id}/deliveries` lists the deliveries to one endpoint, newest first. Filter by `status`: `pending` while attempts remain, `succeeded` or `failed` once they end. ```bash curl "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/deliveries?status=pending" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` ```js const res = await fetch( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/deliveries?status=pending", { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } }, ); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT/deliveries", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, params={"status": "pending"}, ) print(res.json()) ``` Response 200: ```json { "object": "list", "data": [ { "object": "webhook_delivery", "id": "wd_3Cr8Kx2Wq7Lt4Vb9Nz1HmP", "livemode": false, "endpoint": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "event": "evt_6Lr3Kx8Wq2Nt7Vb1Rz5MpA", "event_type": "listing.action_required", "status": "pending", "attempts": 5, "next_attempt_at": "2026-10-08T17:49:31Z", "last_attempt": { "attempted_at": "2026-10-08T11:49:31Z", "http_status": null, "duration_ms": 10000, "error": "timeout" }, "created_at": "2026-10-08T09:13:30Z" } ], "has_more": false, "next_cursor": null } ``` `last_attempt.error` says why an attempt failed without a 2xx: `timeout`, `connection_failed`, `tls_failed`, `redirect` or `blocked_address`, when the host is not public. It is `null` when your endpoint answered, and `http_status` then holds the status it sent. The endpoint itself sums up the last 7 days in `delivery_summary`: attempts, successes, and the time and status of the last attempt. ## Send a delivery again `POST /webhook_deliveries/{webhook_delivery_id}/retry` sends a delivery again now, whatever its status. Use it once you have fixed your endpoint, for the deliveries that failed meanwhile. ```bash curl -X POST https://api.submitator.com/v1/webhook_deliveries/wd_3Cr8Kx2Wq7Lt4Vb9Nz1HmP/retry \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" ``` The endpoint must be enabled: a retry to a disabled endpoint returns 422 `validation_failed`. ## When an endpoint is disabled An endpoint with no successful delivery for 72 hours and at least 10 failed events is disabled: `enabled` becomes `false` and `disabled_reason` becomes `failing`. We email you when it happens. A disabled endpoint gets no deliveries, but events go on being recorded in `GET /events`. Fix the endpoint, enable it again, and read the feed from your last cursor to catch up on what it missed. ```bash curl -X PATCH https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": true}' ``` ```js const res = await fetch("https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ enabled: true }), }); console.log(await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.submitator.com/v1/webhook_endpoints/we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"}, json={"enabled": True}, ) print(res.json()) ``` Response 200 (some fields left out): ```json { "object": "webhook_endpoint", "id": "we_4Xk9Lm2Qt7Wr3Nb8Vz5HcT", "url": "https://hooks.northlight.test/listings", "enabled": true, "disabled_reason": null } ``` You can disable an endpoint yourself with `enabled` `false`: `disabled_reason` is then `requested`. Deleting an endpoint drops the deliveries still waiting for it, and its events stay in the feed. ## What does not count Deliveries to your endpoints do not count toward your [rate limit](https://submitator.com/docs/rate-limits). Your calls to read deliveries, retry them or change an endpoint do. ## What can go wrong | Code | Status | Fix | | --- | --- | --- | | [`endpoint_url_invalid`](https://submitator.com/docs/errors#endpoint_url_invalid) | 422 | The URL is not a public `https` URL, or holds a user name or password. | | [`validation_failed`](https://submitator.com/docs/errors#validation_failed) | 422 | A retry to a disabled endpoint, or an `events` value that is not a type or a group. `errors` says which. | | [`quota_exceeded`](https://submitator.com/docs/errors#quota_exceeded) | 422 | Before your first purchase, test mode allows 3 webhook endpoints. Delete one first. | | [`not_found`](https://submitator.com/docs/errors#not_found) | 404 | The endpoint or delivery belongs to the other mode, or was deleted. | ## Next steps - [Signatures](https://submitator.com/docs/webhooks/signatures): check that a delivery came from us. - [Event types](https://submitator.com/docs/webhooks/event-types): every event and what its `data` holds. --- # Error format URL: https://submitator.com/docs/error-format > Every 4xx and 5xx response has one shape. Branch on the code, show the message, log the request id. Every error, an unknown path and a body that is not JSON included, returns the same envelope: ```json { "error": { "code": "not_ready", "message": "Add the missing items, then launch again. Nothing was spent.", "errors": [ { "param": "contact_email", "code": "required", "message": "Add a contact email. Some directories register the listing to it." } ], "doc_url": "https://submitator.com/docs/errors#not_ready", "request_id": "6b0f2c9e-6a41-4c55-9d2a-0f0d3c1a8e77" } } ``` ## Fields | Field | Always there | What it holds | | --- | --- | --- | | `code` | Yes | The stable code. Branch on it; [Error codes](https://submitator.com/docs/errors) lists all 32. | | `message` | Yes | A sentence for people that says what happened and what to do. It can change, so never parse it. | | `doc_url` | Yes | The section of the error codes page for this code. | | `request_id` | Yes | The request's id, the same as the `X-Request-Id` header. Quote it when you write to support. | | `param` | No | The parameter at fault, when there is one. | | `errors` | No | Every field to fix, on `validation_failed`, `not_ready` and `invalid_directories`. | | `existing` | No | The project in the way, on `project_exists` and `already_launched`. | ## Field errors Each item of `errors` names one field in `param`, as a path such as `tagline`, `competitors[2].url` or `directories.include[0]`. Its `code` comes from this closed list: | Code | Meaning | | --- | --- | | `required` | The field is missing or empty. | | `invalid` | The value is not allowed here; `message` says why. | | `invalid_enum` | The value is not one of the listed values. | | `invalid_url` | Not an `http` or `https` URL. | | `not_public_url` | Live mode only: the host is an IP address or a reserved name such as `.test`. | | `invalid_email` | Not an email address. | | `too_short` | Shorter than the minimum length. | | `too_long` | Longer than the maximum length. | | `too_many` | The list has more items than allowed. | | `immutable` | The field cannot change any more, such as `contact_email` after launch. | | `file_too_large` | The image is larger than 5 MB. | | `unsupported_file_type` | The file is not a PNG, JPEG, GIF or WebP image. | | `import_failed` | We could not download an image from the URL. | ## Handle errors in your code - **4xx:** the request was wrong. Fix it before you send it again; a retry with the same body gets the same answer. - **409 `idempotency_key_in_use`:** the first request with this `Idempotency-Key` is still running. Retry in 1 second with the same key. - **429:** wait the seconds in `Retry-After`, then send the same request again. - **500 and 503:** retry with backoff, for example after 1, 2, 4 and 8 seconds. Send a `POST` again with the same `Idempotency-Key`, so it runs at most once. If it repeats, write to support with the `request_id`. Show `message` to the person who can fix the problem, and keep `code` and `request_id` in your logs. A failed launch spends nothing, and its message says so. ## HTTP statuses | Status | Codes | | --- | --- | | 400 | `invalid_json`, `invalid_query`, `unknown_parameter`, `invalid_cursor` | | 401 | `api_key_missing`, `api_key_invalid` | | 402 | `no_launches_left` | | 403 | `account_suspended`, `permission_denied`, `test_mode_only` | | 404 | `not_found`, `route_not_found` | | 405 | `method_not_allowed` | | 409 | `already_launched`, `project_exists`, `idempotency_key_in_use` | | 410 | `gone`, `cursor_expired` | | 415 | `unsupported_media_type` | | 422 | `validation_failed`, `not_ready`, `nothing_to_submit`, `invalid_directories`, `allowance_exhausted`, `badge_not_found`, `image_unreachable`, `endpoint_url_invalid`, `idempotency_key_reused`, `quota_exceeded` | | 429 | `rate_limited` | | 500 | `internal_error` | | 503 | `unavailable` | --- # Error codes URL: https://submitator.com/docs/errors > Every error code the API returns, with its HTTP status, what happened and how to fix it. Each code below is the `error.code` of a response, and each error's `doc_url` links to its section here. The list is closed: the API returns no other code. [Error format](https://submitator.com/docs/error-format) shows the shape of the body. ## invalid_json Status: 400 **What happened.** The body is not valid JSON. **How to fix.** Send a JSON object with `Content-Type: application/json`. ## invalid_query Status: 400 **What happened.** The query string cannot be read: a `%` is not followed by two hex digits. **How to fix.** Percent-encode the values, for example with `encodeURIComponent`. ## unknown_parameter Status: 400 **What happened.** A body field or query parameter is not part of this operation; `param` names it. **How to fix.** Remove it. The key sets the mode, so `livemode` is never a parameter. ## invalid_cursor Status: 400 **What happened.** The cursor was not issued for this list, or it was changed. **How to fix.** Send `next_cursor` exactly as you received it, to the same list. ## api_key_missing Status: 401 **What happened.** The request has no key. **How to fix.** Send `Authorization: Bearer` and your key. ## api_key_invalid Status: 401 **What happened.** The key is unknown, revoked or expired. **How to fix.** Use an active key from the console. ## no_launches_left Status: 402 **What happened.** The launch needs 1 launch and you have 0. Nothing was spent. **How to fix.** Buy launches in the console, then send the same request again. ## account_suspended Status: 403 **What happened.** Your account is suspended: it can read but not write. **How to fix.** Contact support. ## permission_denied Status: 403 **What happened.** A read-only key tried to write, or to read logins. **How to fix.** Use a key with full permissions. ## test_mode_only Status: 403 **What happened.** A live key called a test helper. **How to fix.** Call test helpers with a `sbm_test_` key. ## not_found Status: 404 **What happened.** Nothing with this id in the key's mode. **How to fix.** Check the id, and that the key's mode matches the object's. ## route_not_found Status: 404 **What happened.** No operation at this path. **How to fix.** Check the path against the reference. ## method_not_allowed Status: 405 **What happened.** The path exists, but not with this HTTP method. **How to fix.** Use a method the reference lists for the path. ## already_launched Status: 409 **What happened.** The project has launched, so it cannot launch again or be deleted; `existing` holds it. **How to fix.** Add directories with `POST /projects/{project_id}/listings` instead. ## project_exists Status: 409 **What happened.** Another project has the same `url`, `contact_email` or `external_id`; `param` names the field and `existing` holds that project. **How to fix.** Use `existing`, or change the field. ## idempotency_key_in_use Status: 409 **What happened.** A request with this `Idempotency-Key` is still running. **How to fix.** Retry in 1 second with the same key. ## gone Status: 410 **What happened.** The report file expired after 7 days, or the path belongs to a retired API. **How to fix.** Build a new report, or follow `doc_url` to the path that replaced it. ## cursor_expired Status: 410 **What happened.** The cursor points to events older than 90 days. **How to fix.** Read the objects you track again, then read the feed without a cursor. ## unsupported_media_type Status: 415 **What happened.** The body is not `application/json`, or for images not `multipart/form-data`. **How to fix.** Set `Content-Type` to match the body. ## validation_failed Status: 422 **What happened.** Fields are invalid; `errors` lists each one with its `param` and `code`. **How to fix.** Fix each field in `errors` and send the request again. ## not_ready Status: 422 **What happened.** The project misses something a launch needs; `errors` lists it. Nothing was spent. **How to fix.** Add what is missing. `readiness.missing` shows the same list. ## nothing_to_submit Status: 422 **What happened.** No directory in the catalog fits the project now. Nothing was spent. **How to fix.** Check `unlocks` and `not_matching` in the readiness preview, change the project, and try again. ## invalid_directories Status: 422 **What happened.** Some directory ids are unknown, outside the catalog, not open to the project or already used; `errors` lists them. Nothing was spent. **How to fix.** Remove them and send the request again. ## allowance_exhausted Status: 422 **What happened.** The project has no free allowance: listings use or reserve all of it, or it has not launched. **How to fix.** Wait for listings to end; `not_accepted` and `cancelled` listings give theirs back. ## badge_not_found Status: 422 **What happened.** We read the site and did not find the badge. **How to fix.** Run `check_command`, fix the install, and verify again. ## image_unreachable Status: 422 **What happened.** We could not download an image from the URL. **How to fix.** Check that the URL is public and returns an image, or upload the file instead. ## endpoint_url_invalid Status: 422 **What happened.** The webhook URL is not a public `https` URL. **How to fix.** Use `https`, a public host, and no user name or password in the URL. ## idempotency_key_reused Status: 422 **What happened.** This `Idempotency-Key` came with a different request before. **How to fix.** Use a new key for each new request. ## quota_exceeded Status: 422 **What happened.** Before your first purchase, test mode allows 25 projects, 100 new projects a day and 3 webhook endpoints. **How to fix.** Delete test data in the console, wait for the next day, or buy launches. ## rate_limited Status: 429 **What happened.** Too many requests this hour, or too many calls to an operation with its own limit. **How to fix.** Wait the seconds in `Retry-After`. ## internal_error Status: 500 **What happened.** Something failed on our side. **How to fix.** Retry with backoff; quote `request_id` if it repeats. ## unavailable Status: 503 **What happened.** The API is down for a short time. **How to fix.** Retry after the seconds in `Retry-After`. --- # Rate limits URL: https://submitator.com/docs/rate-limits > 3,600 requests per UTC hour for each account and mode, a few operations with limits of their own, and how to read the headers. ## Requests per hour Each account can make 3,600 requests per UTC hour in each mode, or 600 before your first purchase. The count starts again at the top of every hour. Webhook deliveries to your endpoints do not count toward it. Your own calls do, in the mode of the key that makes them. Every request your key authenticates gets the numbers for the current hour back in three headers. A path that does not exist (`route_not_found`) or a wrong method (`method_not_allowed`) is answered before the key is read, so those responses carry none of them. | Header | What it holds | | --- | --- | | `RateLimit-Limit` | Requests allowed this hour, such as `3600`. | | `RateLimit-Remaining` | Requests left this hour. | | `RateLimit-Reset` | Seconds until the hour ends and the count starts again. | `GET /account` returns the same numbers in `rate_limit`, with the reset as a time. ## Operations with their own limits | Operation | Limit | | --- | --- | | `POST /projects/{project_id}/badge/verify` | 10 per hour for each project. | | `POST /projects/{project_id}/reports` | 1 PDF every 30 seconds and 1 XLSX every 10 seconds for each project, and as many again with logins. | | `PUT /projects/{project_id}/logo` and `POST /projects/{project_id}/screenshots` with a `url` | 60 image imports per hour. | Uploads with `file` count only toward the hourly request limit. ## When you hit a limit The API answers 429 [`rate_limited`](https://submitator.com/docs/errors#rate_limited) with a `Retry-After` header. Wait that many seconds, then send the same request again. ```http HTTP/1.1 429 Too Many Requests Retry-After: 1460 RateLimit-Limit: 3600 RateLimit-Remaining: 0 RateLimit-Reset: 1460 ``` ```json { "error": { "code": "rate_limited", "message": "You sent 3,600 requests this hour. Try again in 1,460 seconds.", "doc_url": "https://submitator.com/docs/errors#rate_limited", "request_id": "c04d3fa7-d94d-40d0-bfc7-20614c362b82" } } ``` ## Stay under the limit - Receive events as [webhooks](https://submitator.com/docs/guides/receive-webhooks) instead of asking for them: deliveries cost you no requests. - Read the events feed with your last `next_cursor` instead of polling each project: 1 request returns up to 100 changes. - Ask for 100 items per page with `limit=100` when you read a whole list. - Check `RateLimit-Remaining` before a batch, and spread a batch over the hour when it would run out. ## Listings in progress Separate from request limits, up to 100 of your listings are in progress at once. A launch is always accepted: listings above that number wait in `pending` and start as others finish. `GET /account` shows the count in `capacity`. --- # Versioning URL: https://submitator.com/docs/versioning > v1 has been generally available since 2026-10-07. Breaking changes only ever arrive in a new version, /v2, with 6 months of overlap. The version is part of the path: every route starts with `https://api.submitator.com/v1`. There are no version headers and no dated versions. ## v1 is generally available v1 has been generally available since 2026-10-07, and the policy on this page applies to it. `GET /openapi.json` reports `info.version` `1.0.0` and returns the operations the reference shows. The [changelog](https://submitator.com/docs/changelog) dates every change since v1 opened on 2026-10-06. ## Breaking changes go to /v2 A change that can break working code only ever ships in a new version, such as `/v2`. When it does: - `/v1` keeps working for 6 months after `/v2` is released. - Responses from `/v1` carry `Deprecation` and `Sunset` headers with the dates. - The owner of every account with a key gets an email, and the dated [changelog](https://submitator.com/docs/changelog) lists each change. ## Changes that are not breaking These can arrive in v1 at any time, so build your integration to accept them: - New operations, new optional parameters and new fields in responses. - New values in the open lists: listing `reason`, `action.code`, `readiness.missing`, `unlocks[].requirement`, the badge recipe's `platform` and `language`, and a delivery's `last_attempt.error`. - New event types. Answer 2xx to a webhook of a type you do not know. - New wording in any `message`. Branch on `code`, never on the text. Ignore the fields you do not use, and handle a value you do not know: for an unknown `action.code`, show `client_message`, or a general prompt when it is `null`. --- # Changelog URL: https://submitator.com/docs/changelog > Every change to the v1 API that your code can notice, newest first, dated by the day it shipped. Each entry is dated in UTC and lists what changed for your integration. [Versioning](https://submitator.com/docs/versioning) says which changes can come to v1 and which only to a new version. ## 2026-11-21: a directory's organic traffic - **`monthly_organic_visits` on every catalog directory.** `GET /directories`, `GET /directories/{directory_id}` and `GET /projects/{project_id}/directories` return `monthly_organic_visits` on each directory: an estimate of the visits a month its site gets from Google search, worldwide, rounded to two significant figures. `100` means 100 or fewer, and `null` means no estimate above zero. The directory inside a listing or a login does not carry it. - **Search visits only.** A directory that lives on direct and social visitors gets more than this, and for an article platform the number is the whole platform's. - **It changes nothing a launch picks.** `"auto"`, `include`, `exclude` and auto-replace treat the directory as before. - **The console** shows a directory's organic traffic under its site in the catalog and on a project's Directories tab. ## 2026-11-15: directories that take only free products - **`free_only` on every catalog directory.** `GET /directories`, `GET /directories/{directory_id}` and `GET /projects/{project_id}/directories` return `free_only` on each directory: `true` when the directory takes only free products. It is a field of its own, so `audience` and `requires` keep their values, and the directory inside a listing or a login does not carry `free_only`. - **Closed to a product that is not free.** For a project whose `pricing_model` is not `free`, `"auto"`, `exclude` and auto-replace pass such a directory by, and `include` answers 422 [`invalid_directories`](https://submitator.com/docs/errors#invalid_directories) for it. `GET /projects/{project_id}/directories` shows it `locked` to a project not listed there yet, and its `message` is what `include` answers. `reason` is `free_only`, with the directory's name, then `takes only free products (pricing_model free).` as `message`, unless a missing contact email or the directory's audience closes it first. - **`not_matching.free_only` in the readiness preview.** `GET /projects/{project_id}/readiness` counts these directories in `not_matching.free_only`. - **Only a `pricing_model` of `free` opens them.** `freemium`, `open_source`, `paid` and `null` do not. Set it to `free` only when the product is free. - **`audience=any` leaves them out.** `GET /directories?audience=any` returns the directories that take every product: `audience` is empty and `free_only` is `false`. `requires=none` is unchanged. - **Read before `under_maintenance`.** Like a missing contact email, the directory's audience and a reason no project field changes (`other`), `free_only` closes a directory first: one that takes only free products and is turned off shows `reason` `free_only` to a project whose `pricing_model` is not `free`. - **The console** marks such a directory Free products only in the catalog and on a project's Directories tab, and shows it locked as Takes free products only to a project that is not free. ## 2026-11-15: a launch covers up to 110 directories - **110 directories per launch.** Every launch from 15 November 2026 covers up to 110 directories, including launches you bought earlier and have not used yet. Projects launched before keep 100; `allowance.total` says which. - **`limit` and `include` follow.** `limit` in `GET /projects/{project_id}/readiness` and `GET /projects/{project_id}/directories` is 110 for a draft, and `include` takes up to 110 directories. Read `allowance.total` and `limit` rather than assuming 100. - **Test mode follows at once.** Test projects, also ones launched earlier, read `allowance.total` 110, and auto-replace fills the difference. - **Unchanged:** up to 100 of your listings are in progress at once, and the rest start as others finish. ## 2026-11-11: directories turned off while we tune them - **`under_maintenance` on every catalog directory.** `GET /directories`, `GET /directories/{directory_id}` and `GET /projects/{project_id}/directories` return `under_maintenance` on each directory: `true` while the directory is temporarily turned off because we are tuning it. Such a directory stays in the catalog, and the directory inside a listing or a login does not carry `under_maintenance`. - **No new listings there until it is back.** `"auto"`, `exclude` and auto-replace skip it, and `include` answers 422 [`invalid_directories`](https://submitator.com/docs/errors#invalid_directories) for it. `GET /projects/{project_id}/directories` shows it `locked` to a project not listed there yet, and its `message` is what `include` answers. `reason` is `under_maintenance`, unless a missing contact email, the directory's audience or a reason no project field changes (`other`) closes it first. No change to the project opens it while it is turned off. Once it is back, a directory locked with `under_maintenance` opens on its own, unless the project lacks something the directory requires (`directory.requires`): `reason` then names that, or `other` when it lacks more than one. - **The console** marks such a directory Under maintenance in the catalog and on a project's Directories tab. ## 2026-10-28: what a directory's dofollow link depends on - **`backlink_condition` on every catalog directory.** `GET /directories`, `GET /directories/{directory_id}` and `GET /projects/{project_id}/directories` return `backlink_condition`: `badge` when the directory links `dofollow` only while its badge is on the product's site, and `nofollow` without it; `null` otherwise. `backlink` stays `dofollow` for these directories. New values can appear. - **Verify the badge first.** A listing at such a directory goes out with the badge only when the project's badge is verified at that time. Verify it before you launch or add these directories. See [Install the badge](https://submitator.com/docs/guides/install-the-badge#5-verify-it). - **The console** marks such a directory Dofollow with badge in the catalog and on a project's Directories tab. ## 2026-10-21: a sign that a directory might be outdated - **`outdated` on every catalog directory.** `GET /directories`, `GET /directories/{directory_id}` and `GET /projects/{project_id}/directories` return `outdated` on each directory: `true` when it lately seems to publish few new products. It is a sign, not a verdict: `"auto"`, `include`, `exclude` and auto-replace treat the directory as before, and the directory inside a listing or a login does not carry it. - **The console** marks such a directory Outdated in the catalog and on a project's Directories tab. ## 2026-10-10: pick your clients' directories - **A project's directory choices.** `GET /projects/{project_id}/directories` lists every directory of the catalog with what it is to the project: `suggested` for what `"auto"` takes now, up to `limit`, `open` for the others you can name in `include`, and `excluded`, `listed` or `locked`, where a locked one comes with a `reason` and a `message`. `limit` is 100 for a draft and the free allowance once the project has launched. See [Launch and track](https://submitator.com/docs/guides/launch-and-track) and [Directories](https://submitator.com/docs/api/directories). - **`kind` on every directory.** A directory, the one inside a listing included, carries `kind`: `directory`, or `article` for an article platform, where the listing is a post about the product. `GET /directories` takes `kind` as a filter. Events recorded before this change keep their listing as it was, without `kind`. - **Article platforms by `include`.** Dev.to, Medium and Hashnode join the catalog after your first purchase. A launch or an add takes one only when you name it in `include`: `"auto"`, `exclude` and auto-replace never do. See [Reach more directories](https://submitator.com/docs/guides/reach-more-directories). - **`excluded_directories` on a launch and an add.** `POST /projects/{project_id}/launch` and `POST /projects/{project_id}/listings` take it and replace the project's list together with the launch or the add, so a request that fails leaves the list as it was. - **The console** has a Directories tab on each project. It shows the same choices, and launches or adds exactly the directories you check. ## 2026-10-07: logins for your clients' directory accounts - **Logins.** `GET /projects/{project_id}/logins` lists the accounts created for your client on directories that need one: where each signs in, its email and username, whether it is ready, and the one password they all use. `GET /listings/{listing_id}/emails` returns up to 25 emails the directory sent to a login, for a confirmation code or a password reset link. See [Logins](https://submitator.com/docs/api/logins). - **Reports with logins.** `POST /projects/{project_id}/reports` takes `include_logins: true` to add the logins and their password: a Directory logins page in the PDF, a Logins sheet in the XLSX. A report's `include_logins` says which kind it is, and a share link's page never offers one with logins. See [Reports for clients](https://submitator.com/docs/guides/reports-for-clients#5-include-the-logins). - **Read-only keys read everything but logins.** Both operations, and the file of a report with logins, answer a read-only key with 403 `permission_denied`. - **Test mode** returns placeholder logins with a password made from the project's id, and sample emails whose links point to `login.test`; nothing signs up anywhere. A report with logins is the sample report with sample logins on `.test` addresses. ## 2026-10-07: v1 is generally available - **The beta is over.** v1 now follows the [versioning policy](https://submitator.com/docs/versioning): a change that can break working code only ships in a new version, such as `/v2`, with 6 months of overlap. - **`GET /openapi.json` reports `info.version` `1.0.0`**, where it said `1.0.0-beta`. Operations, fields and error codes stay as they were. ## 2026-10-07: share links for your clients - **Share links.** `POST /projects/{project_id}/share_link` returns a read-only progress page you can send to your client: your agency's name and colors, the live listings with their links, what is still in progress, and the latest PDF and XLSX. A project has 1 active link; creating a new one turns the previous URL off, and `DELETE` turns it off. See [Share links](https://submitator.com/docs/api/share-links). - **A new error code:** `invalid_query`, 400, when a query string cannot be read because a `%` is not followed by two hex digits. ## 2026-10-07: test mode, webhooks and idempotency keys - **Test mode.** A `sbm_test_` key is free from the day you create your agency and runs every call on test data, where listings move on their own and nothing is spent. Two test helpers move a listing and set your test launches. See [Test mode](https://submitator.com/docs/test-mode). - **Webhooks.** `POST /webhook_endpoints` registers an HTTPS URL that receives events as they happen, signed as Standard Webhooks describes. A delivery is tried up to 7 times over about 33 hours. See [Signatures](https://submitator.com/docs/webhooks/signatures), [Event types](https://submitator.com/docs/webhooks/event-types) and [Retries and failures](https://submitator.com/docs/webhooks/retries-and-failures). - **Idempotency-Key.** Creating a project, launching, adding directories, building a report and adding a webhook endpoint accept the header. A retry with the same key and body within 24 hours returns the first response and changes nothing twice. - **Read-only keys.** `key.permissions` can be `read_only`. Such a key reads everything and gets 403 `permission_denied` on any write. - **New error codes:** `permission_denied`, `test_mode_only`, `idempotency_key_in_use`, `endpoint_url_invalid`, `idempotency_key_reused` and `quota_exceeded`. - **A new event type:** `ping`, sent only when you test an endpoint. - **New id prefixes:** `we_` for webhook endpoints and `wd_` for deliveries. ## 2026-10-06: v1 beta - **v1 opens in beta** at `https://api.submitator.com/v1`, for agencies: projects, images, the readiness preview, launches, listings, the badge, reports, events and the directory catalog. - **Keys start with `sbm_live_`** and come with your first purchase. Create them in the console under Developers. - **The docs are public** at submitator.com/docs. The reference is built from the same contract the API serves at `GET /openapi.json`. - **The partner API at `/api/partner/v1` is retired** and answers 410 `gone`. --- # For AI agents URL: https://submitator.com/docs/for-ai-agents > Every page as Markdown, all the docs in one file and the OpenAPI document, for AI assistants and coding agents that build with the API. These docs come in forms that AI assistants and coding agents read well. Point your tool at them, or paste a page into a chat, when you build an integration. ## The docs as Markdown | What | Where | | --- | --- | | Any page | Its URL with `.md` added, such as `https://submitator.com/docs/quickstart.md`. The docs home is `https://submitator.com/docs.md`. | | The index | `https://submitator.com/llms.txt` lists every page with one line about it, in the order of the sidebar. | | Everything in one file | `https://submitator.com/llms-full.txt` holds every page, the reference included. | Each page also has 3 buttons under its title. **Copy as Markdown** puts the page on your clipboard, **Open in Claude** starts a chat with Claude that reads the page, and **View as Markdown** opens the twin. ## The OpenAPI document `GET https://api.submitator.com/v1/openapi.json` returns the reference as an OpenAPI 3.1 document, with the operations that are released. It needs no key, so a tool that generates clients or calls APIs can load it directly. ## The MCP server To work with the API from a chat instead of writing code, connect your assistant to the [MCP server](https://submitator.com/docs/mcp). It runs on your machine with `npx -y submitator-mcp`, or remotely at `https://mcp.submitator.com/mcp`. ## A brief for your coding agent These rules keep generated code in line with what the API expects. Paste them into your agent's instructions: ```text You are building a client for the Submitator API at https://api.submitator.com/v1. Docs: https://submitator.com/llms-full.txt. OpenAPI: https://api.submitator.com/v1/openapi.json. - Read the key from the SUBMITATOR_API_KEY environment variable and send it as "Authorization: Bearer" and the key. Never print it, log it or write it into code. - Build and test with a sbm_test_ key: test mode spends nothing. - Call the API from your server or from a tool on your own machine, never from a browser page or an app you ship to others: the key would go out with it. The API sends no CORS headers. - Treat ids such as prj_... as opaque strings, and store them as text. - On an error, branch on error.code, never on error.message, and log error.request_id. - Send an Idempotency-Key with every POST you may retry, and the same key on the retry. - Page through lists by sending next_cursor back as cursor. - Check every webhook's signature with the official Standard Webhooks library before trusting it, and skip a webhook-id you have handled. - A launch spends 1 launch and cannot be undone. Check GET /projects/{project_id}/readiness first. ``` ## Keep keys out of chats Never paste a key into a chat or a prompt. Give the agent the name of the variable, and let your code read its value. If a key reached a chat, roll it in the console with "now" before you go on. An assistant that works through the [MCP server](https://submitator.com/docs/mcp) needs no key in the chat either: its MCP client keeps the key in its config on your own machine, or receives it only inside encrypted tokens when it signs in, and the model never sees it. Never put a key in an app you ship to others, a browser page or a repository. --- # Support URL: https://submitator.com/docs/support > Write to support@submitator.com with the request id, and never with your key. Write to [support@submitator.com](mailto:support@submitator.com) about the API, your account or a listing. ## What to send A request id lets us find the exact call in our logs. Send as many of these as you have: - The `request_id` from the error body, or the `X-Request-Id` header of the response. - The time of the call in UTC, and the method and path, such as `POST /v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/launch`. - The ids involved: `prj_`, `lst_` or `dir_`. - The key's id from `GET /ping`, such as `key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW`. For a webhook that did not arrive, send the endpoint's `we_` id and the delivery's `wd_` id from its deliveries as well. Never send the key itself. If a key was shared by mistake, roll it in the console with "now" before you write. ## Before you write - [Error codes](https://submitator.com/docs/errors) say what each code means and how to fix it. - [How it works](https://submitator.com/docs/how-it-works) explains every listing status and how long listings take. - [Rate limits](https://submitator.com/docs/rate-limits) cover 429 answers and `Retry-After`.