# Leads

## Create or update a lead

`client.leads.createOrUpdate(LeadCreateOrUpdateParamsparams, RequestOptionsoptions?): LeadCreateOrUpdateResponse`

**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
1. If no `id` but phone/email provided, searches for existing lead by phone first, then email
1. 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.

### Parameters

- `params: LeadCreateOrUpdateParams`

  - `rotorAPIVersion: "1.1.0"`

    Header param: Required OpenAPI version header.

    - `"1.1.0"`

  - `id?: string`

    Body param: Optional — provide to update an existing lead

  - `address_city?: string`

    Body param

  - `address_country?: string`

    Body param

  - `address_state?: string`

    Body param

  - `address_street1?: string`

    Body param

  - `address_street2?: string`

    Body param

  - `address_zip?: string`

    Body param

  - `email?: string`

    Body param

  - `follow_up_date?: string`

    Body param

  - `name?: string`

    Body param

  - `notes?: string`

    Body param

  - `phone?: string`

    Body param

  - `priority?: "low" | "medium" | "high"`

    Body param

    - `"low"`

    - `"medium"`

    - `"high"`

  - `projected_value?: number`

    Body param

  - `service_type?: string`

    Body param

  - `source?: string`

    Body param

  - `stage?: string`

    Body param

  - `tags?: Array<string>`

    Body param

### Returns

- `LeadCreateOrUpdateResponse`

  - `id?: string`

  - `address_city?: string | null`

  - `address_country?: string | null`

  - `address_state?: string | null`

  - `address_street1?: string | null`

    Maps to property_street1

  - `address_street2?: string | null`

  - `address_zip?: string | null`

  - `archived?: boolean | null`

  - `archived_at?: string | null`

  - `assigned_to?: string | null`

  - `created_at?: string | null`

  - `email?: string | null`

  - `follow_up_date?: string | null`

  - `lead_source?: string | null`

  - `location?: Array<number> | null`

  - `message?: string`

  - `name?: string`

  - `notes?: string | null`

  - `phone?: string | null`

  - `priority?: "low" | "medium" | "high" | null`

    - `"low"`

    - `"medium"`

    - `"high"`

  - `projected_value?: number | null`

  - `property_city?: string | null`

  - `property_country?: string | null`

  - `property_state?: string | null`

  - `property_street1?: string | null`

  - `property_street2?: string | null`

  - `property_zip?: string | null`

  - `service_type?: string | null`

  - `source?: string | null`

  - `stage?: string | null`

  - `status?: string`

  - `tags?: Array<string>`

  - `value_score?: number | null`

### Example

```typescript
import Rotor from 'getrotor';

const client = new Rotor({
  rotorAPIVersion: '1.1.0',
  apiKey: process.env['ROTOR_API_KEY'], // This is the default and can be omitted
});

const response = await client.leads.createOrUpdate({ 'rotor-api-version': '1.1.0' });

console.log(response.id);
```

#### Response

```json
{
  "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
}
```

## List leads

`client.leads.list(LeadListParamsparams, RequestOptionsoptions?): LeadListResponse`

**get** `/leads`

Returns a paginated list of leads for the authenticated company.
Results are ordered by creation date (newest first).

### Parameters

- `params: LeadListParams`

  - `rotorAPIVersion: "1.1.0"`

    Header param: Required OpenAPI version header.

    - `"1.1.0"`

  - `archived?: boolean`

    Query param: Include archived leads (default false)

  - `limit?: number`

    Query param: Number of results per page (max 1000)

  - `page?: number`

    Query param: Page number (1-based)

  - `search?: string`

    Query param: Search by name, email, or phone

  - `stage?: string`

    Query param: Filter by pipeline stage

  - `tags?: string`

    Query param: Filter by tags (comma-separated). Returns leads that have any of the specified tags.

### Returns

- `LeadListResponse`

  - `data?: Array<Data>`

    - `id?: string`

    - `archived?: boolean | null`

    - `archived_at?: string | null`

    - `assigned_to?: string | null`

    - `created_at?: string | null`

    - `email?: string | null`

    - `follow_up_date?: string | null`

    - `lead_source?: string | null`

    - `location?: Array<number> | null`

    - `name?: string`

    - `notes?: string | null`

    - `phone?: string | null`

    - `priority?: "low" | "medium" | "high" | null`

      - `"low"`

      - `"medium"`

      - `"high"`

    - `projected_value?: number | null`

    - `property_city?: string | null`

    - `property_country?: string | null`

    - `property_state?: string | null`

    - `property_street1?: string | null`

    - `property_street2?: string | null`

    - `property_zip?: string | null`

    - `service_type?: string | null`

    - `stage?: string | null`

      Pipeline stage

    - `tags?: Array<string>`

    - `value_score?: number | null`

  - `pagination?: Pagination`

    - `has_more?: boolean`

      Whether more pages are available

    - `limit?: number`

    - `page?: number`

    - `total?: number`

      Total number of matching records

  - `status?: string`

### Example

```typescript
import Rotor from 'getrotor';

const client = new Rotor({
  rotorAPIVersion: '1.1.0',
  apiKey: process.env['ROTOR_API_KEY'], // This is the default and can be omitted
});

const leads = await client.leads.list({ 'rotor-api-version': '1.1.0' });

console.log(leads.data);
```

#### Response

```json
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "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
      ],
      "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",
      "stage": "stage",
      "tags": [
        "string"
      ],
      "value_score": 0
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}
```

## Get a lead by ID

`client.leads.retrieve(stringid, LeadRetrieveParamsparams, RequestOptionsoptions?): LeadRetrieveResponse`

**get** `/leads/{id}`

Get a lead by ID

### Parameters

- `id: string`

- `params: LeadRetrieveParams`

  - `rotorAPIVersion: "1.1.0"`

    Required OpenAPI version header.

    - `"1.1.0"`

### Returns

- `LeadRetrieveResponse`

  - `data?: Data`

    - `id?: string`

    - `archived?: boolean | null`

    - `archived_at?: string | null`

    - `assigned_to?: string | null`

    - `created_at?: string | null`

    - `email?: string | null`

    - `follow_up_date?: string | null`

    - `lead_source?: string | null`

    - `location?: Array<number> | null`

    - `name?: string`

    - `notes?: string | null`

    - `phone?: string | null`

    - `priority?: "low" | "medium" | "high" | null`

      - `"low"`

      - `"medium"`

      - `"high"`

    - `projected_value?: number | null`

    - `property_city?: string | null`

    - `property_country?: string | null`

    - `property_state?: string | null`

    - `property_street1?: string | null`

    - `property_street2?: string | null`

    - `property_zip?: string | null`

    - `service_type?: string | null`

    - `stage?: string | null`

      Pipeline stage

    - `tags?: Array<string>`

    - `value_score?: number | null`

  - `status?: string`

### Example

```typescript
import Rotor from 'getrotor';

const client = new Rotor({
  rotorAPIVersion: '1.1.0',
  apiKey: process.env['ROTOR_API_KEY'], // This is the default and can be omitted
});

const lead = await client.leads.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
  'rotor-api-version': '1.1.0',
});

console.log(lead.data);
```

#### Response

```json
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "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
    ],
    "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",
    "stage": "stage",
    "tags": [
      "string"
    ],
    "value_score": 0
  },
  "status": "success"
}
```