Lifecycle · Draft

Onboarding — API Endpoint Cross-Check

Created 11 Jun 2026·Updated 11 Jun 2026

Latest change: ADR 0003: Meta 2-Tier child BM primary model; OAuth flow and official API sources

Draft document — deep-dive spec incomplete; content will be updated before and during build. Do not treat as signed-off implementation detail. Pack overview

Purpose

Maps every onboarding provisioning step to concrete APIs (or documents UI-only / human gaps). Use this before implementation to avoid assuming automation where the platform offers no endpoint.

Verify at implementation — pin API versions; endpoints rename across releases. Official docs linked per row.

Billing policy (non-negotiable)

Rule Detail
Never ask client for platform billing details No card, bank account, or payment profile on Google/Meta/TikTok/DV360 during onboarding — ever
Kobi defines platform billing Agency MCC / Business Portfolio / Business Center billing is pre-configured by Kobi ops/finance before tenant onboarding
New accounts inherit agency billing Shell ad accounts created via API are linked to the existing Kobi agency payment method or monthly invoice program — not client instruments
Client pays Kobi Monthly invoice from Kobi (media pass-through + fees) — internal ERP; separate from platform billing APIs
Plan monthly limit on create monthly_media_cap + credit_sub_limit from plan_id applied at provisioning (Meta spend_cap, internal guardrails on all channels)

Onboarding connectors must not expose payment forms or store client PCI data. New accounts inherit agency billing from MCC/BM/BC — no per-client billing step.

Agency one-time setup vs per-client warnings

Class Examples Per-client ONB-* warning?
🔧 PRE — manual once before first client MCC monthly invoicing, agency business verification (Kobi entity), Meta extended credit, TikTok BC funding, agency MCA, TikTok app Live, DV360 contract Nopre-implementation checklist only
✅ Default automation New account inherits payer; plan caps on create; budgets from approved plans via API No
🚩 ONB — per-tenant onboarding failure Page/IG consent timeout, missing plan limits on registry, scope missing on token, MC policy blocking SKU Yes

Billing is never a per-client warning when agency master is configured (our default). Connectors assume master exists; they do not emit platform.onboarding.red_flag for monthly invoicing or extended credit.

Budget allocation (plans) — not billing

Spend is not configured by asking anyone for payment — it is allocated programmatically from approved media plans:

Phase Mechanism API
Onboarding monthly_media_cap, credit_sub_limit on tenant_registry; Meta spend_cap on create ✅ Meta API; ✅ internal guardrails Google/TikTok
Plan approved Channel budgets per plan_version Google CampaignBudgetService; Meta ad set budgets; TikTok campaign budget APIs
Optimization / revise Change sets within guardrails Same budget mutate APIs + qc.spend vs approved plan

As long as APIs support budget mutate (they do), no billing-side warning — agency payer already attached; only budget amounts change from plans.

Business verification policy (Kobi entity — not client)

Rule Detail
Default entity Kobi legal entity on MCC / Business Portfolio / Business Center — never client incorporation docs for platform business verification
Shell accounts inherit Client ad accounts are shells under verified agency masters; connectors do not start a separate client-entity verification flow
Not the same as domain verify Domain = prove ownership of client website (DNS/meta-tag). Business = prove who operates the ad account — Kobi agency
No per-client ONB Incomplete agency business verification is PRE-* (pre-launch), same as billing — not platform.onboarding.red_flag per tenant
Google bulk path Complete / maintain at MCC Verification Hub (bulk across managed accounts) if no submit API — acceptable default
API where available Poll status via platform APIs where exposed; submission often UI-only at agency level

Clients never submit: tax IDs, business licenses, or utility bills to Google/Meta/TikTok for agency-managed shell accounts.


Legend

Symbol Meaning
Fully automatable via API (agent/connector)
⚠️ Partial — API exists but needs human step, UI fallback, or incomplete fields
No public API — human / UI / client action only (per-client)
🔧 Agency one-time setup — manual OK; pre-launch checklist; no per-client warning
🚩 Red flag (ONB-*) — per-tenant onboarding blocker only

Summary (gaps at a glance)

Platform Fully API Partial ⚠️ Human/UI ❌ Red flags 🚩
Tenant registry 1 0 0 0
Google Ads 8 2 1 0
Merchant Center 5 1 0 0
GA4 (optional Admin) 4 1 0 0
Meta 9 3 1 0
TikTok 6 2 0 0
DV360 2 0 0 1 (GMP contract — PRE)
CRM 1 0 0 0
Cross-cutting 2 2 4

