Public API

AdvisorOS CRM — Public API

REST API for creating leads and retrieving CRM contacts. Designed for use with Make.com and other automation tools.

Veřejné API

AdvisorOS CRM — Veřejné API

REST API pro vytváření leadů a stahování kontaktů z CRM. Navrženo pro Make.com a další automatizační nástroje.

 Base URL
 https://europe-west3-advisoros-prod.cloudfunctions.net 

Authentication

Every request must include a token query parameter. Generate your token from the AdvisorOS app → Settings → API Integration section.

Autentizace

Každý požadavek musí obsahovat query parametr token. Token vygenerujete v aplikaci AdvisorOS → Nastavení → API Propojení.

?token=YOUR_API_TOKEN

Condition	Status	Response
Token missing	401	`{"error": "Missing token"}`
Token invalid	403	`{"error": "Invalid token"}`
Rate limit exceeded	429	`{"error": "Too Many Requests"}`
Stav	HTTP Status	Odpověď
Token chybí	401	`{"error": "Missing token"}`
Neplatný token	403	`{"error": "Invalid token"}`
Překročen limit požadavků	429	`{"error": "Too Many Requests"}`

POST

/injestLead

Creates a new lead in the authenticated user's CRM pipeline. Used by the Vytvořit nový lead Make.com module.

Request

Vytvoří nový lead v CRM pipeline přihlášeného uživatele. Využíváno Make.com modulem Vytvořit nový lead.

Požadavek

 POST /injestLead?token=YOUR_API_TOKEN
 Content-Type: application/json 

Body Parameters

Field	Type	Required	Max	Description
`name`	string	No	100	Full name. Default: `"Neznámý kontakt"`
`email`	string	No	100	Email address
`phone`	string	No	50	Phone number
`source`	string	No	100	Traffic source. Default: `"Make.com"`
`notes`	string	No	2000	Additional notes

All string fields are HTML-escaped and truncated server-side.

Parametry těla požadavku

Pole	Typ	Povinné	Max	Popis
`name`	string	Ne	100	Celé jméno. Výchozí: `"Neznámý kontakt"`
`email`	string	Ne	100	E-mailová adresa
`phone`	string	Ne	50	Telefonní číslo
`source`	string	Ne	100	Zdroj kontaktu. Výchozí: `"Make.com"`
`notes`	string	Ne	2000	Poznámky

Všechny řetězcové hodnoty jsou na serveru HTML-escapovány a zkráceny na max. délku.

Example Request

Příklad požadavku

{
  "name": "Jan Novák",
  "email": "jan.novak@example.com",
  "phone": "+420 777 123 456",
  "source": "Facebook Ads",
  "notes": "Zájem o životní pojištění."
}

Responses

Status	Body	Cause
200 OK	`{"success": true}`	Lead created successfully
401	`{"error": "Missing token"}`	`token` param not provided
403	`{"error": "Invalid token"}`	Token does not match any user
405	`{"error": "Method not allowed"}`	Request method is not POST
429	`{"error": "Too Many Requests"}`	Exceeded 60 req/min per token
500	`{"error": "Error saving lead"}`	Internal server error

Rate limit: 60 requests / minute per token.

Odpovědi

Status	Tělo	Příčina
200 OK	`{"success": true}`	Lead byl úspěšně vytvořen
401	`{"error": "Missing token"}`	Parametr `token` chybí
403	`{"error": "Invalid token"}`	Token neodpovídá žádnému uživateli
405	`{"error": "Method not allowed"}`	Metoda požadavku není POST
429	`{"error": "Too Many Requests"}`	Překročeno 60 req/min na token
500	`{"error": "Error saving lead"}`	Interní chyba serveru

Rate limit: 60 požadavků / minutu na token.

GET

/listNewClients

Returns a paginated list of CRM clients, optionally filtered to those created after a given cursor. Used by the Sledovat nový kontakt v CRM Make.com trigger module.

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	API token
`since`	string / number	No	Return only clients created after this point. Accepts Unix timestamp in ms (integer) or ISO 8601 string. Omit to return all clients.
`limit`	integer	No	Max results. Range: 1–500. Default: `100`.

