Send CRM conversions to GeoSwap

Salesforce Flow

Needs: Salesforce Enterprise edition or above (HTTP Callout in Flow), and an admin.

Not yet verified end to end; tell support@geoswap.co if a step differs.

1. Setup → Named Credentials → External Credentials → New: label GeoSwap, protocol Custom. Add a principal with a parameter ApiKey = your gs_live_… key, and a custom header Authorization = {!'Bearer ' & $Credential.GeoSwap.ApiKey}.
2. Named Credentials → New: label GeoSwap, URL https://geoswap.co, external credential GeoSwap, Generate Authorization Header off, Allow Formulas in HTTP Header on.
3. Give the flow's running user access to the external credential principal (permission set → External Credential Principal Access).
4. New Record-Triggered Flow on Lead or Opportunity, "A record is updated", condition: the stage field is changed. One flow (or decision branch) per stage you want to send.
5. Add a formula resource OccurredAtIso (Text): SUBSTITUTE(TEXT({!$Flow.CurrentDateTime}), " ", "T") — Salesforce writes date-times in GMT with a trailing Z.
6. Add an Action → Create HTTP Callout: named credential GeoSwap, method POST, URL path /api/v1/conversions, and paste the sample body below so Salesforce generates the request type. Map the fields as shown.
7. For an Opportunity, set parent_external_id to the Lead Id it was converted from (store it in a custom field such as GeoSwap_Lead_Id__c at conversion). Without one, each stage still counts; it just isn't linked to the lead.
8. Text fields that are blank render as ""; GeoSwap ignores empty optional fields, so a lead without a visitor id or amount still counts. Keep value in quotes (as below) so a blank Amount stays valid JSON.
9. Activate, move a test record through a stage, and check the callout result: 201 (or 200 on a re-send).

{
  "event": "qualified",
  "external_id": "{!$Record.Id}",
  "parent_external_id": "{!$Record.GeoSwap_Lead_Id__c}",
  "occurred_at": "{!OccurredAtIso}",
  "visitor_id": "{!$Record.GS_Visitor_Id__c}",
  "value": "{!$Record.Amount}",
  "currency": "USD"
}

HubSpot workflow

Needs: HubSpot Data Hub (formerly Operations Hub) Professional or Enterprise for the "Send a webhook" action.

Not yet verified end to end; tell support@geoswap.co if a step differs.

1. Create a contact-based workflow, enrolled when Lifecycle stage becomes the stage you want (e.g. Marketing Qualified Lead). Use one workflow per stage.
2. Add the action Send a webhook: method POST, URL https://geoswap.co/api/v1/conversions.
3. Authentication type API key: key name Authorization, value Bearer gs_live_… (the bare key also works), location Request header.
4. Turn on Customize request body and add: static event = qualified; external_id = Record ID; occurred_at = Became a Marketing Qualified Lead date (HubSpot sends epoch milliseconds, which GeoSwap accepts); email = Email; visitor_id = the contact property your form saves gs_vid into.
5. HubSpot's Record ID (hs_object_id) is a number; GeoSwap accepts external_id as either a JSON number or a string, so send it either way.
6. All stages of one contact share the same external_id (the Record ID), so GeoSwap links them into one journey automatically.
7. Test the action with a sample contact: HubSpot shows the response; expect 201.

Zapier

Needs: a Zapier plan that includes Webhooks by Zapier (paid plans).

Not yet verified end to end; tell support@geoswap.co if a step differs.

1. Trigger: your CRM's "deal stage changed" or "new lead" event (Pipedrive, HubSpot, Salesforce, a form tool…).
2. Action: Webhooks by Zapier → POST. URL https://geoswap.co/api/v1/conversions, payload type json.
3. Data: event (type the stage name), external_id (the record id), occurred_at (the trigger's date; add a Formatter step to ISO 8601 if it has no time zone), plus email, value, visitor_id if you have them.
4. Headers: Authorization = Bearer gs_live_….
5. Test the step; expect a 201 with result: "created".

From your server

Any language that can make an HTTPS POST. Batch up to 500 per request with /api/v1/conversions/batch.

1. Store the key in a secret (GEOSWAP_API_KEY); never ship it to a browser.
2. Send each stage when it happens, with the visitor id from the gs_vid cookie or hidden field, and tags for things like site and market.
3. Retry on 429 (after Retry-After) and 5xx; re-sending the same event + external_id is safe.

// Node 18+ (fetch built in). Send each stage when it happens.
const res = await fetch("https://geoswap.co/api/v1/conversions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GEOSWAP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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"
    }
  }),
});
if (res.status === 429) {
  // Rate limited: wait Retry-After seconds, then retry.
} else if (!res.ok) {
  const { error } = await res.json(); // { code, message, request_id }
  console.error(error.code, error.request_id);
}