Entwickler
Mit einem API-Schlüssel Maßnahmen, Leads, Prompts und Playbooks lesen und ändern, jedes Ereignis sofort per signiertem Webhook erhalten oder ohne Code die Zapier-App und den n8n-Node von Echo nutzen.
Jede der folgenden Adressen beginnt mit https://echo-aeo.com/api/v1.
curl https://echo-aeo.com/api/v1/actions?brand_id=YOUR_BRAND_ID \ -H "Authorization: Bearer echo_YOUR_KEY"
Who the key belongs to. Zapier and n8n use it to test a key.
/meThe key's workspace, its name and scopes, and the workspace's brands.
{ "workspace": { "id": "ws_…", "name": "Fernwick" }, "key": { "id": "key_…", "name": "Zapier", "scopes": ["leads:write"] },
"brands": [{ "id": "b_x7…", "name": "Fernwick", "domain": "fernwick.example" }] }/brandsThe workspace's brands.
{ "data": [{ "id": "b_x7…", "name": "Fernwick", "domain": "fernwick.example", "created_at": "…" }], "next_cursor": null }The to-do list every part of Echo feeds: what to change on the website, pages to build, where to get mentioned, follow-ups.
/actionsactions:readA brand's actions, newest first.
brand_idstatuslimitcursor{ "data": [{
"id": "Hh3kP9…", "brand_id": "b_x7…", "title": "Add a comparison page with Tallybird",
"kind": "create_page", "impact": "high", "status": "todo", "source": "ai",
"url": "https://echo-aeo.com/app/actions?brand=b_x7…&action=Hh3kP9…",
"assignee_email": "priya@fernwick.example", "due_date": "2026-10-10",
"detail": "…", "created_at": "2026-09-28T06:02:11.000Z", "done_at": null
}], "next_cursor": "eyJ0Ijo…" }/actions/{id}actions:readOne action.
id{
"id": "Hh3kP9…", "brand_id": "b_x7…", "title": "Add a comparison page with Tallybird",
"kind": "create_page", "impact": "high", "status": "todo", "source": "ai",
"url": "https://echo-aeo.com/app/actions?brand=b_x7…&action=Hh3kP9…",
"assignee_email": "priya@fernwick.example", "due_date": "2026-10-10",
"detail": "…", "created_at": "2026-09-28T06:02:11.000Z", "done_at": null
}/actionsactions:writeAdds a “Follow up” action to a brand's board.
brand_idtitledetailimpactdue_dateassignee_email{
"id": "Hh3kP9…", "brand_id": "b_x7…", "title": "Add a comparison page with Tallybird",
"kind": "create_page", "impact": "high", "status": "todo", "source": "ai",
"url": "https://echo-aeo.com/app/actions?brand=b_x7…&action=Hh3kP9…",
"assignee_email": "priya@fernwick.example", "due_date": "2026-10-10",
"detail": "…", "created_at": "2026-09-28T06:02:11.000Z", "done_at": null
}/actions/{id}actions:writeChanges an action's status, due date or assignee. Marking it done sends action.done.
statusdue_dateassignee_email{
"id": "Hh3kP9…", "brand_id": "b_x7…", "title": "Add a comparison page with Tallybird",
"kind": "create_page", "impact": "high", "status": "todo", "source": "ai",
"url": "https://echo-aeo.com/app/actions?brand=b_x7…&action=Hh3kP9…",
"assignee_email": "priya@fernwick.example", "due_date": "2026-10-10",
"detail": "…", "created_at": "2026-09-28T06:02:11.000Z", "done_at": null
}People who agreed to hear from the brand. Echo keeps only them, so adding one needs your word that they agreed.
/leadsleads:readThe workspace's leads, newest first.
emaillimitcursor{ "data": [{
"id": "Lq81…", "email": "ines@quietharbour.example", "first_name": "Ines", "last_name": "Duarte",
"company": "Quiet Harbour Studio", "website": "quietharbour.example", "source": "api",
"can_email": true, "blocked_reason": null, "created_at": "2026-09-29T09:14:02.000Z"
}], "next_cursor": null }/leads/{id}leads:readOne lead.
id{
"id": "Lq81…", "email": "ines@quietharbour.example", "first_name": "Ines", "last_name": "Duarte",
"company": "Quiet Harbour Studio", "website": "quietharbour.example", "source": "api",
"can_email": true, "blocked_reason": null, "created_at": "2026-09-29T09:14:02.000Z"
}/leadsleads:writeAdds a lead, or updates the one with that email (201 when new, 200 when updated).
emailconsentfirst_name, last_name, company, websiteemail_campaign_id{
"id": "Lq81…", "email": "ines@quietharbour.example", "first_name": "Ines", "last_name": "Duarte",
"company": "Quiet Harbour Studio", "website": "quietharbour.example", "source": "api",
"can_email": true, "blocked_reason": null, "created_at": "2026-09-29T09:14:02.000Z",
"created": true, "added_to_campaign": null
}/email-campaignsleads:readThe workspace's email campaigns, to add leads to.
{ "data": [{ "id": "c_…", "name": "AI score follow-up", "status": "active", "brand_id": "b_x7…", "created_at": "…" }], "next_cursor": null }The questions Echo asks AI assistants for a brand, and how often the answers name it.
/promptsprompts:readA brand's prompts with their topic, intent, market and whether they're tracked.
brand_id{ "data": [{ "id": "p_…", "text": "Best CRM for a small agency?", "topic": "CRM for small teams", "intent": "commercial", "market_id": "m_…", "active": true, "created_at": "…" }], "next_cursor": null }/metricsmetrics:readAI visibility for a period: share of answers naming the brand, share of voice, position and tone, for the brand and each competitor, and per day.
brand_idfrom, toenginemarket{ "brand_id": "b_x7…", "from": "2026-08-31", "to": "2026-09-29", "engine": "all",
"brand": { "visibility": 0.41, "share_of_voice": 0.22, "avg_position": 2.3, "positive_share": 0.64, "mentions": 412, "answers": 1004, "citations": 88 },
"competitors": [{ "id": "…", "name": "Tallybird", "domain": "tallybird.example", "visibility": 0.58, … }],
"days": [{ "date": "2026-09-29", "answers": 40, "visibility": 0.43 }] }The pages Echo hosts for a brand (More → Landing pages), with their address and results since they went live.
/landing-pagespages:readA brand's landing pages: title, address, status, views (the Echo tag) and confirmed sign-ups from their lead forms.
brand_id{ "data": [{ "id": "lp_…", "title": "Fernwick vs. Tallybird", "url": "https://go.fernwick.example/fernwick-vs-tallybird", "status": "published",
"views": 1240, "leads": 38, "campaign_id": "mc_…", "published_at": "2026-09-20T10:02:00.000Z", "created_at": "…" }], "next_cursor": null }A brand's conversion tests (More → Landing pages → Experiments): landing page, lead form and before-and-after tests, each version's visitors and sign-ups, and the result.
/experimentsexperiments:readA brand's tests, newest first: what's tested, status, the verdict in words, each version's visitors, sign-ups, confirmed sign-ups and chance to beat the original, the result and the learning.
brand_id{ "data": [{ "id": "ex_…", "name": "Free audit instead of a demo", "kind": "page", "focus": "offer", "status": "finished", "result": "won",
"verdict": "Version B wins: 97% chance it's better, +38% sign-ups per visitor.", "learning": "A smaller first step works better.",
"versions": [{ "key": "A", "name": "Original", "visitors": 912, "sign_ups": 29, "confirmed": 22, "chance_to_beat_original": null },
{ "key": "B", "name": "Version B", "visitors": 928, "sign_ups": 42, "confirmed": 33, "chance_to_beat_original": 0.97 }],
"page_id": "lp_…", "form_id": null, "campaign_id": null, "started_at": "2026-09-01T09:00:00.000Z", "ended_at": "2026-09-19T05:00:00.000Z", "created_at": "…" }], "next_cursor": null }A brand's outreach (pitches, listing and review requests and community replies: Market intel → Mentions → Outreach), partnerships and own events (More → Partners and events), with their stage, next step and results, and its contacts. Echo never emails or posts for these: people send and post from their own mail and accounts.
/relationsrelations:readA brand's items, newest first: programme, format, stage (open, won or lost), next step and date, owner, contact, outlet or community, campaigns, live coverage pieces and the tracking link's visits and sign-ups.
brand_idprogramme{ "data": [{ "id": "ri_…", "programme": "media", "format": "podcast", "title": "Pitch the Agency Ops Podcast on pipeline reviews", "stage": "agreed", "state": "open",
"next_step": "Send three talking points", "next_date": "2026-10-08", "owner_user_id": "u_…", "contact": { "id": "rc_…", "name": "Robin Vale", "outlet": "Agency Ops Podcast" },
"place": "Agency Ops Podcast", "url": "https://agencyops.example", "event_at": null, "campaign_ids": ["mc_…"], "coverage": 0, "visits": 0, "sign_ups": 0,
"result_at": null, "created_at": "2026-09-22T09:12:00.000Z", "updated_at": "…" }], "next_cursor": null }/relation-contactsrelations:readA brand's contacts (Mentions → Contacts): journalists, podcast hosts, partners and community members, with role, outlet, email, website, topics and how many items they're on.
brand_id{ "data": [{ "id": "rc_…", "name": "Robin Vale", "role": "Host", "outlet": "Agency Ops Podcast", "email": "robin@agencyops.example", "website": "https://agencyops.example",
"topics": ["agency operations", "sales"], "items": 1, "source": "csv", "created_at": "2026-09-20T08:00:00.000Z" }], "next_cursor": null }The ads a brand's competitors run on Meta and Google, from the platforms' public ad libraries (Competitive intel → Ads). Meta shows product ads only for ads shown in the EU and the UK. No spend or results: the libraries don't publish them.
/competitor-adscompetitors:readEvery competitor's ads Echo keeps (running ones and those stopped in the last 12 months): platform, format, texts (Meta), preview picture (Google), where it links, countries, first and last seen, days running, its theme and its link in the ad library.
brand_id{ "data": [{ "id": "ca_…", "competitor": { "id": "c_…", "name": "Tallybird", "domain": "tallybird.example" }, "platform": "meta", "format": "image",
"headline": "Client reports in one click", "body": "Stop building reports by hand…", "landing_url": "https://tallybird.example", "preview_image_url": null,
"library_url": "https://www.facebook.com/ads/library/?id=…", "countries": ["DE", "NL"], "first_seen": "2026-07-02T00:00:00.000Z", "last_seen": "2026-09-30T08:00:00.000Z",
"stopped_at": null, "running": true, "days_running": 91, "theme": "Client reporting" }], "next_cursor": null }Where people talk about the brand and its competitors on the web (Market intel → Mentions, Phase 60): threads, reviews and posts from the pages AI answers cite, Google, Google Alerts, Hacker News and Stack Overflow. Read only: Echo never posts; the team replies from their own accounts.
/mentionsmentions:readA brand's mentions, newest first: link, site, title, snippet, the author's public handle when the source gives one, date, sentiment, whether it names the brand and which competitors, whether it's a question, whether AI answers cite it and which assistants, and its status (new, seen, answered, ignored).
brand_idsitesentimentcitedstatuslimit{ "data": [{ "id": "lm_…", "url": "https://www.reddit.com/r/agencies/comments/abc123", "site": "reddit.com", "site_label": "Reddit",
"title": "Which CRM do small agencies use?", "snippet": "We tried Tallybird but…", "author": null, "published_at": "2026-09-28", "sentiment": "neutral",
"names_brand": false, "competitors": ["Tallybird"], "question": true, "cited": true, "cited_by": ["chatgpt", "perplexity"], "status": "new" }], "next_cursor": null }Who outside the team has access to Brand assets, and the “Request files” links (Phase 56). Read only: inviting a guest or making a request is a person's click in Echo.
/guestsassets:readThe workspace's guests (freelancers and agencies invited to chosen collections): email, name, state (invited, active or ended), their collections with whether they can upload, when their access ends and when they were last seen. Optional brand_id: only guests with collections of that brand.
brand_id{ "data": [{ "id": "g_…", "email": "sam@studio.example", "name": "Sam Park", "state": "active",
"collections": [{ "id": "col_…", "name": "Autumn campaign", "brand_id": "b_x7…", "can_upload": true }],
"access_ends_at": null, "accepted_at": "2026-09-30T10:00:00.000Z", "last_seen_at": "2026-09-30T10:05:00.000Z", "created_at": "…" }], "next_cursor": null }/file-requestsassets:readA brand's file requests: title, note, the link, the collection files go into, state (open, closed, expired or full), which kinds of files it takes, its limits, how many files came in and how many still wait for review.
brand_id{ "data": [{ "id": "fr_…", "title": "Your logo as SVG", "note": "For the partner page", "url": "https://echo-aeo.com/r/…",
"collection": { "id": "col_…", "name": "Partner logos" }, "state": "open", "has_password": false, "file_kinds": ["images"], "max_files": 50,
"max_file_bytes": 524288000, "files_received": 3, "files_to_review": 1, "last_received_at": "…", "expires_at": "2026-10-30T00:00:00.000Z", "created_at": "…" }], "next_cursor": null }Playbooks run by themselves when something happens. Start one for a lead from your own tools, or read the events of the last 30 days.
/playbooksplaybooks:readA brand's playbooks.
brand_id{ "data": [{ "id": "pb_…", "name": "Welcome new form leads", "trigger": "form.submitted", "enabled": true, "brand_id": "b_x7…", "created_at": "…" }], "next_cursor": null }/playbooks/{id}/runsplaybooks:writeRuns a playbook about a person (form sign-ups, AI score sign-ups, replies) for one of your leads. Counts toward the plan's runs.
lead_id{ "id": "run_…", "playbook_id": "pb_…", "status": "done" }/eventsplaybooks:readEvents of the last 30 days that a playbook or webhook listened to, newest first.
typelimitsample{ "data": [ { "id": "evt_…", "type": "form.submitted", … } ], "next_cursor": null }Zapier and n8n subscribe here when a Zap or workflow with an Echo trigger is switched on, and unsubscribe when it's switched off. Your own code can too.
/webhookswebhooks:readThe workspace's webhooks.
{ "data": [{ "id": "wh_…", "url": "https://hooks.zapier.com/…", "events": ["form.submitted"], "brand_id": null, "enabled": true, … }], "next_cursor": null }/webhookswebhooks:writeAdds a webhook. Its signing secret is in the answer, once.
urleventsbrand_id{ "id": "wh_…", "url": "https://hooks.zapier.com/…", "events": ["lead.replied"], "enabled": true, "secret": "whsec_…", … }/webhooks/{id}webhooks:writeRemoves a webhook.
id{ "id": "wh_…", "deleted": true }Was Playbooks auslöst und was Webhooks senden. Jede Zustellung ist ein POST mit dem Ereignis als JSON: ID, Typ, Zeitpunkt, Workspace, Marke und Daten.
form.submittedscore.signuplead.repliedcompany.visitedaccount.signalaction.createdaction.doneproject.createdproject.donecampaign.startedcampaign.endedpage.publishedexperiment.startedexperiment.finishedcompetitor.ad_startedcompetitor.ad_stoppedasset.uploadedfile_request.receivedstory.answers_receivedstory.approvedstory.suggestion_receivedstory.expiringstory.withdrawncoverage.publishedpartner.liveevent.heldaudience.objection_foundmention.foundmention.negativecontent.claim_wrongcontact.subscribedcontact.unsubscribedcontact.updatednewsletter.sentframer.publishedseo.rank_lostseo.page_brokenseo.score_droppedagent.draftedanswer.wrongvisibility.droppedreport.ready{
"id": "evt_4GJ2kq9V…",
"type": "form.submitted",
"created_at": "2026-09-29T09:14:02.000Z",
"workspace_id": "ws_…",
"brand": {
"id": "b_x7…",
"name": "Fernwick",
"domain": "fernwick.example"
},
"data": {
"form": {
"id": "sample-form",
"name": "Newsletter"
},
"lead": {
"id": "sample-lead",
"email": "jamie@sample.example",
"first_name": "Jamie",
"last_name": "Rivera",
"company": "Sample Co",
"website": "sample.example",
"source": "form",
"can_email": true
},
"fields": {
"email": "jamie@sample.example",
"first_name": "Jamie"
}
}
}Jeder Webhook hat ein eigenes Geheimnis, das bei der Erstellung einmal angezeigt wird. Echo signiert jede Zustellung nach dem Standard-Webhooks-Verfahren (Header webhook-id, webhook-timestamp und webhook-signature), sodass sie sich mit jeder Standard-Webhooks-Bibliothek prüfen lässt. Fehlgeschlagene Zustellungen werden innerhalb von etwa 8 Stunden 6-mal erneut versucht. Eine Antwort mit 410 deaktiviert den Webhook.
import crypto from "node:crypto";
// secret: the webhook's "whsec_…"; headers and the raw body as received.
export function fromEcho(secret, headers, body) {
const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = "v1," + crypto.createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest("base64");
return headers["webhook-signature"].split(" ").some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}Kein Code: Echo mit einem API-Schlüssel verbinden und festlegen, was passieren soll.