Conversions API

The Conversions API exports the latest stored conversion date for one tracked website and conversion path.

Endpoints

POST https://app.wheremore.com/api/v2/exports/conversions
GET  https://app.wheremore.com/api/v2/exports/{export_id}

POST is free. The first successful GET of a non-empty ready export costs 0.5 credits. Repeat GETs of the same immutable export are free. Exports expire after seven days.

Authentication and idempotency

Send X-API-Key: sk_live_...  or Authorization: Bearer sk_live_... .

Every POST requires Idempotency-Key . Retry the identical POST with the same key to receive the same export ID. Use a new key for a different scope or journey setting. Unknown JSON fields are rejected.

JSON fields

Create the export

curl -X POST "https://app.wheremore.com/api/v2/exports/conversions" \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Idempotency-Key: conversions-export-2026-08-25-001" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_your_workspace_id",
    "domain": "example.com",
    "path": "Newsletter Signup",
    "include_journey": true
  }'

HTTP 201 means the snapshot is ready. HTTP 202 means it is pending. POST never consumes credits.

Retrieve the export

curl "https://app.wheremore.com/api/v2/exports/exp_0123456789abcdef0123456789abcdef" \
  -H "X-API-Key: sk_live_your_key_here"

A pending GET returns HTTP 202 for free. A ready GET returns HTTP 200. The first non-empty retrieval reports billing_status: "deducted" ; later GETs return identical data with already_deducted , zero credits used and balance: null .

An optional callback contains only export-ready metadata, never conversion-session data.

Response

{
  "success": true,
  "export": {
    "id": "exp_0123456789abcdef0123456789abcdef",
    "type": "conversions",
    "status": "ready",
    "created_at": "2026-08-25T18:00:00Z",
    "ready_at": "2026-08-25T18:00:00Z",
    "expires_at": "2026-09-01T18:00:00Z",
    "status_url": "/api/v2/exports/exp_0123456789abcdef0123456789abcdef"
  },
  "credits_used": 0.5,
  "balance": 999.5,
  "billing_status": "deducted",
  "data": {
    "workspace_id": "ws_your_workspace_id",
    "domain": "example.com",
    "path": "Newsletter signup",
    "currency": "GBP",
    "date": "2026-07-26",
    "journey_requested": true,
    "journey_note": "Journey details are available only for cookie-linked full identities.",
    "sessions": [
      {
        "session_id": "example-session",
        "identity_status": "full",
        "journey_available": true,
        "conversion_timestamp": "2026-07-26T09:30:00Z",
        "revenue": 100,
        "is_new_customer": true,
        "conversion_device": "desktop",
        "sessions_to_conversion": 2,
        "days_to_conversion": 3,
        "touchpoint_count": 4,
        "first_touch": {
          "channel": "social",
          "source": "linkedin",
          "medium": "paid-social",
          "campaign": "summer_launch"
        },
        "last_touch": {
          "channel": "direct",
          "source": null,
          "medium": null,
          "campaign": null
        },
        "journey": [
          {
            "channel": "social",
            "source": "linkedin",
            "medium": "paid-social",
            "campaign": "summer_launch",
            "landing_page_url": "https://example.com/landing",
            "device": "desktop",
            "timestamp": "2026-07-23T12:00:00Z"
          }
        ]
      }
    ],
    "total_sessions": 1
  },
  "meta": {
    "request_id": "req_example",
    "api_version": "v2",
    "data_contract": "2026-08-25",
    "duration_ms": 13.19
  }
}

Fields can be null  where the underlying identity, UTM or referrer value was unavailable.

Identity and tracking mode

Full identity

identity_status: "full"  means Wheremore has a cookie-linked visitor identity. This can support:

• Joining eligible sessions over time.
• First-touch and last-touch attribution across those sessions.
• Sessions-to-conversion and days-to-conversion.
• A saved touchpoint journey when include_journey=true .

Session-only identity

identity_status: "session_only"  means the conversion is valid but Wheremore cannot safely join that session to other visits by the same person.

In this case:

• The conversion still counts.
• Revenue can still be reported.
• Session acquisition context can still be available.
• Cross-session journey fields can be unavailable.
• journey_available  is false when no eligible journey can be returned.

Cookieless tracking is intentionally session-scoped. It does not identify the same person across later sessions or devices.

Authenticated audience selection is separate from cookie identity. Selecting prospects or authenticated visitors does not create cross-session identity by itself.

Interpreting the fields

• date  is the latest conversion date included in the export.
• total_sessions  is the number of returned conversion sessions for that date.
• currency  comes from the selected path; Wheremore does not convert currencies.
• revenue  uses the configured path value and confirmed completion data.
• first_touch  and last_touch  are attribution views, not proof that a channel caused the conversion.
• Wheremore last-touch can include Direct.
• is_new_customer  depends on the identity and historical evidence available to the attribution pipeline.
• sessions_to_conversion  and days_to_conversion  require sufficient journey identity.
• journey  is returned only when requested and available.

Important limitations

• The endpoint exports the latest available conversion date, not an arbitrary reporting period.
• Only configured paths belonging to the selected website and workspace can be requested.
• Path steps and conversion zones must be correctly configured and tracking must be enabled.
• Conversion processing and attribution processing are asynchronous.
• Cookieless conversions are measured, but separate sessions cannot be reliably joined into a visitor journey.
• The same person cannot be assumed across devices without a shared persistent identity.
• Attribution explains how credit is assigned within the captured evidence; it does not prove causation.
• Revenue values from paths using different currencies should not be combined without external currency handling.
• Workspace access is checked again whenever the saved export is retrieved.

Errors

Troubleshooting

The path is not found

• Confirm the path belongs to the supplied domain.
• Confirm that domain belongs to the supplied workspace.
• Match the path name; matching is case-insensitive.
• Confirm the path has not been deleted.

No conversion data is available

• Confirm tracking is installed and enabled.
• Confirm the relevant pages are tracked.
• Confirm every path step has a working conversion zone.
• Confirm the path is active and within its schedule.
• Allow conversion and attribution processing to finish.

Journey data is missing

• Confirm include_journey: true  was included as a JSON boolean when the export was created. Retrieval uses only the resulting export ID.
• Check identity_status .
• Cookieless or session-only conversions cannot provide a cross-session visitor journey.
• A full identity can still have no journey if no eligible saved touchpoints exist.

Revenue is zero or missing

• Confirm the path’s value source and currency.
• Confirm the path-completion event was written.
• Zero-value paths intentionally report no revenue.

Campaign or channel values are missing

• Confirm UTM parameters were present on the captured entry.
• Confirm the Wheremore tracking script was active on the landing page.
• Direct and untagged visits can legitimately have empty UTM fields.
• Allow attribution-touch and model processing to complete.

A repeat retrieval

Repeat GET requests return the same saved sessions for free with billing_status: "already_deducted"  and balance: null .

Security

• Keep API keys in server-side secret storage.
• Never place a key in browser JavaScript or a URL.
• Revoke an exposed key immediately.
• Validate callback workspace, domain and path values before retrieval.
• Make callback handling idempotent because failed notifications are retried.
• Treat session IDs, landing pages and journey data as potentially sensitive behavioural data.
• Apply appropriate access controls and retention rules in the receiving system.