GEOboom API

A REST API over HTTPS and JSON, for your own software: authentication, idempotency, limits, and every operation.

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

ScopeAllows
readSee everything: projects, campaigns, prospects, publishers, contacts, deals and the inbox, threads included.
campaigns:writeCreate and change projects and campaigns, set up prospecting, import URLs and decide which fit, edit drafts.
prospecting:spendSpend: run prospecting, set monthly credit budgets, turn on automatic scheduling.
mail:sendReach publishers: reply on threads, send first emails, launch or resume a campaign. Sent email cannot be taken back.
deals:writeWrite 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 requiredstring (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 requiredstring, up to 200
brandName requiredstring, up to 200
brandUrlstring, up to 2000
brandContextstring, up to 10000
pitchType"exchange" | "exchange_or_paid" | "paid" — Default "exchange_or_paid".
clientLocationstring, up to 200
postalAddressstring, 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 requiredstring (uuid)
namestring, up to 200
brandNamestring, up to 200
brandUrlstring, up to 2000
brandContextstring, up to 10000
pitchType"exchange" | "exchange_or_paid" | "paid"
clientLocationstring, up to 200
postalAddressstring, 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 requiredstring (uuid)
credits requirednumber | 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 requiredstring (uuid)
mailboxes requiredarray of object
mailboxes[].id requiredstring (uuid)
mailboxes[].senderTitlestring, 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 requiredstring (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 requiredstring (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 requiredstring (uuid)
namestring, 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"
templateIdsarray of string (uuid) — The manual list, in the order a batch deals them; used when templateMode is manual
mailboxIdsarray of string (uuid) — Mailboxes it sends from, of the project's; empty means all
sendRulesobject
sendRules.publisherLimitnumber | null — Most people written to at one publisher, 1–50
sendRules.publisherGapDaysnumber | null — Days between people at one publisher, 0–365; null is the default
sendRules.includeCatchAllboolean
sendRules.donorPageLimitnumber | null
excludeCompetitorsboolean | null — null follows the pitch: on for paid
archivedboolean
autoFilterboolean — Decide undecided URLs by the campaign's rules as facts arrive
rankByobject — A column key from the import, `rank`, or `position`
rankBy.key requiredstring
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 requiredstring (uuid)
credits requirednumber | 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 requiredstring (uuid)
autoSchedule requiredboolean

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 requiredstring (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 requiredstring (uuid)
agreedCostnumber — 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 requiredstring (uuid)
namestring, up to 200 — Default "".
kind"links" | "geo" — links: placements; geo: answers in AI engines Default "links".
creditAllowancenumber | null — Whole credits a month it may commit; null is the default
excludeCompetitorsboolean — 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 requiredstring (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 requiredstring (uuid)
afterstring

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 requiredstring (uuid)
keywords requiredstring | array of string, up to 500 — Keywords: an array, or one per line
serpDepthnumber — Default 20.
topNnumber — Default 500.
schedulestring — Default "off".
marketstring — A market code: US, GB, CA, AU, DE, FR, ES, UA. Anything else means US. Default "US".
languageCodestring, 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 requiredstring (uuid)
mode requiredstring

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 requiredstring (uuid)
prompts requiredstring | array of string, up to 500 — Prompts: an array, or one per line
enginesarray of string — Default [].
topNnumber — Default 500.
windowDaysnumber — Default 30.
schedulestring — Default "off".
marketstring — A market code: US, GB, CA, AU, DE, FR, ES, UA. Anything else means US. Default "US".
languageCodestring, 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 requiredstring (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 requiredstring (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 requiredstring (uuid)
statestring — One of undecided, fit, not_fit, scheduled, all_fit, all. Anything else, or nothing, means undecided.
sortstring — One of value, position, dr. Anything else, or nothing, means value.
pageinteger 1–9007199254740991
sizeinteger 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 requiredstring (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 requiredstring (uuid)
targetIds requiredarray of string (uuid)
competitor requiredboolean

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 requiredstring (uuid)
urlsarray of string, up to 2000
csvstring, up to 4000000 — Comma, tab or semicolon separated, with a header row
mappingarray of object — How to take each column of `csv`; inferred when absent
mapping[].index requiredinteger 0–9007199254740991
mapping[].header requiredstring
mapping[].key requiredstring
mapping[].role required"url" | "goal" | "rank" | "custom" | "ignore"
mapping[].type required"number" | "text" | "date"
mapping[].samplesarray of string — Default [].
filenamestring, 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 requiredstring (uuid)
targetIds requiredarray 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 requiredstring (uuid)
targetIds requiredarray 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 requiredstring (uuid)
targetIds requiredarray 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 requiredstring (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.

projectIdstring (uuid)
campaignIdstring (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 requiredstring (uuid)
inboxId requiredstring (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 requiredstring (uuid)
subjectstring, up to 500
bodyTextstring, up to 50000
followUpsarray of object
followUps[].text requiredstring, up to 50000
followUps[].delayDays requiredstring | number | null
followUps[].subject requiredstring, up to 500 | null
toarray 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 requiredstring (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 requiredstring (uuid)
inboxId requiredstring (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 requiredstring (uuid)
costConfirmedboolean — 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.

tabstring — One of all, need_action, replied, sending, client, inbound. Anything else, or nothing, means all.
projectIdstring (uuid) | null
campaignIdstring (uuid) | null
contactIdstring (uuid) | null
qstring | null — Matches names, addresses, company, the pitched page's domain or URL, and the subject
pageinteger 1–9007199254740991
sizeinteger 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 requiredstring (uuid)
topicKey requiredstring — 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 requiredstring (uuid)
topicKey requiredstring
subjectstring, up to 500 — Default "".
bodyText requiredstring, up to 50000
alsoIncludearray of string, up to 320 — Default [].
suggestionIdstring (uuid) | null
seenMessageIdstring (uuid) | null
attachmentsarray 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 requiredstring (uuid)
subject requiredstring, up to 500
bodyText requiredstring, up to 50000
attachmentsarray of string (uuid) — Default [].
toAddressesarray of string, up to 320 — Default [].
dealIdstring (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.

projectIdstring (uuid) | null — Only people at publishers with URLs in this project
qstring | null — Matches part of the name, address or company
standingstring — One of warm, reaching_out, all. Anything else, or nothing, means warm.
pageinteger 1–9007199254740991
sizeinteger 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 requiredstring (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.

projectIdstring (uuid) | null — Only publishers with URLs in this project
qstring | null — Matches part of the domain or the company name
standingstring — One of in_contact, reaching_out, all. Anything else, or nothing, means in_contact.
stancestring — One of any, exchange, paid, both, neither, not_selling. Anything else, or nothing, means any.
kindstring — One of any, listicle_insert, link_insert, guest_post, press_release, other. Anything else, or nothing, means any.
sortstring — One of recent, dr, contacts, outreach, campaign_urls, pages, mentions, competitors. Anything else, or nothing, means dr.
pageinteger 1–9007199254740991
sizeinteger 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 requiredstring, up to 253
projectIdstring (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 requiredstring, up to 253
doNotApproach requiredboolean

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 requiredstring, up to 253
notes requiredstring

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.

projectIdstring (uuid)
statestring
qstring, 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 requiredstring (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 requiredstring (uuid)
email requiredstring
titlestring, 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".
notesstring, up to 20000 | null
threadobject | null
thread.conversationId requiredstring (uuid)
thread.topicKey requiredstring

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 requiredstring (uuid)
titlestring, up to 300 | null
publisherDomainstring, up to 253 | null
contactIdstring (uuid) | null
oursGives"placement" | "payment"
theirsGives"placement" | "payment"
oursAmountCentsinteger 0–9007199254740991 | null — What we pay, in cents
theirsAmountCentsinteger 0–9007199254740991 | null — What they pay, in cents
currencystring | null
notesstring, up to 20000 | null
oursInvoiceRefstring, up to 500 | null
oursPaymentMethodstring, up to 200 | null
oursPaymentTermsstring, up to 500 | null
oursAmountExcludesTaxboolean | null
oursPaidAtstring (date-time) | null — When we paid them; null to mark not paid
oursInvoiceAttachmentIdstring (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 requiredstring (uuid)
archived requiredboolean

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 requiredstring (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".
hostUrlstring, up to 2000 | null — The page it goes on
targetUrlstring, up to 2000 | null — Where the link points
anchorstring, up to 500 | null
relstring, up to 100 | null — e.g. nofollow, sponsored; empty for a followed link
bodystring, up to 50000 | null — The agreed words, for added_text
bodyFormat"text" | "markdown" | null — markdown keeps the links inside the words
positioninteger 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".
promisedAtstring, up to 40 | null — The date it was promised for, YYYY-MM-DD
notesstring, 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 requiredstring (uuid)
kind"link_insertion" | "added_text" — link_insertion: a link into existing words; added_text: new words with links
hostUrlstring, up to 2000 | null — The page it goes on
targetUrlstring, up to 2000 | null — Where the link points
anchorstring, up to 500 | null
relstring, up to 100 | null — e.g. nofollow, sponsored; empty for a followed link
bodystring, up to 50000 | null — The agreed words, for added_text
bodyFormat"text" | "markdown" | null — markdown keeps the links inside the words
positioninteger 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
promisedAtstring, up to 40 | null — The date it was promised for, YYYY-MM-DD
notesstring, 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.

projectIdstring (uuid)
conversationIdstring (uuid)
topicKeystring — With conversationId: one subject of that conversation
side"ours" | "theirs"
qstring, up to 200 — Text in the article address, the words or the publisher's domain
limitinteger 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 requiredstring (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.

Book a demo with Oleksii

30 minutes with GEOboom’s Head of Marketing: your sites, your prospects, live.

Free trial

Request GEOboom free trial

Leave your work email and we’ll get in touch to set your trial up.

Have an account? Sign in