Ybyatã: Google Ads API tool design

Published September 2026 · Ybyata Growth Operations Ltda · Versão em português

Status. The platform is in advanced development, with the first client clinic being onboarded. Section 3 describes intended usage of the Google Ads API, which is what the access application asks for. Section 4 describes data handling as the system actually stands on the date above.

1. Company and business model

Ybyatã Growth Operations (ybyata.com) is a Brazilian marketing agency and software company serving physiotherapy and other health clinics. Clinics pay a monthly fee. In exchange, Ybyatã runs their paid acquisition on Google Ads and Meta and operates the software that follows every lead from the ad click, through the WhatsApp conversation with the clinic's front desk, to a booked and attended evaluation appointment.

The Google Ads accounts of client clinics are linked under Ybyatã's manager account (MCC). Ybyatã's team operates them.

2. What the tool is

A single web application (Elixir/Phoenix, PostgreSQL) hosted by Ybyatã. Users sign in with their e-mail. Each clinic is a tenant with its own data, isolated by an organization id carried on every row.

Access is granted per organization. Roles: Ybyatã staff (agency) operate the linked accounts and see every clinic they manage; clinic owners see reports for their own clinic; front-desk staff (the people who answer the WhatsApp) get no advertising data at all.

The Google Ads API is called only by background jobs of this application, never by end users directly, and always with Ybyatã's own credentials. No clinic user authenticates with Google. The tool is not sold or licensed to third parties.

3. Intended API usage

3.1 Reporting (read)

Once per day per linked account, a job runs a GoogleAdsService.SearchStream query at campaign level for the previous 30 days:

SELECT campaign.id, campaign.name, campaign.status,
       segments.date, metrics.cost_micros, metrics.clicks,
       metrics.impressions, metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Results are stored keyed by campaign.id so that each clinic's dashboard shows spend, leads and booked appointments per campaign on one row, and cost per booked appointment derived from real appointments recorded in our system, not from form fills.

3.2 Offline click conversions (write)

When a lead we tracked (the landing page stores the GCLID or WBRAID on the lead record) becomes a booked or attended appointment, a job calls ConversionUploadService.UploadClickConversions with:

gclid or wbraid, conversion_action, conversion_date_time, currency, optional value;
enhanced conversions for leads: hashed (SHA-256) phone number and, when present, hashed e-mail, sent through user_identifiers.

Each upload is idempotent: a conversion is claimed in our database before the call and marked as sent on success, so retries never double-count. Conversion actions are created once per account by Ybyatã staff.

3.3 Campaign management (write, later phase)

Physiotherapy clinics need the same few campaign structures. Ybyatã staff will create and pause campaigns for managed accounts from a small set of predefined templates (for example: a search campaign for "fisioterapia" plus neighbourhood terms, with call and message assets). Services used: CampaignBudgetService, CampaignService, AdGroupService, AdGroupAdService, AdGroupCriterionService, with status changes limited to ENABLED and PAUSED. Nothing is ever removed through the API. Every mutation is triggered by a staff action or by a deterministic reconciliation job that applies exactly what staff declared; there is no autonomous bidding or budget logic.

4. Architecture and data flow

Clinic's landing page  --gclid-->  Ybyatã app (lead record)
WhatsApp Cloud API     --webhook-> Ybyatã app (conversation, appointment)
Ybyatã app background jobs  <----> Google Ads API (reports, conversion uploads,
                                    campaign mutations) using Ybyatã's OAuth
                                    refresh token and developer token,
                                    login-customer-id = Ybyatã MCC
Ybyatã app  ---> dashboards for staff and clinic owners

Credentials: the developer token, OAuth client and refresh token are Ybyatã-owned and kept in environment configuration on the server, never in the database and never in the client-facing application. Per-clinic Google data (customer id, conversion action ids) lives in the database next to the clinic's other configuration.

How personal data is handled, stated as it stands today:

Names, phone numbers and e-mail addresses are stored in ordinary database columns. They are reachable only through Ybyatã's own application and by Ybyatã staff; the database is not publicly exposed, and no clinic user or third party is given direct access to it.
Application-level encryption (AES-GCM, with the key held outside the database) is applied to conversation content (WhatsApp message bodies, the verbatim quotes our analysis stores, the analyzer's prompts and results) and to every provider access token we hold.
On the Google path, personal data never leaves the system in the clear: phone and e-mail are sent to the Google Ads API only as SHA-256 hashes, inside user_identifiers on the conversion upload, which is what enhanced conversions for leads requires. Nothing else about a patient is uploaded.

5. Volume and rate limits

Fewer than 10 linked accounts in the first year.
Reporting: one SearchStream request per account per day.
Conversion uploads: batched, a few dozen per account per day at most.
Campaign mutations: rare, staff-triggered.
Expected total: a few hundred operations per day. Jobs use exponential backoff on RESOURCE_EXHAUSTED and RATE_EXCEEDED errors.

6. Users and access

Internal: Ybyatã staff operate campaigns and see all accounts they manage.
External: clinic owners see reports for their own clinic only.
The API tool is not offered to the general public.

7. Contact

Ybyata Growth Operations Ltda, CNPJ 68.452.751/0001-82, R. Pais Leme, 215, Conj. 1713, Pinheiros, São Paulo/SP, Brasil · [email protected] · Privacy policy: ybyata.com/politica-de-privacidade