Per-client onboarding blockers (ONB- only):* client Page/IG OAuth consent (Meta), plan limits missing on registry, scope/token failures, optional DNS for domain verify.

Pre-launch (🔧 PRE — no per-client warning): agency MCC monthly invoicing + Kobi entity business verification, Meta BM verification, TikTok BC verification, Meta extended credit, TikTok BC funding, agency MCA, TikTok app Live, DV360 contract, GTM publish (deferred).

Business vs domain verification

Type Whose entity / asset Default owner Per-client ONB?
Business verification Kobi legal entity on MCC / BM / BC Ops — PRE-7…PRE-9 No
Domain verification Client website URL Implementation guide (+ optional DNS delegate) Only if SKU requires events and DNS blocked

TikTok developer app (one-time Kobi task — not a client warning)

Kobi submits a developer app to TikTok for review (privacy policy, demo video). When approved, status = Live → Marketing API creates real advertisers like Google/Meta.

Client involved? No
Blocks each onboarding? No — only blocks selling TikTok SKU until done
Where tracked? Platform access pre-implementation checklist — not ONB-* per tenant

If Live: TikTok rows below are same as Meta. Sandbox = engineering only.

Domain verification (not GA4, not Search Console)

Proves domain ownership to ad platforms (usually DNS TXT or meta tag on client site).

Platform Verify in GA4 / GSC required?
Meta Business Settings → Domains No
Google Ads Site / conversion setup docs No
TikTok Events Manager allowlist No

Phase 1: include steps in implementation guide; optional HITL if client delegates DNS. Not a connector API requirement for account create.


0. Tenant registry (Kobi internal)

Onboarding step Sub-item API / action Auto Notes
Create tenant tenant_id, SKU, vertical Internal POST /tenants (TBD) Not a platform API
Store platform ID map onboarding_record Internal registry CRUD Populated as each platform step completes
ToS + consent Legal capture Internal consent service Timestamp + version; client confirms in portal

1. Google Ads (Kobi MCC)

Onboarding step Sub-item API (Google Ads API) Auto Notes
Apply plan entitlements monthly_media_cap, channels Internal tenant_registry See provisioning spec §1
Create shell account Customer under MCC CustomerService.MutateCustomercreate_customer_client Create account
Apply vertical conversion template Primary/secondary actions ConversionActionService from template health / school / tourism / ecommerce
Name + currency + timezone Customer fields on create Same mutate Set in create request
Link to MCC Manager link Created as client of manager customer_id Implicit in create_customer_client
Grant API user access Automation user CustomerUserAccessService / MutateCustomerUserAccess Or pre-provision MCC-level user
Enable auto-tagging gclid CustomerService.MutateCustomer auto_tagging_enabled
Conversion actions Primary / secondary goals ConversionActionService.MutateConversionActions
Conversion goals Campaign goal mapping CustomerConversionGoalService / CampaignConversionGoalService
Link GA4 property Ads ↔ GA4 (if client granted Admin) GA4 Admin properties.googleAdsLinks.create + Ads ProductLinkService (GOOGLE_ANALYTICS) Client invites Kobi user/SA as Administrator — then fully API; skip if no grant
Enhanced Conversions Web / Leads Customer / conversion settings via API + site tag ⚠️ API configures; tag on site is GTM human/deploy
Merchant Center link Shopping ProductLinkService (MERCHANT_CENTER) + Accounts.link After sub-account + data source created
Offline conversion import CRM path ConversionUploadService / ConversionAdjustmentUploadService Upload at runtime; create actions first
Inherit agency billing on create MCC payments profile Auto via create_customer_client under billed MCC Default — no per-client step; 🔧 PRE if MCC not set up yet
Set monthly spend guardrail from plan monthly_media_cap Internal tenant_registry + qc.spend Google: no account spend-cap API — Kobi guardrail + campaign budgets from plan
Apply channel budgets from plan Post-approval execution CampaignBudgetService, campaign mutate APIs Not onboarding — no billing warning
MCC monthly invoicing (one-time) Agency master Platform UI / Google rep 🔧 PRE-1 — finance once; never per-client
Agency business / identity verification Kobi entity on MCC MCC Verification Hub (bulk) + Ads API status poll where available 🔧 / ⚠️ PRE-7not client entity; shell accounts inherit; complete once at MCC
Poll identity verification status Per customer Google Ads API customer / identity verification resources ⚠️ Read status in connector; submit via MCC UI if no API
Domain verification (client site) Client website Implementation guide — DNS / meta-tag ⚠️ Separate from business verify — not Kobi entity docs
Google Ads → BigQuery Kobi warehouse GCP BigQuery Data Transfer API (not Ads API) Ads transfer
Account status check Ready to serve GoogleAdsService.Search / customer resource Poll until not SUSPENDED / billing ok

