Skip to content
Rotor API Logo Rotor API
Get started
API Reference
Leads

Create or update a lead

POST/leads

Creates a new lead or updates an existing one based on the provided information.

Upsert Logic:

  1. If id is provided, updates the lead with that ID
  2. If no id but phone/email provided, searches for existing lead by phone first, then email
  3. If no existing lead found, creates a new lead

Response Status:

  • 201 Created for new leads
  • 200 OK for updated leads

Tags are merged (not replaced) when updating.

Header ParametersExpand Collapse
"rotor-api-version": "1.1.0"
Body ParametersJSONExpand Collapse
id: optional string

Optional — provide to update an existing lead

formatuuid
address_city: optional string
address_country: optional string
address_state: optional string
address_street1: optional string
address_street2: optional string
address_zip: optional string
email: optional string
follow_up_date: optional string
name: optional string
notes: optional string
phone: optional string
priority: optional "low" or "medium" or "high"
One of the following:
"low"
"medium"
"high"
projected_value: optional number
service_type: optional string
source: optional string
stage: optional string
tags: optional array of string
ReturnsExpand Collapse
id: optional string
address_city: optional string
address_country: optional string
address_state: optional string
address_street1: optional string

Maps to property_street1

address_street2: optional string
address_zip: optional string
archived: optional boolean
archived_at: optional string
assigned_to: optional string
created_at: optional string
email: optional string
follow_up_date: optional string
lead_source: optional string
location: optional array of number
message: optional string
name: optional string
notes: optional string
phone: optional string
priority: optional "low" or "medium" or "high"
One of the following:
"low"
"medium"
"high"
projected_value: optional number
property_city: optional string
property_country: optional string
property_state: optional string
property_street1: optional string
property_street2: optional string
property_zip: optional string
service_type: optional string
source: optional string
stage: optional string
status: optional string
tags: optional array of string
value_score: optional number

Create or update a lead

curl https://api.getrotor.com/open-api/leads \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $ROTOR_API_KEY" \
    -d '{}'
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "address_city": "address_city",
  "address_country": "address_country",
  "address_state": "address_state",
  "address_street1": "address_street1",
  "address_street2": "address_street2",
  "address_zip": "address_zip",
  "archived": true,
  "archived_at": "2019-12-27T18:11:19.117Z",
  "assigned_to": "assigned_to",
  "created_at": "2019-12-27T18:11:19.117Z",
  "email": "dev@stainless.com",
  "follow_up_date": "2019-12-27T18:11:19.117Z",
  "lead_source": "lead_source",
  "location": [
    0
  ],
  "message": "Lead created successfully",
  "name": "name",
  "notes": "notes",
  "phone": "phone",
  "priority": "low",
  "projected_value": 0,
  "property_city": "property_city",
  "property_country": "property_country",
  "property_state": "property_state",
  "property_street1": "property_street1",
  "property_street2": "property_street2",
  "property_zip": "property_zip",
  "service_type": "service_type",
  "source": "source",
  "stage": "stage",
  "status": "success",
  "tags": [
    "string"
  ],
  "value_score": 0
}
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}
{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}
{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}
{
  "status": "error",
  "message": "Internal server error"
}
Returns Examples
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "address_city": "address_city",
  "address_country": "address_country",
  "address_state": "address_state",
  "address_street1": "address_street1",
  "address_street2": "address_street2",
  "address_zip": "address_zip",
  "archived": true,
  "archived_at": "2019-12-27T18:11:19.117Z",
  "assigned_to": "assigned_to",
  "created_at": "2019-12-27T18:11:19.117Z",
  "email": "dev@stainless.com",
  "follow_up_date": "2019-12-27T18:11:19.117Z",
  "lead_source": "lead_source",
  "location": [
    0
  ],
  "message": "Lead created successfully",
  "name": "name",
  "notes": "notes",
  "phone": "phone",
  "priority": "low",
  "projected_value": 0,
  "property_city": "property_city",
  "property_country": "property_country",
  "property_state": "property_state",
  "property_street1": "property_street1",
  "property_street2": "property_street2",
  "property_zip": "property_zip",
  "service_type": "service_type",
  "source": "source",
  "stage": "stage",
  "status": "success",
  "tags": [
    "string"
  ],
  "value_score": 0
}
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}
{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}
{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}
{
  "status": "error",
  "message": "Internal server error"
}