Ads & Voice

Ads and Voice are Crevio’s two outbound-growth surfaces: launch and optimize paid ad campaigns across platforms, and have an AI place real phone calls on your behalf — both metered as you go. You can just ask Crevio to launch a campaign for a product or call a lead to book a demo. Or drive it through the API: the ads surface manages the full campaign hierarchy, audiences, pixels, and leads; the voice surface places AI phone calls with a clear objective, manages your numbers, and tracks consent. Both domains have many endpoints — this guide covers the workflow and the key calls. See the API reference for the exhaustive parameter lists.

Crevio ads run across multiple platforms with a standard hierarchy: Campaign → Ad Group → Ad, plus custom audiences, pixels & conversions, and lead forms.

Connect an ads account first

Ads need their own connection — separate from your other integrations — before you can sync or create campaigns.

curl -X POST https://api.crevio.co/v1/ads/connect \
  -H "Authorization: Bearer YOUR_API_TOKEN"

ChatGPT ads have no OAuth step. Create an API key in ChatGPT Ads Manager under Settings and send it with platform: "openaiads"; one key covers exactly one ad account. OpenAI has no read-only scope, so the key carries full campaign write access.

curl -X POST https://api.crevio.co/v1/ads/connect \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform": "openaiads", "api_key": "sk-ads-..."}'

A ChatGPT ad is a chat card: headline (3–50 characters), body (up to 100), image_url and link_url are all required. Budgets are lifetime-only with an end_date, bid_strategy plus bid_amount are required, and targeting is by country only.

Campaign creation will fail until an ads account is connected. Always run POST /ads/connect first.

The campaign hierarchy

Once connected, build top-down:

# 1. Create a campaign
curl -X POST https://api.crevio.co/v1/ads/campaigns \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Listing promo", "objective": "conversions" }'

# 2. Add an ad group under it, then 3. ads under the group
curl -X POST https://api.crevio.co/v1/ads/ad-groups \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "campaign": "adcmp_abc123", "name": "Lookalike — buyers" }'

Audiences, targeting, pixels, and conversions

Custom audiences — build and reuse audience segments.
Targeting search & reach estimates — search targeting options and estimate audience reach before you spend.
Pixels & conversions — install pixels and report conversions back for optimization.
Lead forms & leads — collect leads with on-platform forms and pull the resulting leads.

Boost a post and Click-to-WhatsApp

Turn an existing organic social post into a paid ad:

curl -X POST https://api.crevio.co/v1/ads/boost \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "post": "post_abc123", "budget": 5000 }'

Click-to-WhatsApp campaigns are supported for driving conversations directly into WhatsApp.

Meta special ad categories

Meta requires housing, employment and financial ads to declare a special ad category. Send special_ad_categories with special_ad_category_country on POST /ads, POST /ads/boost or POST /ads/ctwa:

curl -X POST https://api.crevio.co/v1/ads \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "sacct_abc123",
    "ad_account_id": "act_123",
    "name": "Downtown listing",
    "goal": "traffic",
    "budget_amount": 20,
    "budget_type": "daily",
    "headline": "2-bed apartment downtown",
    "link_url": "https://example.com/listing",
    "image_url": "https://example.com/listing.jpg",
    "countries": ["US"],
    "special_ad_categories": ["HOUSING"],
    "special_ad_category_country": ["US"]
  }'

The category is set on the new campaign and can’t be added later through the API. With HOUSING, EMPLOYMENT or FINANCIAL_PRODUCTS_SERVICES, Meta rejects narrowed targeting: omit age_min, age_max and gender, and use no ZIP codes, lookalikes or location exclusions. Meta’s error comes back as the API error.

Performance reports

Pull performance reports to see spend, results, and ROAS across the hierarchy, then feed that back into optimization — or let a Task do the optimizing on a schedule.

Insights queries

GET /ads/insights runs a live performance query against the platform behind a connection, for anything the fixed reports don’t cover. The connection’s platform decides what you send:

Google Ads: any read-only GAQL SELECT in query, for example search terms, keywords with Quality Score, geo, devices, assets or conversion actions.
Meta: Graph insights fields, breakdowns and filtering on object_id, which must be the connection’s ad account (act_...) or one of its campaigns, ad sets or ads.
TikTok: ad_account_id, data_level, dimensions, metrics, from and to.

Rows come back as the platform returned them, with keys in snake_case. Google counters are strings and cost is in micros. Follow next_cursor for more rows. A query the platform rejects returns 400 with its message.

curl -G https://api.crevio.co/v1/ads/insights \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "account_id=sacct_abc123" \
  --data-urlencode "query=SELECT search_term_view.search_term, search_term_view.status, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"

search_term_view.status says whether a term is already a keyword (ADDED), a negative (EXCLUDED) or neither (NONE).

Keywords and negatives

POST /ads/keywords adds keywords to a Google Search ad group (ad_group_id), keeping the ones already there. With "negative": true it adds negatives to one ad group (ad_group_id) or one campaign (campaign_id), never both, and keeps every negative already there. Each keyword is { "text": ..., "match_type": "exact" | "phrase" | "broad" }.

curl -X POST https://api.crevio.co/v1/ads/keywords \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "sacct_abc123", "negative": true, "campaign_id": "21345678901", "keywords": [{ "text": "free", "match_type": "broad" }] }'

Adding a campaign-level negative reads the campaign’s current list live first. When Google’s daily API quota is used up, that read can’t be trusted, so the request fails with 503 ad_provider_unavailable instead of overwriting newer negatives. Retry later, or add the negative at the ad-group level. When the agent makes these changes, it always asks for approval first.

Voice

Crevio places autonomous AI phone calls — inbound and outbound. You give the AI an objective and an opening line, and it makes the call. Voice is billed per minute.

Place a call

POST /calls starts an outbound AI call.

Field	Purpose
`to_number`	The number to call
`objective`	What the AI should accomplish on the call
`first_message`	The opening line the AI says
`purpose`	The reason/category for the call

curl -X POST https://api.crevio.co/v1/calls \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+15551234567",
    "objective": "Follow up with the lead about the home they inquired about and book a viewing.",
    "first_message": "Hi, this is Maple Realty following up on the listing you asked about.",
    "purpose": "lead_follow_up"
  }'

import { Crevio } from "@crevio/sdk";

const crevio = new Crevio({ apiKeyAuth: "YOUR_API_TOKEN" });

await crevio.calls.create({
  to_number: "+15551234567",
  objective:
    "Follow up with the lead about the home they inquired about and book a viewing.",
  first_message: "Hi, this is Maple Realty following up on the listing you asked about.",
  purpose: "lead_follow_up",
});

Call +1 555 123 4567 to follow up on the listing they inquired about
and book a viewing.

Call events

Subscribe a webhook or an event-triggered Task to call.started and call.ended instead of polling GET /calls. Both carry the call object; call.ended arrives after the call is billed, with its transcript and credits_charged. The calls API and these events cover phone calls only. A call the account owner takes with their assistant in the browser stays in that chat: GET /calls doesn’t list it, and it sends no events.

Phone numbers

Provision a number to call from (and to receive inbound calls), and release it when you’re done.

# Provision a number
curl -X POST https://api.crevio.co/v1/phone-numbers \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Release a number
curl -X DELETE https://api.crevio.co/v1/phone-numbers/phon_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Texting

A phone number can send and receive texts once texting is on. POST /phone-numbers/{id}/texting turns it on and returns the number with its texting state: active, registering, or unsupported. While a US number is registering, carriers must approve the business before texts deliver. Send the owner sms_registration_url, a form for the business’s legal details that stays valid for 7 days. Calling the endpoint again re-reads the state and returns a fresh link once the old one expires. Texting becomes active on its own after approval. Three booleans on PATCH /phone-numbers/{id} control what the number does with texts. All default to false.

Field	Effect
`answer_texts`	The number’s assistant replies to incoming texts, following `inbound_objective`. It can look up the texter’s orders, book free services, take a message for the owner, and record opt-outs.
`text_back_missed_calls`	Texts a caller when a forwarded call (`call_routing: "forward"`) isn’t picked up.
`text_new_leads`	Texts a new lead who left a phone number, up to three times (right away, after 1 day, then after 2 more days), until they reply, book, or opt out.