Connector package (illustrative): googleads.onboarding.createCustomer, .createConversionActions, .linkGa4, .linkMerchantCenter, .enableAutoTagging.


2. Merchant Center (ecommerce SKU) — fully API; client supplies feed URL only

No client billing. No manual MC UI for account create. Client pastes feed URL in portal → connector runs API chain.

Onboarding step Sub-item API (Merchant API) Auto Notes
Agency MCA ready Kobi aggregator 🔧 PRE-4 — one-time ops (like MCC); not per-client
Client provides feed URL Shopify / CMS / static URL Internal intake field Only client input needed for feed
Create sub-account Under MCA Accounts.create Accounts
Create data source Scheduled fetch from URL DataSources.create Pass client feed_url
Link to Ads customer Shopping Accounts.link + Ads ProductLinkService Two API calls — still automated
Feed fetch / validate First crawl Products.list / feed diagnostics Agent polls
Policy / disapproval status Launch gate (not create) Productstatuses / Accountstatuses Async Google review — blocks shopping go-live, not onboarding complete
Website claim (store URL) MC policy Content API / MC UI fallback ⚠️ May need DNS/meta-tag — guide client; rare blocker on account create
Inherit agency MCA billing Sub-account under billed MCA Auto on Accounts.create Default — 🔧 PRE-4 if MCA not ready yet

Nothing here prevents fully automated account + feed setup except pre-existing Kobi MCA and optional website-claim verification.


We do not create GA4 properties in v1. If client grants Kobi Administrator on their existing property:

Onboarding step Sub-item API Auto Notes
Client grants GA4 Admin Invite Kobi SA / user Google Analytics access invite ⚠️ Client one-time — not billing
Link property ↔ Ads customer Two-way link GA4 Admin properties.googleAdsLinks.create + Ads ProductLinkService Link GA4 to Ads via API
Configure key events (optional) Vertical template Admin API conversion/key events If scoped in onboarding
Read SoT metrics Reporting / opt Analytics Data API runReport
Create new GA4 property properties.create Phase 3+ consideration (ADR 0002) — v1 uses invite Admin or skip; revisit if API + OAuth verification + tag path (k.js) prove viable
Deploy gtag / GTM Site Implementation guide only
Client GA4 → BigQuery Out of Kobi scope

If no GA4 Admin: skip GA4 rows; onboarding completes without link. No Search Console required for Ads↔GA4 link.


4. Meta Ads (Kobi Business Portfolio)

Tenant model (ADR 0003): Child BM per client via 2-Tier BM — primary path. Single parent BM (≤5 ad accounts) = fallback until PRE-10. Meta Ads doc · provisioning §5b

