Conversion Goals API

What it does

Conversion Goals let you record customer actions — purchases, signups, demo requests, qualified leads — so they appear in Velaro reports and so AI workflows can react to them. Posting to the Conversions API attributes the event to the visitor's chat session, rolls it up in revenue and conversion-rate reports, and can trigger follow-up workflows (e.g. send a thank-you message, tag the contact, hand off to an account manager).

Use this when an event happens outside the Velaro chat widget — on your server, in your checkout flow, or in a third-party system that fires a webhook.

Get your API key

Conversion events must be authenticated with a Velaro API key. Generate one in the Velaro admin console under Settings → MCP Keys.

1. Open Settings → MCP Keys
2. Click New key and give it a label that identifies the system using it (e.g. "Shopify webhook", "Marketing site server")
3. Copy the vel_live_* value — it is shown once and cannot be retrieved later
4. Store it as an environment variable or secret in the system that will call the API

Create a separate key per integration. If a key leaks or an integration is decommissioned, you can revoke that single key without affecting the others.

The key is bound to the site where it was created. It can only record conversions for that site.

curl example

This is the exact pattern shown in Settings → Conversions → Server-side / webhook.

curl -X POST https://api-admin-us-east.velaro.com/Conversions/record \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vel_live_YOUR_KEY_HERE" \
  -d '{
    "goalId": 123,
    "visitorId": "optional-session-id",
    "amount": 99.00,
    "integrationOrderId": "ORDER-123",
    "integrationSource": "custom"
  }'

A successful call returns HTTP 200 with the recorded conversion ID.

Node.js / fetch example

await fetch("https://api-admin-us-east.velaro.com/Conversions/record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer vel_live_YOUR_KEY_HERE"
  },
  body: JSON.stringify({
    goalId: 123,
    visitorId: "optional-session-id",
    amount: 99.00,
    integrationOrderId: "ORDER-123",
    integrationSource: "custom"
  })
});

The same pattern works from any server-side language — Python requests, Go net/http, PHP curl, .NET HttpClient. The only requirement is the Authorization: Bearer vel_live_* header.

What gets recorded

Duplicate events: if you post the same goalId + integrationOrderId twice, the second post is ignored. This makes it safe to retry on network failures. If integrationOrderId is omitted, duplicates are not detected and each post records a new conversion.

Errors and what they mean

Why the body siteId is ignored when an API key is provided

The API key is bound to one site, so the server uses that site and ignores any siteId field you send in the body — this prevents a leaked key from being used to record events against other sites.

Rotating or revoking a key

Go to Settings → MCP Keys. Each row has actions to:

• Revoke — immediately stops the key from working. Calls using it return 401 from the moment you click revoke.
• Rotate — creates a replacement key with the same label and revokes the old one. The new vel_live_* value is shown once. Update the consuming system before the old key is revoked to avoid downtime.

Because each integration has its own key, revoking one never breaks the others.

Troubleshooting

"My calls return 401 even though the key looks right." Check the key prefix — only vel_live_ keys work against the production API. vel_test_ keys are for the staging environment and will be rejected by production, and vice versa.

"I copied the key from the admin console and it doesn't work." A trailing space or newline from the clipboard is the most common cause. Paste the key into a plain-text editor first, confirm it starts with vel_live_ and has no whitespace before or after, then copy it again.

"It worked yesterday, now it returns 401." Someone may have revoked the key. Open Settings → MCP Keys and confirm the key is still listed and active. If not, generate a new one and update the consuming system.

"I'm getting 403 even with a valid key." The key is for a different site than the goal. Keys are site-scoped — a key created on Site A cannot record conversions on Site B. Generate a new key from the site that owns the goal.

Related

• Integrations overview
• Workflows and AI