Leads

Create or update a lead

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

POST

/leads

curl --request POST \
  --url https://api.getrotor.com/open-api/leads \
  --header 'x-api-key: <api-key>' \
  --header 'rotor-api-version: 1.1.0' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address_city": "<string>",
  "address_country": "<string>",
  "address_state": "<string>",
  "address_street1": "<string>",
  "address_street2": "<string>",
  "address_zip": "<string>",
  "email": "jsmith@example.com",
  "follow_up_date": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "notes": "<string>",
  "phone": "<string>",
  "priority": "low",
  "projected_value": 123,
  "service_type": "<string>",
  "source": "<string>",
  "stage": "<string>",
  "tags": [
    "<string>"
  ]
}
'

{
  "address_city": "<string>",
  "address_country": "<string>",
  "address_state": "<string>",
  "address_street1": "<string>",
  "address_street2": "<string>",
  "address_zip": "<string>",
  "archived": true,
  "archived_at": "2023-11-07T05:31:56Z",
  "assigned_to": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "email": "jsmith@example.com",
  "follow_up_date": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lead_source": "<string>",
  "location": [
    123
  ],
  "message": "Lead created successfully",
  "name": "<string>",
  "notes": "<string>",
  "phone": "<string>",
  "priority": "low",
  "projected_value": 123,
  "property_city": "<string>",
  "property_country": "<string>",
  "property_state": "<string>",
  "property_street1": "<string>",
  "property_street2": "<string>",
  "property_zip": "<string>",
  "service_type": "<string>",
  "source": "<string>",
  "stage": "<string>",
  "status": "success",
  "tags": [
    "<string>"
  ],
  "value_score": 123
}

Upsert Logic:

If id is provided, updates the lead with that ID
If no id but phone/email provided, searches for existing lead by phone first, then email
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.

Authorizations

x-api-keystringheaderrequired

Company API key in the format: rotor_{keyId}_{keySecret}

To obtain an API key:

Log into your Rotor dashboard
Go to Settings → Integrations → API Keys
Create a new key and select the scopes you need
Copy the key — it's only shown once!

Headers

rotor-api-versionenum<string>headerdefault:1.1.0required

Required OpenAPI version header.

Available options: 1.1.0

Example: 1.1.0

Body

address_citystring

Maximum string length: 100

address_countrystring

Maximum string length: 100

address_statestring

Maximum string length: 100

address_street1string

Maximum string length: 255

address_street2string

Maximum string length: 255

address_zipstring

Maximum string length: 20

emailstring

Maximum string length: 255

follow_up_datestring

idstring

Optional — provide to update an existing lead

namestring

Maximum string length: 255

notesstring

Maximum string length: 2000

phonestring

priorityenum<string>

Available options: low, medium, high

projected_valuenumber

Required range: 0 <= x <= 10000000

service_typestring

Maximum string length: 100

sourcestring

Maximum string length: 100

stagestring

Maximum string length: 100

tagsstring[]

Maximum array length: 20

Response

Lead updated successfully

address_citystring | null

address_countrystring | null

address_statestring | null

address_street1string | null

Maps to property_street1

address_street2string | null

address_zipstring | null

archivedboolean | null

archived_atstring | null

assigned_tostring | null

created_atstring | null

emailstring | null

follow_up_datestring | null

idstring

lead_sourcestring | null

locationnumber[] | null

messagestring

Example: Lead created successfully

namestring

notesstring | null

phonestring | null

priorityenum<string> | null

Available options: low, medium, high

projected_valuenumber | null

property_citystring | null

property_countrystring | null

property_statestring | null

property_street1string | null

property_street2string | null

property_zipstring | null

service_typestring | null

sourcestring | null

stagestring | null

Pipeline stage

statusstring

Example: success

tagsstring[]

value_scorenumber | nulldeprecated

Still need help? Ask the team