Developers

API documentation

Version 1 · Last updated 17 November 2026

Connect The Client Ocean to your website, Zapier, Make, Google Sheets, Facebook Lead Ads or your own code. There are three ways in:

  1. Lead-capture endpoint — one secret URL per user. No login. Perfect for forms and automations.
  2. REST API — log in with your account to read and write your leads and CRM data.
  3. Public endpoints — plans/pricing and the contact form.

All requests use HTTPS and JSON. Values below in <angle brackets> are yours to fill in.

Base URL   https://firestore.googleapis.com/v1/projects/my-project-1509538563016/databases/(default)/documents
API key    AIzaSyD47sNtRooSLOE8QyOBTvfWABNkNA1WD-g   (public web key — access is controlled by security rules, not by this key)

1. Lead-capture endpoint (webhook)

In the app open Settings → API & integrations → Create my lead-capture endpoint and copy your URL. Anyone with the URL can add leads to your account only, so keep it private; you can replace it at any time.

POST/capture/<YOUR_TOKEN>/leads?key=<API_KEY>

Fields

FieldRequiredNotes
businessyesBusiness name, 1–200 characters
websiteURL (max 500)
emailBusiness email (max 200)
phonePhone / WhatsApp
city, countrycountry = 2-letter code, e.g. ae, de
nichee.g. Real estate agencies
dm, roleDecision maker and their role
notesMax 5,000 characters
sourcee.g. Website form, Facebook Lead Ads
langClient language code, e.g. de, ar, ur
valueExpected deal value (text or number as text)
tagsComma-separated, e.g. "VIP, Dubai"

Each value is sent as {"stringValue": "..."}. Unknown fields are rejected.

cURL

curl -X POST "https://firestore.googleapis.com/v1/projects/my-project-1509538563016/databases/(default)/documents/capture/<YOUR_TOKEN>/leads?key=<API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"business":{"stringValue":"Palm Realty"},"email":{"stringValue":"owner@palmrealty.ae"},"city":{"stringValue":"Dubai"},"source":{"stringValue":"Website form"}}}'

JavaScript (your website form)

const URL = "https://firestore.googleapis.com/v1/projects/my-project-1509538563016/databases/(default)/documents/capture/<YOUR_TOKEN>/leads?key=<API_KEY>";
const s = (v) => ({ stringValue: String(v || "") });
await fetch(URL, { method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ fields: { business: s(form.company.value), email: s(form.email.value), phone: s(form.phone.value), notes: s(form.message.value), source: s("Website form") } }) });

Python

import requests
s = lambda v: {"stringValue": str(v)}
requests.post(URL, json={"fields": {"business": s("Palm Realty"), "email": s("owner@palmrealty.ae"), "source": s("Python")}})

Zapier / Make

  1. Add an action Webhooks by Zapier → POST (Make: HTTP → Make a request, method POST).
  2. URL: your endpoint. Payload type: JSON (raw body).
  3. Body: the JSON from the cURL example, mapping your form fields into the stringValues.
  4. Test — the lead appears in your Lead Tracker the next time you open the app (or click Check for new leads now), with a "review today" task.

Responses

200 — the created document (JSON). 403 PERMISSION_DENIED — wrong/old token, missing business, a field that isn't allowed, or a value that's too long. 429 — slow down.

2. REST API (your account)

Authenticate

POSThttps://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=<API_KEY>

{"email":"you@example.com","password":"<your password>","returnSecureToken":true}

The response contains idToken (valid 1 hour), refreshToken and localId (your user id, <UID>). Send Authorization: Bearer <idToken> with every request. Refresh: POSThttps://securetoken.googleapis.com/v1/token?key=<API_KEY> with grant_type=refresh_token&refresh_token=<refreshToken>. Your email must be confirmed and your account active.

Leads

GET/users/<UID>/leads?pageSize=300 — list leads (use nextPageToken for more)
GET/users/<UID>/leads/<LEAD_ID> — one lead
PATCH/users/<UID>/leads/<LEAD_ID> — create or replace a lead
DELETE/users/<UID>/leads/<LEAD_ID> — delete a lead

Each lead document has two fields: j (the lead as a JSON string) and u (last-updated time in milliseconds). The app keeps the newest version, so always send a current u.

curl -X PATCH "<BASE>/users/<UID>/leads/api123?key=<API_KEY>" \
  -H "Authorization: Bearer <idToken>" -H "Content-Type: application/json" \
  -d '{"fields":{"j":{"stringValue":"{\"id\":\"api123\",\"business\":\"Palm Realty\",\"status\":\"NEW\",\"created\":\"2026-11-17\",\"email\":\"owner@palmrealty.ae\",\"findings\":[],\"history\":[]}"},"u":{"integerValue":"1795000000000"}}}'

Lead object (inside j)

KeyMeaning
id, createdSame id as the document; created date YYYY-MM-DD
business, website, email, phone, wa, city, country, niche, dm, role, source, langContact and context
statusNEW · PITCHED · BOUNCED · FOLLOWED-UP · REPLIED · HOT · CALL · PROPOSAL · AGREEMENT · WON · ACTIVE · LOST · LATER · DNC
value, price, pkg, setupFee, closeBy, owner, tags[]Deal details
tasks[]{id, t, due, time, done, key, act, auto}
meetings[]{id, title, start (ISO), dur, link, gid, status}
findings[], history[], notesAudit findings, activity log, notes
sent, fu, fuStage, subject, invoice, invNo, paid, startPitch, follow-up and invoice dates

Profile & settings

GET/users/<UID>/crm/meta — your profile, business details, settings (field j, JSON). Write with PATCH like leads.

3. Public endpoints

GET/config/plans?key=<API_KEY> — packages & prices (field j, JSON).
POST/messages?key=<API_KEY> — contact form. Fields: name (2–80), email, message (10–5000), optional subject, company, topic; plus status: "new" and createdAt (ISO string).

Limits & security

Services The Client Ocean uses

ServiceUsed forKey
Google Firebase (Auth, Firestore, Hosting)Accounts, data, websitebuilt in
Serper.devLive Google search resultseach user's own
Google PageSpeed InsightsSpeed auditsown or shared
Google Cloud Translation / MyMemoryClient-language translationown Google key, or free MyMemory
Google Calendar & MeetMeetings and invitesuser signs in with Google
OpenStreetMap (Nominatim, Overpass)Live business listsnone
crt.sh, Common Crawl, GDELTNew domains, free-builder sites, newsnone
Google website translatorApp interface languagesnone
open.er-api.comLive exchange ratesnone

Questions? Contact us.