Everything GEOboom does for an organisation, over HTTPS and JSON: the same operations the app and the MCP server use. Every one is listed below with its inputs; the full schemas, outputs included, are public at https://api.geoboom.io/v1/openapi.json.
Authentication
An owner makes a key in Settings → Integrations and chooses what it may do. It starts with gbk_ and is shown once. Send it on every call:
curl https://api.geoboom.io/v1/org \
-H "Authorization: Bearer gbk_..."A key acts for the person who made it, in one organisation. An owner sees each key's calls in Settings → Integrations, and can pause or revoke it there at any time.
Permissions
| Scope | Allows |
|---|---|
read | See everything: projects, campaigns, prospects, publishers, contacts, deals and the inbox, threads included. |
campaigns:write | Create and change projects and campaigns, set up prospecting, import URLs and decide which fit, edit drafts. |
prospecting:spend | Spend: run prospecting, set monthly credit budgets, turn on automatic scheduling. |
mail:send | Reach publishers: reply on threads, send first emails, launch or resume a campaign. Sent email cannot be taken back. |
deals:write | Write deals down: terms, prices, paid, placements and whether they are live. |
Some things stay with people in the app, whatever the scopes: inviting and removing members, making or widening keys and connections, deleting projects and campaigns, and billing. Archiving and pausing are allowed; deleting is not.
Requests and answers
The base URL is https://api.geoboom.io/v1. Inputs go in the path and query string for GET, and as a JSON body otherwise. Answers are JSON. Every answer carries an x-request-id header; quote it if you write to us.
Idempotency
An operation that reaches a person outside GEOboom (outward) or commits credits (spend) needs an Idempotency-Key header. Make one per intended action, a UUID is ideal, and send it unchanged on every retry of that action:
curl -X POST https://api.geoboom.io/v1/threads/{conversationId}/replies \
-H "Authorization: Bearer gbk_..." \
-H "Idempotency-Key: 6f1c2a9e-4b7d-4e0a-9c55-2d8f1e3b7a10" \
-H "Content-Type: application/json" \
-d '{"topicKey": "...", "seenMessageId": "...", "bodyText": "..."}'- A retry with the same key gets the first call's answer, marked
Idempotent-Replayed: true, instead of a second email or a second charge. Keys are kept for 7 days. - The same key with a different request is refused (
idempotency_mismatch); a retry while the first call is still running is told to wait (in_progress). - GEOboom also checks the thing itself, whatever the key: an identical reply on the same thread within 24 hours is refused, and so is a reply when a newer message arrived than
seenMessageId.
Some operations ask before they commit: campaigns.resume and drafts.send answer with the cost first when there is one, and go ahead when called again with it agreed.
Long work
prospecting.run returns at once with a jobId. Follow it with jobs.get, which says queued, running, done or failed, and read the run's counters with prospecting.latestRun.
Limits and errors
Each key may call each operation 600 times a minute for reads, 120 for writes and 30 for spending and sending, and an organisation 3000 times a minute in all. Past that, calls are refused with 429 and a Retry-After header.
A refusal is a problem document with a stable code, a detail written for whoever reads it, and a requestId. Every code is explained, with what to do about it.
Versions
The API only grows within v1: operations and fields are added, never renamed or removed while in use. A value described as an open set may gain new members, so treat one you do not know as "other".
Operations
Each is also an MCP tool, named with an underscore: deals.create is deals_create. Reads first in each area, then what changes things.
Organisation
Who you are acting for: credits, activation, mailboxes.
org.get
GET /v1/org · MCP org_get · scope read
This organisation: name, whether it is activated, its default writing language, its credits (balance, reserved by scheduled outreach, available) and whether sending is paused for billing, and how many mailboxes it sends from.
Returns id, name, slug, activated, defaultLanguage, credits, paused, mailboxes.
Projects
One per brand being promoted, with its budget and the mailboxes it sends from.
projects.list
GET /v1/projects · MCP projects_list · scope read
List this organisation's projects — one per brand being promoted — with outreach counts: URLs, publishers written to, replies, deals, live placements, threads needing action, and this month's budget.
Returns rows, totals.
projects.get
GET /v1/projects/{projectId} · MCP projects_get · scope read
One project's facts (brand, site, pitch, location), its budget, and which mailboxes it sends from.
projectId required | string (uuid) |
|---|
Returns id, name, brandName, brandUrl, brandContext, pitchType, clientLocation, postalAddress, creditAllowance, mailboxes.
projects.create
POST /v1/projects · MCP projects_create · scope campaigns:write
Make a project for a client brand. Every mailbox of the organisation is enabled for it; its site is crawled once. Make a campaign in it next.
Changes data in GEOboom.
name required | string, up to 200 |
|---|---|
brandName required | string, up to 200 |
brandUrl | string, up to 2000 |
brandContext | string, up to 10000 |
pitchType | "exchange" | "exchange_or_paid" | "paid" — Default "exchange_or_paid". |
clientLocation | string, up to 200 |
postalAddress | string, up to 1000 |
Returns id, name, brandName, brandUrl, brandContext, pitchType, clientLocation, postalAddress, creditAllowance, mailboxes.
projects.update
PATCH /v1/projects/{projectId} · MCP projects_update · scope campaigns:write
Change a project's facts: name, brand, site, context, pitch type, location, address. Only the fields sent change.
Changes data in GEOboom.
projectId required | string (uuid) |
|---|---|
name | string, up to 200 |
brandName | string, up to 200 |
brandUrl | string, up to 2000 |
brandContext | string, up to 10000 |
pitchType | "exchange" | "exchange_or_paid" | "paid" |
clientLocation | string, up to 200 |
postalAddress | string, up to 1000 |
Returns id, name, brandName, brandUrl, brandContext, pitchType, clientLocation, postalAddress, creditAllowance, mailboxes.
projects.setAllowance
POST /v1/projects/{projectId}/allowance · MCP projects_setAllowance · scope prospecting:spend
Set the whole credits a month a project may commit to new publishers; null is the default.
Changes data in GEOboom.
projectId required | string (uuid) |
|---|---|
credits required | number | null |
Returns creditAllowance.
projects.setMailboxes
PUT /v1/projects/{projectId}/mailboxes · MCP projects_setMailboxes · scope campaigns:write
Replace the set of mailboxes a project sends from, with the role each sender signs with. Mailboxes left out stop sending for this project.
Changes data in GEOboom.
projectId required | string (uuid) |
|---|---|
mailboxes required | array of object |
mailboxes[].id required | string (uuid) |
mailboxes[].senderTitle | string, up to 200 — Default "". |
Returns mailboxes.
Campaigns
Groups of prospect URLs pitched together: settings, launching, pausing, budgets.
campaigns.get
GET /v1/campaigns/{campaignId} · MCP campaigns_get · scope read
One campaign's settings (name, kind, pitch, templates, mailboxes, send rules, budget, paused) and the templates and mailboxes it may be set to.
campaignId required | string (uuid) |
|---|
Returns id, projectId, name, kind, paused, launchedAt, archived, pitch, templates, mailboxIds, sendRules, excludeCompetitors, autoFilter, autoSchedule, rankBy, creditAllowance, options, followUpGapDays.
campaigns.list
GET /v1/projects/{projectId}/campaigns · MCP campaigns_list · scope read
List a project's campaigns (groups of prospect URLs pitched together) with their progress: URLs, publishers, emails sent and to send, replies, deals, budget, today's sending share, and daily output for the last days.
projectId required | string (uuid) |
|---|
Returns rows, days.
campaigns.update
PATCH /v1/campaigns/{campaignId} · MCP campaigns_update · scope campaigns:write
Change a campaign's settings: name, kind, pitch type, templates, mailboxes, send rules, competitor exclusion, auto-filter, ranking, archived. Only the fields sent change. Returns the settings as they now are.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
name | string, up to 200 |
kind | "links" | "geo" |
pitchType | "exchange" | "exchange_or_paid" | "paid" | null — What it offers publishers; null follows the project. Changes which templates auto mode sends |
templateMode | "auto" | "manual" |
templateIds | array of string (uuid) — The manual list, in the order a batch deals them; used when templateMode is manual |
mailboxIds | array of string (uuid) — Mailboxes it sends from, of the project's; empty means all |
sendRules | object |
sendRules.publisherLimit | number | null — Most people written to at one publisher, 1–50 |
sendRules.publisherGapDays | number | null — Days between people at one publisher, 0–365; null is the default |
sendRules.includeCatchAll | boolean |
sendRules.donorPageLimit | number | null |
excludeCompetitors | boolean | null — null follows the pitch: on for paid |
archived | boolean |
autoFilter | boolean — Decide undecided URLs by the campaign's rules as facts arrive |
rankBy | object — A column key from the import, `rank`, or `position` |
rankBy.key required | string |
rankBy.dir required | "asc" | "desc" |
Returns id, projectId, name, kind, paused, launchedAt, archived, pitch, templates, mailboxIds, sendRules, excludeCompetitors, autoFilter, autoSchedule, rankBy, creditAllowance.
campaigns.setAllowance
POST /v1/campaigns/{campaignId}/allowance · MCP campaigns_setAllowance · scope prospecting:spend
Set the whole credits a month a campaign may commit to new publishers; null is the default.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
credits required | number | null |
Returns creditAllowance.
campaigns.setAutoSchedule
POST /v1/campaigns/{campaignId}/auto-schedule · MCP campaigns_setAutoSchedule · scope prospecting:spend
Turn automatic scheduling of a campaign's fits on or off.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
autoSchedule required | boolean |
Returns autoSchedule.
campaigns.pause
POST /v1/campaigns/{campaignId}/pause · MCP campaigns_pause · scope campaigns:write
Pause a campaign: nothing more is sent from it until it is resumed. Research carries on and nothing queued is lost; replies still arrive. Pausing a paused campaign changes nothing.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|
Returns paused, held.
campaigns.resume
POST /v1/campaigns/{campaignId}/resume · MCP campaigns_resume · scope mail:send
Launch or resume a campaign. If resuming commits credits, the first call answers with the cost and the credit picture instead; call again with that cost as agreedCost to go ahead.
Commits the organisation's credits. Needs an idempotency key.
campaignId required | string (uuid) |
|---|---|
agreedCost | number — The cost a previous call answered with, to go ahead |
campaigns.create
POST /v1/projects/{projectId}/campaigns · MCP campaigns_create · scope campaigns:write
Make a campaign in a project. It starts paused, with no URLs; import into it, then launch it in the app.
Changes data in GEOboom.
projectId required | string (uuid) |
|---|---|
name | string, up to 200 — Default "". |
kind | "links" | "geo" — links: placements; geo: answers in AI engines Default "links". |
creditAllowance | number | null — Whole credits a month it may commit; null is the default |
excludeCompetitors | boolean — Leave out publishers whose own site is a competitor |
Returns id, projectId, name, kind, paused, launchedAt, archived, pitch, templates, mailboxIds, sendRules, excludeCompetitors, autoFilter, autoSchedule, rankBy, creditAllowance.
Prospecting
Where a campaign's prospects come from: keywords, AI answers' citations, SE Ranking, or your own list.
prospecting.get
GET /v1/campaigns/{campaignId}/prospecting · MCP prospecting_get · scope read
How a campaign gets its prospects: which source is live (manual, seranking, keywords or prompts) and each source's setup and last run. Only the live source adds prospects on its schedule.
campaignId required | string (uuid) |
|---|
Returns mode, manual, seranking, keywords, prompts.
prospecting.latestRun
GET /v1/campaigns/{campaignId}/prospecting/runs/latest · MCP prospecting_latestRun · scope read
A campaign's newest prospecting run, with its progress counters. Pass `after` (startedAfter from prospecting.run) to get only the run you started: null means it has not begun yet. Finished when finishedAt is set.
campaignId required | string (uuid) |
|---|---|
after | string |
Returns run.
prospecting.saveKeywords
PUT /v1/campaigns/{campaignId}/prospecting/keywords · MCP prospecting_saveKeywords · scope campaigns:write
Set up a campaign's keyword source: up to 1000 keywords whose search results are read for prospects, how deep to read (serpDepth 10–100), how many candidates to keep (topN 10–5000), how often to run on its own (off, weekly, monthly) and the market. Replaces the previous list. Running it is prospecting.run.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
keywords required | string | array of string, up to 500 — Keywords: an array, or one per line |
serpDepth | number — Default 20. |
topN | number — Default 500. |
schedule | string — Default "off". |
market | string — A market code: US, GB, CA, AU, DE, FR, ES, UA. Anything else means US. Default "US". |
languageCode | string, up to 10 — Default "en". |
Returns count.
prospecting.setMode
PUT /v1/campaigns/{campaignId}/prospecting/mode · MCP prospecting_setMode · scope campaigns:write
Choose which source adds prospects to a campaign on its schedule: manual (nobody), seranking, keywords or prompts. The source must be set up first. Other sources keep their setup.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
mode required | string |
Returns mode.
prospecting.savePrompts
PUT /v1/campaigns/{campaignId}/prospecting/prompts · MCP prospecting_savePrompts · scope campaigns:write
Set up a campaign's prompt source: up to 500 questions put to AI answer engines (chatgpt), whose cited pages become prospects; how many to keep (topN 10–5000), how far back the answer count looks (windowDays 1–365), how often to run on its own (off, daily, weekly, monthly) and the market. Replaces the previous list. Running it is prospecting.run.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
prompts required | string | array of string, up to 500 — Prompts: an array, or one per line |
engines | array of string — Default []. |
topN | number — Default 500. |
windowDays | number — Default 30. |
schedule | string — Default "off". |
market | string — A market code: US, GB, CA, AU, DE, FR, ES, UA. Anything else means US. Default "US". |
languageCode | string, up to 10 — Default "en". |
Returns count.
prospecting.run
POST /v1/campaigns/{campaignId}/prospecting/runs · MCP prospecting_run · scope prospecting:spend
Run a campaign's keyword or prompt source now: search results or AI answers are bought, their pages scored, and the best become prospects to decide on. Returns at once; follow it with jobs.get (jobId) and prospecting.latestRun (after = startedAfter). One run at a time per campaign.
Commits the organisation's credits. Needs an idempotency key.
campaignId required | string (uuid) |
|---|---|
source required | "keywords" | "prompts" — Which source to run; it need not be the live one |
Returns jobId, startedAfter.
Prospects
A campaign's URLs: importing them, deciding which fit, and the auto-filter.
prospects.planAutoFilter
GET /v1/campaigns/{campaignId}/auto-filter · MCP prospects_planAutoFilter · scope read
What the auto-filter would decide for a campaign's undecided URLs: how many become fits, how many are ruled out and by which rule, and how many it cannot decide yet and why.
campaignId required | string (uuid) |
|---|
Returns undecided, fit, notFit, leftAlone, drFloor, ownDomain, ownDomainRating, competitors.
prospects.list
GET /v1/campaigns/{campaignId}/prospects · MCP prospects_list · scope read
A campaign's prospect URLs, filtered by where they stand (undecided, fit, not_fit, scheduled, all_fit, all), most valuable first. Each row says whether its verdict can still be changed.
campaignId required | string (uuid) |
|---|---|
state | string — One of undecided, fit, not_fit, scheduled, all_fit, all. Anything else, or nothing, means undecided. |
sort | string — One of value, position, dr. Anything else, or nothing, means value. |
page | integer 1–9007199254740991 |
size | integer 1–100 |
Returns rows, total, counts, applied.
prospects.autoFilter
POST /v1/campaigns/{campaignId}/auto-filter · MCP prospects_autoFilter · scope campaigns:write
Decide a campaign's undecided URLs by its rules (see planAutoFilter). URLs missing a fact stay undecided, and the fact is asked for; run it again later to decide them.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|
Returns fit, notFit, asked.
prospects.markCompetitor
POST /v1/campaigns/{campaignId}/competitors · MCP prospects_markCompetitor · scope campaigns:write
Say whether these URLs' publishers are the client's competitors, overruling the automatic check. Verdicts do not change; the auto-filter uses the answer for URLs not decided yet.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
targetIds required | array of string (uuid) |
competitor required | boolean |
Returns domains.
prospects.import
POST /v1/campaigns/{campaignId}/prospects · MCP prospects_import · scope campaigns:write
Add URLs to a campaign: `urls` as a list, or `csv` as a table whose other columns are kept (the URL column, rank and goal are inferred unless `mapping` says). URLs already on the campaign are skipped; ones the project already holds join it. New pages start being read at once.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
urls | array of string, up to 2000 |
csv | string, up to 4000000 — Comma, tab or semicolon separated, with a header row |
mapping | array of object — How to take each column of `csv`; inferred when absent |
mapping[].index required | integer 0–9007199254740991 |
mapping[].header required | string |
mapping[].key required | string |
mapping[].role required | "url" | "goal" | "rank" | "custom" | "ignore" |
mapping[].type required | "number" | "text" | "date" |
mapping[].samples | array of string — Default []. |
filename | string, up to 200 |
Returns added, joinedFromProject, duplicatesInCampaign, duplicatesInFile, invalid, queued, dropped, droppedBy, mapping.
prospects.remove
POST /v1/campaigns/{campaignId}/prospects/remove · MCP prospects_remove · scope campaigns:write
Take URLs off a campaign. Only the campaign's membership goes; the page, its contacts and its messages stay, and importing the URL again brings it back.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
targetIds required | array of string (uuid) |
Returns removed.
prospects.skip
POST /v1/campaigns/{campaignId}/skip · MCP prospects_skip · scope campaigns:write
Stop everything still to go to these URLs from a campaign: unsent pitches are skipped and follow-ups of sent ones withdrawn. Threads they answered are left alone.
Reaches a person outside GEOboom, or withdraws something already handed to the mail provider. Needs an idempotency key.
campaignId required | string (uuid) |
|---|---|
targetIds required | array of string (uuid) |
Returns skipped, withdrawn.
prospects.setVerdict
POST /v1/campaigns/{campaignId}/verdicts · MCP prospects_setVerdict · scope campaigns:write
Mark a campaign's URLs a fit, not a fit, or undecided again (null). A fit is searched for contacts. URLs already on the queue keep their verdict and are counted as locked.
Changes data in GEOboom.
campaignId required | string (uuid) |
|---|---|
targetIds required | array of string (uuid) |
verdict required | "fit" | "not_fit" | null |
Returns decided, locked, notOnCampaign.
Jobs
Long work started by another operation, and where it is.
jobs.get
GET /v1/jobs/{jobId} · MCP jobs_get · scope read
Where a piece of queued work is: queued, running, done or failed. Operations that start long work (prospecting.run) return its jobId. A failed job is not retried further; what it produced, if anything, is read from the operation that started it.
jobId required | string (uuid) |
|---|
Returns id, type, state, attempts, createdAt.
Drafts
Messages waiting to be sent: first emails and replies.
drafts.list
GET /v1/drafts · MCP drafts_list · scope read
Messages waiting to be sent, newest first (at most 200). A `cold` draft is a first email: send it with drafts.sendFirstContact from a mailbox; any other with drafts.send.
projectId | string (uuid) |
|---|---|
campaignId | string (uuid) |
Returns rows.
drafts.previewFirstContact
GET /v1/drafts/{messageId}/first-contact · MCP drafts_previewFirstContact · scope read
What a cold draft would look like sent as a first email from a mailbox — exactly the text, the follow-ups — and anything that would stop it (suppression, a bad address, a mailbox not ready).
messageId required | string (uuid) |
|---|---|
inboxId required | string (uuid) |
Returns ok, blockers, warnings, from, to, subject, body, followUps, followUpDays.
drafts.update
PATCH /v1/drafts/{messageId} · MCP drafts_update · scope campaigns:write
Edit a waiting draft: subject, body, its follow-ups, and who it goes to. Fields left out stay as they are.
Changes data in GEOboom.
messageId required | string (uuid) |
|---|---|
subject | string, up to 500 |
bodyText | string, up to 50000 |
followUps | array of object |
followUps[].text required | string, up to 50000 |
followUps[].delayDays required | string | number | null |
followUps[].subject required | string, up to 500 | null |
to | array of string, up to 320 |
Returns messageId.
drafts.discard
POST /v1/drafts/{messageId}/discard · MCP drafts_discard · scope campaigns:write
Discard a waiting draft without sending it. It stays on the URL page; the queue moves on.
Changes data in GEOboom.
messageId required | string (uuid) |
|---|
Returns messageId.
drafts.sendFirstContact
POST /v1/drafts/{messageId}/first-contact · MCP drafts_sendFirstContact · scope mail:send
Send a cold draft as a first email from a mailbox, with its follow-ups. Queued: the mailbox's schedule decides when it leaves. Refused if anything in drafts.previewFirstContact would stop it.
Reaches a person outside GEOboom, or withdraws something already handed to the mail provider. Needs an idempotency key.
messageId required | string (uuid) |
|---|---|
inboxId required | string (uuid) |
Returns queued, to, from, followUpDays.
drafts.send
POST /v1/drafts/{messageId}/send · MCP drafts_send · scope mail:send
Send a waiting draft into its thread. A cold draft (a first email) is refused: use drafts.sendFirstContact. A draft that costs credits answers `confirm` with the cost first; call again with costConfirmed to send it.
Reaches a person outside GEOboom, or withdraws something already handed to the mail provider. Needs an idempotency key.
messageId required | string (uuid) |
|---|---|
costConfirmed | boolean — Default false. |
Inbox
Conversations with publishers: reading and replying.
threads.list
GET /v1/threads · MCP threads_list · scope read
List inbox threads with publishers, newest first: who each is with, whether it is owed an answer (need_action) or a chase, the page pitched, where a deal stands, and the suggested next step. Also returns how many threads are behind each tab. Filter by tab, project, campaign, contact, or a search.
tab | string — One of all, need_action, replied, sending, client, inbound. Anything else, or nothing, means all. |
|---|---|
projectId | string (uuid) | null |
campaignId | string (uuid) | null |
contactId | string (uuid) | null |
q | string | null — Matches names, addresses, company, the pitched page's domain or URL, and the subject |
page | integer 1–9007199254740991 |
size | integer 1–100 |
Returns rows, total, counts.
threads.get
GET /v1/threads/{conversationId} · MCP threads_get · scope read
One inbox thread and all its messages, oldest first, with sender, recipients, subject, plain text, and whether each was an automatic reply. Names the thread by conversationId and topicKey, as threads.list returns them.
conversationId required | string (uuid) |
|---|---|
topicKey required | string — As threads.list returns it; URL-encode it |
Returns thread, messages.
threads.reply
POST /v1/threads/{conversationId}/replies · MCP threads_reply · scope mail:send
Reply on a thread. Send `seenMessageId`, the newest message you read: if a newer one has arrived the reply is refused, to be read and answered instead. Others on the thread may be included by address. An identical reply on the same thread within 24 hours is refused.
Reaches a person outside GEOboom, or withdraws something already handed to the mail provider. Needs an idempotency key.
conversationId required | string (uuid) |
|---|---|
topicKey required | string |
subject | string, up to 500 — Default "". |
bodyText required | string, up to 50000 |
alsoInclude | array of string, up to 320 — Default []. |
suggestionId | string (uuid) | null |
seenMessageId | string (uuid) | null |
attachments | array of string (uuid) — Default []. |
Returns messageId.
threads.startTopic
POST /v1/threads/{conversationId}/topics · MCP threads_startTopic · scope mail:send
Start a new subject with somebody already in a conversation. Refused if a thread with that subject exists: reply there instead.
Reaches a person outside GEOboom, or withdraws something already handed to the mail provider. Needs an idempotency key.
conversationId required | string (uuid) |
|---|---|
subject required | string, up to 500 |
bodyText required | string, up to 50000 |
attachments | array of string (uuid) — Default []. |
toAddresses | array of string, up to 320 — Default []. |
dealId | string (uuid) | null |
Returns topicKey.
Contacts
People at publishers.
contacts.list
GET /v1/contacts · MCP contacts_list · scope read
List people at publishers this organisation has found or written to, with how warm each is, the sites they answer for, and whether a thread with them is owed an answer. Search by name, address or company; optionally narrow to one project.
projectId | string (uuid) | null — Only people at publishers with URLs in this project |
|---|---|
q | string | null — Matches part of the name, address or company |
standing | string — One of warm, reaching_out, all. Anything else, or nothing, means warm. |
page | integer 1–9007199254740991 |
size | integer 1–100 |
Returns rows, total, applied.
contacts.get
GET /v1/contacts/{contactId} · MCP contacts_get · scope read
Everything known about one person at a publisher: name, address and whether it is verified, role, how warm they are and why, their employer, the sites they answer for with our URLs on each, their threads (and which are owed an answer), notes and messages.
contactId required | string (uuid) |
|---|
Returns contact, employer, domains, threads, history, messages.
Publishers
Sites, their terms, your notes, and who not to approach.
publishers.list
GET /v1/publishers · MCP publishers_list · scope read
List publishers (sites) this organisation has pages or URLs for, with their authority, people, outreach counts and terms. Filter by who is in contact, what they sell and a search on the domain; optionally narrow to one project.
projectId | string (uuid) | null — Only publishers with URLs in this project |
|---|---|
q | string | null — Matches part of the domain or the company name |
standing | string — One of in_contact, reaching_out, all. Anything else, or nothing, means in_contact. |
stance | string — One of any, exchange, paid, both, neither, not_selling. Anything else, or nothing, means any. |
kind | string — One of any, listicle_insert, link_insert, guest_post, press_release, other. Anything else, or nothing, means any. |
sort | string — One of recent, dr, contacts, outreach, campaign_urls, pages, mentions, competitors. Anything else, or nothing, means dr. |
page | integer 1–9007199254740991 |
size | integer 1–100 |
Returns rows, total, applied.
publishers.get
GET /v1/publishers/{domain} · MCP publishers_get · scope read
Everything known about one publisher, by its site's domain: authority and traffic, the quality verdict, what they sell and their stated terms, private notes, the people there, pages and URLs held on the site, recent messages, and outreach standing.
domain required | string, up to 253 |
|---|---|
projectId | string (uuid) | null |
Returns domain, company, logo, domainRating, quality, metricsAt, label, sells, siteKind, publisher, standing, pages, people, messages.
publishers.setApproachable
POST /v1/publishers/{domain}/do-not-approach · MCP publishers_setApproachable · scope campaigns:write
Mark a publisher do-not-approach, or allow approaches again. Marking drops every pitch still queued for their site and withdraws sequences already handed to the mail provider, so no follow-up goes out; un-marking puts the dropped pitches back in the queue but does not re-add withdrawn sequences.
Reaches a person outside GEOboom, or withdraws something already handed to the mail provider. Needs an idempotency key.
domain required | string, up to 253 |
|---|---|
doNotApproach required | boolean |
Returns domain, doNotApproach, queueChanged, withdrawn.
publishers.saveNotes
POST /v1/publishers/{domain}/notes · MCP publishers_saveNotes · scope campaigns:write
Replace this organisation's private notes on a publisher (their site's domain). Empty text clears them. Notes are never shown to the publisher.
Changes data in GEOboom.
domain required | string, up to 253 |
|---|---|
notes required | string |
Returns domain, notes.
Deals
What was agreed: prices, payment, placements and whether they are still live.
deals.list
GET /v1/deals · MCP deals_list · scope read
This organisation's deals, newest activity first: who with, what each side gives, the price, and the state read off the placements (agreed, partly_live, live, broken or archived. An open set.). Filter by project, state, or text.
projectId | string (uuid) |
|---|---|
state | string |
q | string, up to 200 |
Returns rows.
deals.get
GET /v1/deals/{dealId} · MCP deals_get · scope read
One deal: its terms, payment details, every placement with what the daily check last saw, the threads it came from (conversationId and topicKey, for threads.get), and its history.
dealId required | string (uuid) |
|---|
Returns id, title, state, projectId, project, publisherDomain, contactId, who, contactEmail, oursGives, theirsGives, oursAmountCents, theirsAmountCents, currency, oursInvoiceRef, oursPaymentTerms, oursAmountExcludesTax, oursPaidAt, owed, notes, archivedAt, createdAt, updatedAt, placements, threads, history.
deals.create
POST /v1/deals · MCP deals_create · scope deals:write
Write a deal down: who it is with (email; a new address becomes a contact), what each side gives (placement or payment), and the thread it came from. Price it with deals.update and add what goes where with deals.addPlacement.
Changes data in GEOboom.
projectId required | string (uuid) |
|---|---|
email required | string |
title | string, up to 300 | null |
oursGives | "placement" | "payment" — What we hand over: placement or payment Default "placement". |
theirsGives | "placement" | "payment" — What they hand over: placement or payment Default "placement". |
notes | string, up to 20000 | null |
thread | object | null |
thread.conversationId required | string (uuid) |
thread.topicKey required | string |
Returns id.
deals.update
PATCH /v1/deals/{dealId} · MCP deals_update · scope deals:write
Change a deal's terms: what each side gives and pays (cents, with currency), invoice and payment details, and mark it paid (oursPaidAt) or not (null). Only the fields sent change. Placements have their own operations.
Changes data in GEOboom.
dealId required | string (uuid) |
|---|---|
title | string, up to 300 | null |
publisherDomain | string, up to 253 | null |
contactId | string (uuid) | null |
oursGives | "placement" | "payment" |
theirsGives | "placement" | "payment" |
oursAmountCents | integer 0–9007199254740991 | null — What we pay, in cents |
theirsAmountCents | integer 0–9007199254740991 | null — What they pay, in cents |
currency | string | null |
notes | string, up to 20000 | null |
oursInvoiceRef | string, up to 500 | null |
oursPaymentMethod | string, up to 200 | null |
oursPaymentTerms | string, up to 500 | null |
oursAmountExcludesTax | boolean | null |
oursPaidAt | string (date-time) | null — When we paid them; null to mark not paid |
oursInvoiceAttachmentId | string (uuid) | null |
Returns id.
deals.archive
POST /v1/deals/{dealId}/archive · MCP deals_archive · scope deals:write
Archive a deal (no longer tracked or checked) or reopen it.
Changes data in GEOboom.
dealId required | string (uuid) |
|---|---|
archived required | boolean |
Returns id, archived.
deals.addPlacement
POST /v1/deals/{dealId}/placements · MCP deals_addPlacement · scope deals:write
Add what goes where to a deal: a link on a page (ours: on our site; theirs: on theirs), its anchor, rel and position, or added words. Marked agreed until it is live. GEOboom checks live placements daily.
Changes data in GEOboom.
dealId required | string (uuid) |
|---|---|
side required | "ours" | "theirs" — ours: we place them on our page; theirs: they place us on theirs |
kind | "link_insertion" | "added_text" — link_insertion: a link into existing words; added_text: new words with links Default "link_insertion". |
hostUrl | string, up to 2000 | null — The page it goes on |
targetUrl | string, up to 2000 | null — Where the link points |
anchor | string, up to 500 | null |
rel | string, up to 100 | null — e.g. nofollow, sponsored; empty for a followed link |
body | string, up to 50000 | null — The agreed words, for added_text |
bodyFormat | "text" | "markdown" | null — markdown keeps the links inside the words |
position | integer 1–9007199254740991 | null — Our place in a listicle |
textBy | "us" | "them" | null — Who writes the words |
status | "agreed" | "live" | "removed" — agreed: settled, not up yet; live: on the page; removed: was up, is not Default "agreed". |
promisedAt | string, up to 40 | null — The date it was promised for, YYYY-MM-DD |
notes | string, up to 20000 | null |
Returns id.
deals.updatePlacement
PATCH /v1/placements/{placementId} · MCP deals_updatePlacement · scope deals:write
Change a placement: its terms, or its status (agreed, live, removed). Setting a status withdraws what the daily check concluded about the old one; the next check looks again. Only the fields sent change.
Changes data in GEOboom.
placementId required | string (uuid) |
|---|---|
kind | "link_insertion" | "added_text" — link_insertion: a link into existing words; added_text: new words with links |
hostUrl | string, up to 2000 | null — The page it goes on |
targetUrl | string, up to 2000 | null — Where the link points |
anchor | string, up to 500 | null |
rel | string, up to 100 | null — e.g. nofollow, sponsored; empty for a followed link |
body | string, up to 50000 | null — The agreed words, for added_text |
bodyFormat | "text" | "markdown" | null — markdown keeps the links inside the words |
position | integer 1–9007199254740991 | null — Our place in a listicle |
textBy | "us" | "them" | null — Who writes the words |
status | "agreed" | "live" | "removed" — agreed: settled, not up yet; live: on the page; removed: was up, is not |
promisedAt | string, up to 40 | null — The date it was promised for, YYYY-MM-DD |
notes | string, up to 20000 | null |
Returns id, dealId.
Blurbs
Our entries for publishers' articles, and the copy publishers send for the project's own site.
blurbs.list
GET /v1/blurbs · MCP blurbs_list · scope read
Blurbs, newest first: our entries written for publishers' articles (side ours) and the copy publishers sent for our project's site, read out of their threads (side theirs). Each with its words, its table line, the article it goes into and the thread it belongs to. Filter by project, by thread (conversationId, with topicKey to narrow to one subject), by side, or by text in the address or words.
projectId | string (uuid) |
|---|---|
conversationId | string (uuid) |
topicKey | string — With conversationId: one subject of that conversation |
side | "ours" | "theirs" |
q | string, up to 200 — Text in the article address, the words or the publisher's domain |
limit | integer 1–200 |
Returns rows.
blurbs.get
GET /v1/blurbs/{blurbId} · MCP blurbs_get · scope read
One blurb in full: its words and table line, what the model first wrote (ours) and what it was asked, its link and anchor, what the model could not fill (gaps), where the words came from in the thread (theirs: messages, attachments, Google Docs), how the thread changed them, and every link shared with the publisher. A theirs blurb can be put on the project's WordPress site with sites.publish (blurbId).
blurbId required | string (uuid) |
|---|
Returns id, side, projectId, conversationId, topicKey, hostUrl, authorDomain, body, tableRow, edited, author, createdAt, updatedAt, originalBody, originalTableRow, instructions, anchor, targetUrl, shape, gaps, sources, history, shares.