Onboarding step Sub-item API (Graph / Marketing API) Auto Notes
Client Connect Meta + IG OAuth — required for 2-Tier Facebook Login for Business ⚠️ User token + Page; see provisioning §5
Create child BM 2-Tier (primary) POST /{parent_bm_id}/[owned_businesses](https://developers.facebook.com/docs/marketing-api/reference/business/owned_businesses/) ✅¹ User token + shared_page_idsetup guide. ¹PRE-10
Create ad account In child BM (2-Tier) or parent BM (fallback) POST /{business-id}/adaccount ✅² ²Fallback: parent BM system user, max 5 API accounts — help
Create system user In child BM (2-Tier) POST /{child_bm_id}/[system_users](https://developers.facebook.com/docs/marketing-api/system-users) Parent system user only for fallback path
Generate system user token Long-lived POST /{system-user-id}/access_tokens Per-tenant Secret Manager
Share parent credit to child LOC + spend limit Onboard at scale ✅³ ³PRE-2
Set ad account spend_cap from plan credit_sub_limit POST /act_{ad-account-id} spend_cap See provisioning spec
Set ad account name / currency Fields on create Same
Apply vertical event template Pixel standard events Pixel + CAPI config APIs Template from provisioning_template.{vertical}
Share Page with Kobi BM Partner / agency share POST /{page-id}/agencies or partner invite ⚠️ Fallback if OAuth share insufficient
Assign ad account to system user Asset access POST /{ad-account-id}/assigned_users or Business asset API Child BM system user in 2-Tier path
Create Meta Pixel Web events POST /act_{ad-account-id}/adspixels
Share pixel with account Pixel assignment Asset connection APIs
CAPI endpoint config Server events Pixel + POST /{pixel-id}/events (runtime) Relay URL is Kobi infra
Create product catalog Ecommerce POST /{business-id}/owned_product_catalogs Feed upload: POST /{catalog-id}/items_batch
Offline event set CRM offline POST /{business-id}/offline_conversion_data_sets
Partner invite to client BM Client Page access POST /{business-id}/managed_businesses / partner request flows ⚠️ Client must accept — not fully headless
Link client Page + IG Creative / identity Page access + act_{id}/promote_pages etc. ⚠️ Requires client asset ownership or partner share
Domain verification Optimization events Business Settings / verification APIs limited Often DNS TXT — human
Inherit agency billing on create Extended credit / monthly invoice on Kobi BM Auto on adaccount create under billed BM Default — 🔧 PRE-2 if BM credit not set up yet (one-time finance)
Apply ad set / campaign budgets from plan Post-approval Marketing API budget fields Programmatic from plan_version — not billing
Agency business verification Kobi entity on BM Business Settings UI; status via Graph where exposed 🔧 PRE-8 — Kobi docs only; not client entity; not per-client ONB
Special Ad Categories Schools / housing Set on campaign/ad set create At execution; flag in onboarding template

5. TikTok Ads (Kobi Business Center)

Onboarding step Sub-item API (Marketing API v1.3) Auto Notes
Create advertiser Under BC /open_api/v1.3/advertiser/create/ or /bc/advertiser/create/ Requires Kobi app Live (one-time pre-launch); BC admin assigns app
Apply vertical Events API template Pixel events by business type Pixel create + event config ⚠️ From provisioning_template.{vertical}
Internal spend guardrail monthly_media_cap from plan Internal tenant config No Google account-level spend cap API
Assign advertiser to app OAuth scope BC asset assign endpoints ⚠️ BC admin step
OAuth access + refresh token Automation /open_api/v1.3/oauth2/access_token/ After advertiser auth
Create pixel Web events /open_api/v1.3/pixel/create/
Events API Server events /open_api/v1.3/event/track/ (runtime)
Catalog / catalog ads Ecommerce Catalog-related endpoints (per app approval) ⚠️ Confirm scopes at app review
Agency business verification Kobi entity on BC TikTok for Business UI 🔧 PRE-9 — one-time; not client entity; not per-client ONB
Inherit agency BC billing Kobi prepaid / credit on BC Auto on advertiser create under funded BC Default — 🔧 PRE-3 if BC not funded yet (one-time)
Set monthly limit from plan monthly_media_cap Internal guardrail + BC policies where API exists
Kobi TikTok app → Live One-time TikTok Developer Portal 🔧 PRE-5 — not per-client; do not sell TikTok SKU until done

6. DV360 (deferred SKU)

Onboarding step Sub-item API (Display & Video 360 API) Auto Notes
GMP / DV360 contract Partner exists 🔧 PRE-6 — sales once; not per-client ONB
Create advertiser Under partner advertisers.create DV360 API
Grant API user role Standard / Admin DV360 UI user management; users service (service account) ⚠️ display-video-user-management scope
Floodlight / CM360 Legacy attribution Campaign Manager API (separate product) ⚠️ Prefer GA4-only path
IO template Structure insertionOrders.create (at execution) Onboarding may only reserve advertiser shell

7. CRM integration

Onboarding step Sub-item API Auto Notes
Register webhook Conversion export Internal POST /integrations/crm/register See internal-crm
Validate schema gclid, hashes Internal test event
Platform routing config Per tenant Internal tenant config

8. Cross-cutting (all platforms)

Onboarding step Sub-item API Auto Notes
Verification sweep Aggregate status Internal onboarding orchestrator Polls each connector health
Domain DNS records Meta / Google verify Client DNS or Kobi-managed DNS if delegated
Implementation guide (manual + GTM) Pixel/CAPI install doc Internal doc generator Phase 1 — client installs; Kobi does not publish GTM in v1
GTM container publish Tags live GTM API (optional) Deferred — guide includes GTM template for later
Domain verification instructions Meta / TikTok / Google In implementation guide ⚠️ Client DNS or meta-tag — not GA4 or Search Console
Agency billing master (🔧 PRE) MCC / BM / BC monthly invoice Platform admin UI once 🔧 PRE-1…PRE-3 — no ONB warning per client
Apply plan limits on new accounts monthly_media_cap, spend_cap Internal + Meta API At account create
Apply plan channel budgets After plan approval Platform budget mutate APIs Execution phase — not billing
Feed source connection test URL / SFTP / API Internal Feed Management Platform-agnostic
Emit client.onboarding.completed Event bus Internal Pub/Sub

Pre-launch register (🔧 PRE — not per-client warnings)

Track on platform-access pre-implementation checklist. Do not emit platform.onboarding.red_flag or block a tenant for these during onboarding.

ID One-time setup Owner
PRE-1 Google MCC + monthly invoicing / agency payments profile Finance / ops
PRE-2 Meta Business Portfolio extended credit / agency monthly invoice Finance / ops
PRE-3 TikTok Business Center agency funding Finance / ops
PRE-4 Merchant Center agency MCA (ecommerce) Ops
PRE-5 TikTok developer app Live (if TikTok SKU) Engineering
PRE-6 DV360 / GMP contract (if DV360 SKU) Sales
PRE-7 Google MCC business / advertiser identity verificationKobi entity (bulk MCC hub OK) Ops / legal
PRE-8 Meta Business Portfolio business verificationKobi entity Ops / legal
PRE-9 TikTok Business Center business verificationKobi entity Ops / legal
PRE-10 Meta 2-Tier BM access (child-BM-per-client) — required beyond 5 Meta ad accounts; Meta-rep gated, long lead Sales / partnerships

Red-flag register (per-tenant ONB only)

Emit platform.onboarding.red_flag only for per-client failures — never for PRE-* agency setup.

ID Condition Blocks Mitigation
ONB-3 Meta ad account creation limit hit (hard 5/BM via API) New tenant Meta (#6+) 2-Tier BM child-BM-per-client (PRE-10, Meta-rep gated) — not solvable per-ticket at scale
ONB-5 TikTok BC advertiser not assigned to app API 403 BC admin assignment
ONB-6 DV360 no contract DV360 SKU Exclude from plan templates
ONB-7 Client Page not shared (Meta) Social ads HITL A4; partner workflow
ONB-8 (reserved — GA4 deferred v1)
ONB-9 Merchant Center policy hold Shopping Feed QC + human
ONB-10 Required scope missing on token Channel connector Re-auth; see scope matrix
ONB-11 Plan limits not set (credit_sub_limit, caps) Spend guardrails Block complete; fix registry
ONB-12 Meta Page/IG not linked after consent timeout Social ads HITL A4; partner-invite fallback
ONB-13 Ecommerce SKU without catalog + MCA Shopping / dynamic ads Block catalog-dependent channels

Agent vs API reality (reconcile with onboarding.md)

Step in onboarding doc Doc says agent? API cross-check
Create ad accounts Yes ✅ Google, ✅ Meta (≤5/BM; child-BM-per-client beyond — PRE-10), ✅ TikTok (if SKU + app Live), ✅ DV360 (if contract)
BM partner invite Sends ⚠️ API sends invite; client accept
Domain verify (client site) Guides ⚠️ DNS — separate from business verify
Agency business verify Kobi entity on MCC/BM/BC 🔧 PRE-7…PRE-9 — not client entity; MCC bulk OK
Agency billing on new account Inherit Kobi master ✅ auto — 🔧 PRE if agency not ready (not ONB)
Plan limits + budgets from plan Yes ✅ caps on create; budget APIs on execution
GA4 setup ⏸ deferred v1
Implementation guide Yes ✅ pixels + manual + GTM template
GTM publish ⏸ deferred
Merchant Center Implied ✅ mostly API
CRM credentials Implied ✅ internal API

Recommendation: Onboarding Agent orchestrates rows; HITL for per-client ❌ only. Never raise ONB-* for agency billing, monthly invoicing, or Kobi-entity business verification — those are PRE-* before first client. Never mark client.onboarding.completed while ONB-* red flags are open for SKU channels.


Implementation order (connector build)

  1. Internal tenant + onboarding state machine
  2. Google Ads create_customer_client + conversions + auto-tagging + BQ transfer
  3. Merchant Center (if ecommerce) — after Ads customer exists
  4. Meta ad account + system user + pixel (+ catalog if SKU) + Connect flow
  5. TikTok (if SKU) — advertiser + pixel + OAuth
  6. Implementation guide — manual + GTM paths
  7. GA4 Admin — later phase
  8. DV360 after contract — advertiser shell only
  9. CRM register + test conversion round-trip