Vrátí stránkovaný seznam klientů CRM, volitelně filtrovaný na kontakty vytvořené po daném časovém bodu. Využíváno Make.com trigger modulem Sledovat nový kontakt v CRM.

Query parametry

Parametr	Typ	Povinné	Popis
`token`	string	Ano	API token
`since`	string / number	Ne	Vrátí jen klienty vytvořené po tomto bodu. Přijímá Unix timestamp v ms (integer) nebo ISO 8601 řetězec. Vynecháním se vrátí všichni klienti.
`limit`	integer	Ne	Max. počet výsledků. Rozsah: 1–500. Výchozí: `100`.

Example Request

Příklad požadavku

 GET /listNewClients?token=YOUR_API_TOKEN&since=2025-11-03T17:53:00.000Z&limit=50 

Success Response — 200 OK

Úspěšná odpověď — 200 OK

{
  "clients": [
    {
      "id": "abc123def456",
      "firstName": "Jan",
      "lastName": "Novák",
      "email": "jan.novak@example.com",
      "phone": "+420 777 123 456",
      "createdAt": "2025-11-03T17:53:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Unique Firestore document ID of the client
`firstName`	string	First name
`lastName`	string	Last name
`email`	string	Email address
`phone`	string	Phone number
`createdAt`	string (ISO 8601) \| null	Creation timestamp. `null` for legacy records.

Results are ordered by createdAt ascending. Clients without a createdAt value are included only when since is not provided.

Pole odpovědi

Pole	Typ	Popis
`id`	string	Unikátní ID dokumentu klienta ve Firestore
`firstName`	string	Křestní jméno
`lastName`	string	Příjmení
`email`	string	E-mailová adresa
`phone`	string	Telefonní číslo
`createdAt`	string (ISO 8601) \| null	Čas vytvoření. `null` u starších záznamů bez časového razítka.

Výsledky jsou seřazeny vzestupně dle createdAt. Klienti bez createdAt jsou zahrnuti pouze tehdy, když parametr since není zadán.

Error Responses

Status	Body	Cause
200 OK	`{"clients": [...]}`	Success
401	`{"error": "Missing token"}`	`token` param not provided
403	`{"error": "Invalid token"}`	Token does not match any user
405	`"Method not allowed"`	Request method is not GET
429	`{"error": "Too Many Requests"}`	Exceeded 120 req/min per token
500	`{"error": "Server error"}`	Internal server error

Rate limit: 120 requests / minute per token.

Chybové odpovědi

Status	Tělo	Příčina
200 OK	`{"clients": [...]}`	Úspěch
401	`{"error": "Missing token"}`	Parametr `token` chybí
403	`{"error": "Invalid token"}`	Token neodpovídá žádnému uživateli
405	`"Method not allowed"`	Metoda požadavku není GET
429	`{"error": "Too Many Requests"}`	Překročeno 120 req/min na token
500	`{"error": "Server error"}`	Interní chyba serveru

Rate limit: 120 požadavků / minutu na token.

GET

/listNewLeadMagnetSubmissions

Returns lead magnet form submissions captured from public Linktree-style profile cards (MarketingOS — Lead Magnet block). Used by the Sledovat nový lead magnet Make.com trigger module.

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	API token (same token as for `listNewClients` / `injestLead`)
`since`	string / number	No	Return only submissions created after this point. Accepts Unix timestamp in ms (integer) or ISO 8601 string. Omit to return all submissions.
`limit`	integer	No	Max results. Range: 1–500. Default: `100`.

Vrátí seznam odeslaných formulářů z lead magnet bloků na veřejných vizitkách (MarketingOS — Lead Magnet). Využíváno Make.com trigger modulem Sledovat nový lead magnet.

Query parametry

Parametr	Typ	Povinné	Popis
`token`	string	Ano	API token (stejný jako pro `listNewClients` / `injestLead`)
`since`	string / number	Ne	Vrátí jen submissions vytvořené po tomto bodu. Přijímá Unix timestamp v ms (integer) nebo ISO 8601 řetězec. Vynecháním se vrátí všechny.
`limit`	integer	Ne	Max. počet výsledků. Rozsah: 1–500. Výchozí: `100`.

Example Request

Příklad požadavku

 GET /listNewLeadMagnetSubmissions?token=YOUR_API_TOKEN&since=2026-05-04T10:15:30.000Z&limit=50 

Success Response — 200 OK

Úspěšná odpověď — 200 OK

{
  "submissions": [
    {
      "id": "abc123def",
      "blockId": "k7g3m9p2x",
      "blockTitle": "10 finančních triků pro rok 2026",
      "pdfFileName": "10-financnich-triku.pdf",
      "email": "jan.novak@example.com",
      "firstName": "Jan",
      "lastName": "Novák",
      "phone": "+420 777 123 456",
      "source": "MarketingOS: Lead Magnet",
      "createdAt": "2026-05-04T10:15:30.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Unique Firestore document ID of the submission
`blockId`	string	ID of the lead magnet block on the user's profile card
`blockTitle`	string	Visible title of the lead magnet
`pdfFileName`	string	Original filename of the gated PDF
`email`	string	Contact email (always present — required field)
`firstName`	string	First name (only if the block requested it)
`lastName`	string	Last name (only if the block requested it)
`phone`	string	Phone number (only if the block requested it)
`source`	string	Traffic source attribution (e.g. `direct`, `instagram`, `facebook`)
`createdAt`	string (ISO 8601) \| null	Submission timestamp

Results are ordered by createdAt ascending. Optional fields not requested by the block come back as empty strings.

Pole odpovědi

Pole	Typ	Popis
`id`	string	Unikátní ID dokumentu odeslání ve Firestore
`blockId`	string	ID lead magnet bloku na vizitce
`blockTitle`	string	Název lead magnetu (zobrazený klientovi)
`pdfFileName`	string	Původní název nahraného PDF
`email`	string	E-mailová adresa (vždy přítomna — povinné pole)
`firstName`	string	Křestní jméno (jen pokud blok pole vyžaduje)
`lastName`	string	Příjmení (jen pokud blok pole vyžaduje)
`phone`	string	Telefon (jen pokud blok pole vyžaduje)
`source`	string	Zdroj návštěvnosti (např. `direct`, `instagram`, `facebook`)
`createdAt`	string (ISO 8601) \| null	Čas odeslání formuláře

Výsledky jsou seřazeny vzestupně dle createdAt. Volitelná pole, která blok nevyžaduje, se vrací jako prázdný řetězec.

Error Responses

Status	Body	Cause
200 OK	`{"submissions": [...]}`	Success
401	`{"error": "Missing token"}`	`token` param not provided
403	`{"error": "Invalid token"}`	Token does not match any user
405	`"Method not allowed"`	Request method is not GET
429	`{"error": "Too Many Requests"}`	Exceeded 120 req/min per token
500	`{"error": "Server error"}`	Internal server error

Rate limit: 120 requests / minute per token.

Chybové odpovědi

Status	Tělo	Příčina
200 OK	`{"submissions": [...]}`	Úspěch
401	`{"error": "Missing token"}`	Parametr `token` chybí
403	`{"error": "Invalid token"}`	Token neodpovídá žádnému uživateli
405	`"Method not allowed"`	Metoda požadavku není GET
429	`{"error": "Too Many Requests"}`	Překročeno 120 req/min na token
500	`{"error": "Server error"}`	Interní chyba serveru

Rate limit: 120 požadavků / minutu na token.

GET

/validateApiToken

Validates an API token and returns the owner's profile metadata. Used by the Make.com app for connection testing and metadata population (so the owner's email shows next to the connection in the Make.com UI).

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	API token

Ověří platnost API tokenu a vrátí metadata vlastníka. Používá Make.com aplikace pro test connectionu a vyplnění metadat (aby se v Make.com UI u připojení zobrazil e-mail vlastníka tokenu místo náhodného ID).

Query parametry

Parametr	Typ	Povinné	Popis
`token`	string	Ano	API token

Example Request

Příklad požadavku

GET /validateApiToken?token=YOUR_API_TOKEN

Success Response — 200 OK

Úspěšná odpověď — 200 OK

{
  "email": "advisor@example.cz",
  "name": "Jan Novák",
  "uid": "abc123def456"
}

Response Fields

Field	Type	Description
`email`	string	Contact email of the token owner (from the AdvisorOS profile)
`name`	string	Display name of the token owner
`uid`	string	Internal user ID (Firebase Auth UID)

Pole odpovědi

Pole	Typ	Popis
`email`	string	Kontaktní e-mail vlastníka tokenu (z profilu v AdvisorOS)
`name`	string	Zobrazované jméno vlastníka tokenu
`uid`	string	Interní ID uživatele (Firebase Auth UID)

Error Responses

Status	Body	Cause
401	`{"error": "Missing token"}`	`token` param not provided
403	`{"error": "Invalid token"}`	Token does not match any user
405	`{"error": "Method not allowed"}`	Request method is not GET
429	`{"error": "Too Many Requests"}`	Exceeded 60 req/min per token
500	`{"error": "Server error"}`	Internal server error

Rate limit: 60 requests / minute per token.

Chybové odpovědi

Status	Tělo	Příčina
401	`{"error": "Missing token"}`	Parametr `token` chybí
403	`{"error": "Invalid token"}`	Token neodpovídá žádnému uživateli
405	`{"error": "Method not allowed"}`	Metoda požadavku není GET
429	`{"error": "Too Many Requests"}`	Překročeno 60 req/min na token
500	`{"error": "Server error"}`	Interní chyba serveru

Rate limit: 60 požadavků / minutu na token.

Make.com Integration

This API powers the AdvisorOS CRM app on Make.com. Module mapping:

Make.com module	Endpoint
Sledovat nový kontakt v CRM	`GET /listNewClients`
Sledovat nový lead magnet	`GET /listNewLeadMagnetSubmissions`
Vytvořit nový lead	`POST /injestLead`

All three modules share a single connection (apiToken). No separate credential is needed.

Trigger cursor behaviour

Both watch triggers store the createdAt value of the last processed item as their cursor. On subsequent polls, this value is passed as the since parameter. The API accepts both ISO 8601 strings and Unix timestamps in milliseconds.

Connection verification

The Make.com connection test calls GET /validateApiToken?token=TOKEN. A 403 response means the token is invalid; a 200 response returns the owner's email/name (used to populate connection metadata in the Make.com UI).

Integrace s Make.com

Toto API pohání aplikaci AdvisorOS CRM na Make.com. Mapování modulů:

Make.com modul	Endpoint
Sledovat nový kontakt v CRM	`GET /listNewClients`
Sledovat nový lead magnet	`GET /listNewLeadMagnetSubmissions`
Vytvořit nový lead	`POST /injestLead`

Všechny tři moduly sdílí jednu connection (apiToken). Žádné další credential není potřeba.

Chování kurzoru triggeru

Oba watch triggery si ukládají hodnotu createdAt posledního zpracovaného záznamu jako kurzor. Při každém dalším dotazu je tato hodnota předána jako parametr since. API přijímá jak ISO 8601 řetězce, tak Unix timestamp v milisekundách.

Ověření připojení

Test připojení v Make.com volá GET /validateApiToken?token=TOKEN. Odpověď 403 znamená neplatný token; odpověď 200 vrátí e-mail a jméno vlastníka tokenu (použito pro vyplnění metadat connectionu v Make.com UI).

Changelog

Version	Date	Notes
1.0	2026-04-22	Initial public API release — `injestLead` + `listNewClients`
1.1	2026-05-05	Added `listNewLeadMagnetSubmissions` polling endpoint for MarketingOS lead magnet capture
1.2	2026-05-05	Added `validateApiToken` connection-test endpoint (returns owner email + name); normalized all `injestLead` error responses to JSON `{error: "..."}`

Historie změn

Verze	Datum	Poznámky
1.0	2026-04-22	První veřejné vydání API — `injestLead` + `listNewClients`
1.1	2026-05-05	Přidán polling endpoint `listNewLeadMagnetSubmissions` pro sběr leadů z MarketingOS lead magnet bloků
1.2	2026-05-05	Přidán endpoint `validateApiToken` pro test connectionu v Make.com (vrací e-mail + jméno vlastníka); error responses v `injestLead` normalizovány na JSON `{error: "..."}`