Conversions

Report a conversion from your server

Reports one real conversion — a lead your own systems already accepted. The browser tracker (one <script> line, see https://serp-agent.com/docs/tracking) can only observe that a form was SENT; a form backend, CRM webhook or booking system knows whether the lead was accepted, which is what makes a server report trustworthy enough to count as a business outcome.

Attribution: the conversion is credited to one article, in this order — articleUrl (explicit), ctaTrackingId, pageUrl, then landingUrl (the page the visit started on, which is what usually names the article). The response says which one was used. A conversion that matches no article is still stored and counted for the project.

Idempotency: pass externalId — your own lead id. A repeat with the same id is ignored and answered 200 with duplicate: true, so retries and webhook redeliveries cannot inflate the numbers.

Never send personal data: no names, emails, phone numbers or message bodies. Only the event type, the pages involved and your own lead id.

post/v1/projects/{projectId}/conversions

Request

  • Base URL: https://serp-agent.com
  • URL: https://serp-agent.com/v1/projects/{projectId}/conversions
  • Auth: HTTP bearer

Path parameters

projectIdstring required

Project id.

Request body

eventType'FORM_SUBMIT' | 'CALENDAR_BOOKED' | 'PHONE_CLICK' | 'EMAIL_CLICK' | 'CTA_CLICK' required

What happened. FORM_SUBMIT and CALENDAR_BOOKED are the ones a server normally reports.

externalIdstring

Your own id for this lead. Makes the call idempotent — a repeat is ignored.

pageUrlstring uri

Page the conversion happened on.

landingUrlstring uri

Page the visit started on. Usually the article that earned the lead.

articleUrlstring uri

Explicit article URL when you already know which article to credit. Strongest evidence.

occurredAtstring date-time

When it happened (ISO 8601). Defaults to now; must not be more than 5 minutes in the future.

ctaTrackingIdstring

Value of the data-sa-cta attribute on the button, when your pages use one.

utm_sourcestring
utm_mediumstring
utm_campaignstring
utm_contentstring

Response

Already reported under this externalId — nothing was stored a second time.

recordedboolean required

True when this call stored a new conversion.

duplicateboolean required

True when the same externalId was already reported.

article_attributedboolean required

True when the conversion was credited to one of your articles.

attribution'explicit' | 'cta' | 'page' | 'landing' | 'none' required

Which signal credited the article: articleUrl (explicit), ctaTrackingId (cta), pageUrl (page), landingUrl (landing), or none.

Changes

No recorded changes to this operation across all 1 revision of this API.