Ads
Create Meta Ads custom conversions via API
Two routes create and list the custom conversions in the customer's ad account. You define the conversion by the rule that fires it, a URL or a pixel event, and use the id in the ad set, without implementing the Meta API or going through app review.
The request
POST /api/ads/facebook_ads/custom-conversions?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"name": "Purchase completed",
"pixel_id": "900000000000001",
"rule": {
"url_contains": "/obrigado"
},
"event_type": "purchase"
}What you can do
- Create a conversion with POST /ads/facebook_ads/custom-conversions, by the rule.url_contains or rule.event rule.
- Pick the category with event_type, such as purchase, lead, add_to_cart or subscribe.
- List the account's conversions with GET /ads/facebook_ads/custom-conversions.
- Use the id in adset.facebook_ads.promoted_object.custom_conversion_id on an ad set.
Rules and limits
- The conversion is defined by the rule, and rule accepts exactly one of the keys: url_contains or event. pixel_id is required.
- The URL rule is the one verified against a real account. The event rule exists in the contract, but the platform refuses it on some pixels, and that refusal reaches you as ads_integration_error.
- event_type accepts a closed set of values. Outside it, the response is 422 with the list. Without event_type, the platform receives other.
- Idempotency-Key is required and goes in the header. The created conversion appears in the next listing without refresh.
- The listing is not paginated (200 items at most) and is cached for 600 s per connection.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Name of the custom conversion, up to 255 characters. |
| pixel_id | string | Yes | The pixel behind the rule. Required: without it the platform refuses the creation. It comes from GET /ads/facebook_ads/pixels. |
| rule.url_contains | string | No | Fires when the visited address contains this fragment. Use this key or rule.event, never both. |
| rule.event | string | No | Fires when the pixel reports this event. Use this key or rule.url_contains, never both. |
| event_type | string | No | The conversion category, such as purchase, lead or add_to_cart. Omitted, the platform receives other. |
| Idempotency-Key | string | Yes | Required header, up to 255 characters. Generate it once and resend the same one on every retry. |
Who it is for
Thank-you page conversion
Your SaaS creates a conversion with url_contains "/obrigado" so the customer can optimize ads for completed purchases.
Campaign onboarding at an agency
An agency creates the standard conversions for an e-commerce customer (purchase, lead), one idempotent call per conversion.
AI agent that prepares measurement
An agent lists the conversions, creates the missing one and uses its id in the new ad set.
Works with
Meta Ads
Frequently asked questions
Can I create the conversion from a pixel event?
The contract accepts rule.event, but the platform refuses that form on some pixels, and the refusal reaches you as ads_integration_error. The URL rule (rule.url_contains) is the one verified against a real account.
Do I have to provide the pixel?
Yes. pixel_id is required, because the platform refuses the creation without the pixel behind the rule. List pixels with GET /ads/facebook_ads/pixels.
Where do I use the conversion id?
In adset.facebook_ads.promoted_object.custom_conversion_id, on the ad set.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
