Sign in
OpenAPI 3.1.02026-08-185681822.2 MB

d0ab3b4eb0ae

Ad Accounts

Create or reuse a custom conversion

Provision the Meta custom conversion an ads flow optimises toward, and hand back the customConversionId for promotedObject.customConversionId on POST /v1/ads/create. Removes the manual "create it in Ads Manager first" step.

Reuse is ours, not Meta's. Meta's create is not idempotent, so a retried request would otherwise mint a duplicate carrying none of the original's optimisation history. A non-archived conversion with the same name on the same pixelId is returned instead of created, with reused: true and a 200 rather than a 201.

rule is forwarded verbatim in Meta's own grammar (e.g. {"url": {"i_contains": "thank-you"}}); Meta validates it and rejects a malformed one with "A conversion rule is required at creation time".

post/v1/accounts/{accountId}/custom-conversions

Path parameters

accountIdstring required

Meta ads SocialAccount id.

Request body

adAccountIdstring required

Meta ad account id (act_<n>).

namestring required

Also the reuse key, together with pixelId.

pixelIdstring required

Meta pixel id (event_source_id). From GET /v1/accounts/{accountId}/tracking-tags.

customEventTypestring required

Meta custom_event_type, e.g. LEAD, PURCHASE, OTHER.

ruleobject required

Meta conversion rule, forwarded verbatim.

Response

An existing custom conversion was reused

adAccountIdstring
customConversionIdstring

Drops straight into promotedObject.customConversionId on POST /v1/ads/create.

reusedboolean

True when an existing conversion matched name + pixelId; the response is then a 200.