Store/Update Conversion (Web)

This API request stores web conversion data such as a form, for a specific site using the HTTP method PUT. The request includes the following parameters:

Headers:

AuthorizationstringRequired

The authorization token for accessing the API. The header value should be set to "Bearer {your-access-token}", where {your-access-token} is the access token assigned to the user.

Request Body(JSON payload):

The data containing the conversion information to store/update. The payload should include the following parameters:

CaptureDateTimestringRequired

The date and time the conversion was captured, as an ISO 8601 date-time in UTC: yyyy-MM-ddTHH:mm:ss, for example 2026-09-21T14:05:00.

Send the time the form was submitted on the website, not the time you send this request. Spot matching looks for the browsing session in the two minutes before this time, so a delayed or rounded time will stop a form being matched.

VisitorIdentifierOptionsArrayRequired

An array of visitor identifiers. Each item in the array should include the following parameters:

KeystringRequired

The key for the visitor identifier. Accepted Keys: EmailAddress, PhoneNumber, RaId, CookieValue

ValuestringRequired

The value for the visitor identifier.

If using the CookieValue identifier you must pass the Google Client ID without the GA.1.1 prefix. e.g. GA1.1.101961087.1756204614 should be sent as 101961087.1756204614

PayloadArrayRequired

An array of payload. Each item in the array should include the following parameters:

KeystringRequired

The key for the payload item.

ValuestringRequired

The value for the payload item.

LandingPageUrlOverridestring

The Landing Page Url you would like to set for this form. If you do not set a MarketingChannelOverride then this URL will be used for attribution alongside the referrer URL.

Ensure this is a well formatted URL. e.g.https://www.ruleranalytics.com/

ReferrerUrlOverridestring

The referrer Url you would like to set for this form. If you do not set a MarketingChannelOverride then this URL will be used for attribution alongside the Landing page URL.

Ensure this is a well formatted URL. e.g.https://www.ruleranalytics.com/

MarketingChannelOverridestring

The Marketing Channel Override you would like to provide: See table below for reference values.

SourceCategoryOverridestring

The Source Category Override you would like to provide: See table below for reference values.

SpotMatchboolean

Whether Ruler may spot match this form. Defaults to true when omitted. Send false to opt a single form out.

Spot matching only acts when the form carries no RaId, the site has spot match settings configured in the Ruler app, and Ruler does not already know the person by email or phone. It looks for a browsing session on one of the site's configured form pages in the two minutes before CaptureDateTime. One clear session joins the form onto that journey with the source Journey; no session, or too many, gives the form the source No Spot Match. A form that matches a conversion Ruler already has is skipped as a duplicate.

Source	Marketing Channels
UnMatched	NotApplicable
Direct	NotApplicable
Offline	NotApplicable
Referral	NotApplicable
Email	NotApplicable
SMS	NotApplicable
Google	Paid, Organic, Places
Yahoo	Paid, Organic
Bing	Paid, Organic
Facebook	Paid, Organic
Twitter	Paid, Organic
LinkedIn	Paid, Organic
Pinterest	Paid, Organic
Instagram	Paid, Organic
YouTube	Paid, Organic
TikTok	Paid, Organic
Reddit	Paid, Organic
Snapchat	Paid, Organic
AdRoll	Paid, Organic
DuckDuckGo	Paid, Organic
Outbrain	Paid
StackAdapt	Paid
Awin	Paid
Klaviyo	Paid
Criteo	Paid
Impact	Paid
ShareASale	Paid
Taboola	Paid
TheTradeDesk	Paid
ChatGPT	Organic
Yelp	Paid
Journey	NotApplicable	Joins the form onto an existing touchpoint if one is found to match. Other sources create a new touchpoint. Spot matching sets this source automatically when a form is matched to a session.
No Spot Match	NotApplicable	System-assigned. Spot matching sets this source when a form could not be matched to a session. Do not send it as an override.
Custom Source	Custom	Use this method when you want to upload to one of your custom sources. Replace Custom Source with the name of your source

The {your-access-token} parameter in the authorization header should be replaced with the appropriate access token.

Request

PUT

{siteId}/conversion/web/upload

curl -X PUT \
  'https://rest.rulerapi.com/v1/{siteId}/conversion/web/upload' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: application/json' \
  -d {
    "CaptureDateTime": "{captureDateTime}",
    "VisitorIdentifierOptions": [{
        "Key": "{key}",
        "Value": "{value}"
    }],
    "Payload": [{
        "key": "{key}",
        "value": "{value}"
    }],
    "MarketingChannelOverride" : "{marketingChannelOverride}",
    "SourceCategoryOverride": "{sourceCategoryOverride}",
    "LandingPageUrlOverride": "{landingPageUrlOverride}",
    "ReferrerUrlOverride": "{referrerUrlOverride}",
    "SpotMatch": true
}

Response

Status: 202

API Thresholds

maxRequestsPerSecond: 1000 maxConcurrentRequests: 1000