POST /sms-messages sends one text. If the recipient texted the number in the last 24 hours it is a reply and sends immediately. Otherwise purpose applies: transactional (default) needs consent on file, and marketing needs written consent (web_form, checkout, or api). Texting first only sends between 8am and 9pm in the recipient’s time zone, and is capped at 3 texts per number per day. The first text to a number gets the business name and “Reply STOP to opt out.” added. Each segment (160 GSM-7 characters, or 70 with other characters) costs 1 credit. Pass an Idempotency-Key header to make retries safe.

# Send a text
curl -X POST https://api.crevio.co/v1/sms-messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567", "body": "Your order shipped today.", "purpose": "transactional" }'

# Read a conversation, newest first
curl "https://api.crevio.co/v1/sms-messages?counterpart=%2B15551234567" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Refusals return 422 with a code: no_consent, opted_out, frequency_capped, unreachable (not in the number’s country), or texting_unavailable. POST /sms-follow-ups texts a group of past customers chosen by tag or customer_ids, with message as the first text. It takes the same variables as an email, such as {{ customer.first_name | default: "there" }} and one follow-up 3 days later if they don’t reply. These are marketing texts, so customers without written marketing consent, opted-out numbers, and numbers the line can’t text are skipped. The response counts them per reason. Read the outcome with GET /sms-follow-ups/stats?launch_id=... and the individual follow-ups with GET /sms-follow-ups?launch_id=.... POST /sms-follow-ups/{id}/cancel ends one as canceled, along with any text still waiting to go out.

curl -X POST https://api.crevio.co/v1/sms-follow-ups \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "past-clients", "message": "Hi {{ customer.first_name | default: \"there\" }}, we have openings next week. Want one?" }'
# { "object": "sms_follow_up_launch", "launch_id": "launch_...", "enrolled": 9, "skipped": { "no_written_consent": 31 } }

A reply of STOP (or UNSUBSCRIBE, CANCEL, END, QUIT) adds the number to the do-not-call suppressions, which blocks both texts and calls, and ends its follow-ups. START removes the opt-out. Voice includes compliance tooling. Record TCPA consents before calling, and maintain do-not-call suppressions so the AI never dials a suppressed number.

# Record consent
curl -X POST https://api.crevio.co/v1/phone-consents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551234567" }'

# Suppress a number (do not call)
curl -X POST https://api.crevio.co/v1/phone-suppressions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15559876543" }'

Calls are billed per minute and draw down credits. Always confirm you have valid consent before placing outbound calls.

Next steps

Social

Boost organic posts into paid ads.

Tasks

Automate campaign optimization and follow-up calls.

Usage & credits

See how per-minute calls and ad operations bill.

API reference

Every ads and voice endpoint and parameter.

Getting started

AI & agents

Core concepts

Integrations

Recipes

Ads

Connect an ads account first

The campaign hierarchy

Audiences, targeting, pixels, and conversions

Boost a post and Click-to-WhatsApp

Meta special ad categories

Performance reports

Insights queries

Keywords and negatives

Voice

Place a call

Call events

Phone numbers

Texting

Next steps

Social

Tasks

Usage & credits

API reference

​Ads

​Connect an ads account first

​The campaign hierarchy

​Audiences, targeting, pixels, and conversions

​Boost a post and Click-to-WhatsApp

​Meta special ad categories

​Performance reports

​Insights queries

​Keywords and negatives

​Voice

​Place a call

​Call events

​Phone numbers

​Texting

​Consent and do-not-call (TCPA)

​Next steps

Social

Tasks

Usage & credits

API reference

Ads

Connect an ads account first

The campaign hierarchy

Audiences, targeting, pixels, and conversions

Boost a post and Click-to-WhatsApp

Meta special ad categories

Performance reports

Insights queries

Keywords and negatives

Voice

Place a call

Call events

Phone numbers

Texting

Consent and do-not-call (TCPA)

Next steps