GeoSwap API

What the API can do

• Send conversions from a CRM, a backend or a no-code tool, one at a time or up to 500 per request.
• Link funnel stages (lead → qualified → signed) with parent_external_id, in any arrival order.
• Correct a conversion by sending it again with the same event and external_id.
• Tag conversions (site, market, business unit).
• Match conversions to visits with the visitor id or click id from your forms, or by hashed email, phone or address.
• Verify a key and read your project id and install snippet.

What the API can't do

• Read conversions or attribution reports back over the API.
• Delete a single conversion by id, or erase a person's data through the API: email support@geoswap.co and GeoSwap erases it for you.
• Manage links, redirects or other rules.
• Send conversions to ad platforms (Google, Meta) for you.
• Store raw email, phone or address: they're hashed on receipt.
• Authenticate with OAuth: API keys only.

Authentication

Create a key in Settings → API keys (workspace owners and admins). A key belongs to one workspace and carries scopes: workspace:read and/or conversions:write. Send it as Authorization: Bearer gs_live_…. Keys are shown once; revoke one at any time. API access works on every plan.

Endpoints

Paths below are relative to https://api.geoswap.co/v1.

Send a conversion

One stage of a journey: a lead, a qualified lead, a signed deal, a purchase. A first send answers 201 with result: "created"; sending the same event and external_id again answers 200 with updated or unchanged. Fields you leave out keep their stored value. An empty string or null in an optional field is ignored.

curl -X POST https://api.geoswap.co/v1/conversions \
  -H "Authorization: Bearer $GEOSWAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "qualified",
  "external_id": "006Hs00001AbCdE",
  "parent_external_id": "00QHs00002XyZqR",
  "occurred_at": "2026-10-12T14:03:00Z",
  "visitor_id": "Xb3k9_Qm2LpA7vR1.20261003",
  "email": "jane@example.com",
  "value": 1200,
  "currency": "USD",
  "tags": {
    "market": "co"
  }
}'

Email, phone and address are normalized and SHA-256 hashed the moment they arrive; GeoSwap never stores or logs them raw. An identifier that can't be read is dropped and named in warnings; the conversion is still saved.

external_id and parent_external_id also accept a JSON number (HubSpot's Record ID is one); it's stored as its decimal string, so the same id sent as 123 or "123" is the same conversion.

Send up to 500 at once

POST /conversions/batch with { "conversions": [ … ] }. A valid batch always answers 200 with one result per item, in order, plus a summary; each item succeeds or fails on its own. An invalid envelope (wrong shape, over 500 items, over the size limit) or an auth/rate-limit failure answers before any item is written, with its own status (400/401/403/413/422/429) instead.

A batch is written in chunks of 100. If a later chunk fails, earlier chunks may already be committed and the request returns 500 — re-send the whole batch. That's safe: GeoSwap matches on event + external_id, so already-written items are just updated again.

curl -X POST https://api.geoswap.co/v1/conversions/batch \
  -H "Authorization: Bearer $GEOSWAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conversions": [
    {
      "event": "qualified",
      "external_id": "006Hs00001AbCdE",
      "parent_external_id": "00QHs00002XyZqR",
      "occurred_at": "2026-10-12T14:03:00Z",
      "visitor_id": "Xb3k9_Qm2LpA7vR1.20261003",
      "email": "jane@example.com",
      "value": 1200,
      "currency": "USD",
      "tags": {
        "market": "co"
      }
    },
    {
      "event": "purchase",
      "external_id": "order-1001",
      "occurred_at": "2026-10-12T15:20:00Z",
      "visitor_id": "Pq7Lm2Xr9Ka0Zt3W",
      "value": 49.99,
      "currency": "USD",
      "tags": {
        "site": "diara",
        "market": "in"
      }
    }
  ]
}'

Stages and corrections

• Send each stage as its own conversion. parent_external_id points at the stage before it (e.g. the lead behind a deal); stages may arrive in any order.
• Stages that share an external_id under different events (the same CRM record moving through lifecycle stages) are linked automatically.
• A correction is a re-send: change occurred_at or value and GeoSwap marks it (and its journey, if it's the first stage) for re-attribution.
• Visitor id, click id, email, phone and address are how a conversion is matched to the visits before it. Send as many as you have.

Capture the visitor id

Add hidden inputs named gs_vid, gs_c and gs_r to your forms. geoswap.js fills them in (it never adds inputs), so the values land on the CRM record. Send them back as visitor_id, click_idand contact_id/gs_r. Forms inside cross-origin iframes (some HubSpot embeds) can't be filled; send the email instead.

Erase a person's data

There's no self-serve delete endpoint yet. Email support@geoswap.co with the visitor id, email, phone or contact id that identifies the person, and GeoSwap deletes their visit history (touches), erases the identifiers on their conversions, and removes them from attribution. Conversion counts stay; the person can't be identified from them. A deletion removes what is stored now: if your CRM sends the same conversion again later, it is stored as new data. Stop syncing a person who asked to be forgotten.

Errors

Every error is { "error": { "code", "message", "request_id" } }. code never changes meaning; request_id equals the X-Request-ID header. Quote it to support.

A 401 also carries a WWW-Authenticate header (RFC 6750); a 403 from insufficient_scope names the missing scope there too.

Rate limits

Per API key: 600 requests and 30,000 conversions per minute, in fixed one-minute windows (a batch counts each conversion). Over the limit you get 429 rate_limited with a Retry-After header. Wait the Retry-After seconds, then retry.

Versioning

/v1 only changes additively: new endpoints, new optional fields, new response fields, new error codes. Ignore fields you don't know. Breaking changes ship as /v2, with at least six months' notice before v1 stops.