---
title: "Record Conversion"
method: POST
path: "/api/sdk/v1/conversion"
tags: ["SDK"]
---

# Record Conversion

`POST /api/sdk/v1/conversion`

## Request

- Base URL: `https://geo.sig.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://geo.sig.ai/api/sdk/v1/conversion`
- Auth: none declared

Record a conversion for an attributed session.

Updates the attribution session with conversion details, enabling revenue
tracking back to the original AI query. This is the key endpoint for
proving ROI: "Which ChatGPT query generated $499 in revenue?"

**Use Case:**
When a user completes a purchase, upgrade, or other conversion event,
call this endpoint with the session_id and conversion value.

**Example:**
```javascript
// User completes checkout
const sessionId = AIVisibility.getSessionId();
await fetch('/api/v1/sdk/conversion', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_key' },
  body: JSON.stringify({
    session_id: sessionId,
    value: 499.00,
    currency: 'USD',
    metadata: { plan: 'pro', interval: 'monthly' }
  })
});
```

**Request Body:**
- session_id: SDK session identifier (same as used in /attribution/link)
- value: Conversion value (e.g., 499.00 for $499)
- currency: ISO currency code (default: USD)
- metadata: Optional conversion details (plan, customer_email, etc.)

**Response:**
Returns conversion details including query_id (if attributed) and ai_source.
If session wasn't attributed to an AI query, query_id will be null.

**Note:**
If the session doesn't exist in attribution_sessions, the conversion
is still recorded but won't be attributed to a specific AI query.

## Headers

- `X-API-Key` string

## Request body

- ConversionRecordRequest: Request to record a conversion for an attributed session.
  - `session_id` string, required: SDK session identifier
  - `value` number, required: Conversion value (e.g., 499.00)
  - `currency` string: ISO currency code
  - `metadata` object, nullable: Additional conversion details

## Response `200`

Successful Response

- ConversionRecordResponse: Response after recording a conversion.
  - `session_id` string, required
  - `converted` boolean, required
  - `conversion_value` number, required
  - `currency` string, required
  - `conversion_at` string, date-time, required
  - `query_id` string, nullable, required
  - `ai_source` string, nullable, required
  - `conversion_metadata` object, nullable, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api.md) · [All operations](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/revisions/3ec39f9be9e0?raw)