Create Conversion Event

POST /conversions

Record a conversion event for a lead. Conversions track business outcomes such as reservations (intermediary) or closed sales (final).

The workflow_id, master_workflow_id, and currency are automatically inherited from the conversion type, and converted_at defaults to the current time. You only need to provide conversion_type_id, lead_id, and amount.

Each conversion type can define custom fields (see List Conversion Types). When creating an event, pass the corresponding values in the metadata object using the field key as the JSON key.

Request Body

Field	Type	Required	Description
conversion_type_id	string (uuid)	Yes	Conversion type ID. Use GET /conversion-types to list available types
lead_id	string (uuid)	Yes	Lead ID that converted
amount	number	Yes	Monetary value of the conversion
workflow_run_id	string (uuid)	No	Optional workflow run ID for granular attribution
currency	string (3 chars)	No	ISO 4217 currency code. Inherited from conversion type if not provided
converted_at	string (date-time)	No	When the conversion occurred. Defaults to current time
metadata	object	No	Custom field values. Keys should match the conversion type's field definitions
notes	string	No	Free-text notes about this conversion event

Examples

Minimal — only required fields

converted_at defaults to now.

curl -X POST https://api.getnexor.ai/api/public/conversions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "conversion_type_id": "123e4567-e89b-12d3-a456-426614174100",
    "lead_id": "123e4567-e89b-12d3-a456-426614174200",
    "amount": 85000.00
  }'

With custom field metadata

curl -X POST https://api.getnexor.ai/api/public/conversions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "conversion_type_id": "123e4567-e89b-12d3-a456-426614174100",
    "lead_id": "123e4567-e89b-12d3-a456-426614174200",
    "amount": 5000.00,
    "converted_at": "2026-01-28T10:00:00Z",
    "metadata": {
      "property_unit": "Apt 302",
      "broker": "John Smith"
    },
    "notes": "Client paid in cash, expedited closing."
  }'

With workflow run override

curl -X POST https://api.getnexor.ai/api/public/conversions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "conversion_type_id": "123e4567-e89b-12d3-a456-426614174100",
    "lead_id": "123e4567-e89b-12d3-a456-426614174200",
    "workflow_run_id": "123e4567-e89b-12d3-a456-426614174400",
    "amount": 50000.00,
    "converted_at": "2026-02-10T12:00:00Z",
    "metadata": {
      "property_unit": "Unit 15B",
      "commission": 2500
    }
  }'

Responses

201 — Conversion event created successfully

{
  "success": true,
  "conversion_event": {
    "id": "uuid",
    "conversion_type_id": "uuid",
    "lead_id": "uuid",
    "workflow_id": "uuid",
    "master_workflow_id": null,
    "workflow_run_id": null,
    "amount": 85000.00,
    "currency": "USD",
    "metadata": {
      "property_unit": "Apt 302",
      "broker": "John Smith"
    },
    "notes": null,
    "converted_at": "2026-02-01T15:30:00Z",
    "created_at": "2026-02-01T15:30:00Z"
  }
}

400 — Validation error

Possible error messages:

• "conversion_type_id, lead_id, and amount are required"
• "currency must be a 3-character ISO 4217 code (e.g., \"USD\", \"CLP\")"
• "conversion_type_id not found, inactive, or does not belong to your account"
• "lead_id not found or does not belong to your account"
• "workflow_run_id not found or does not match the given workflow_id and lead_id"

401 — Authentication error

See Authentication.

500 — Internal server error