Sign in
Ad Accounts

Create 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

Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...).

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.

Changes

Changed in 5 of the 56 revisions of this API.17

  • 2c04683ce6948See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 3e6ddf2a99ea2See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 0dba7d004d754See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • e70ed06e71502See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

  • 1e9a379eafca1See the full diff
    • ○

      endpoint added

      endpoint-added