> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Lead

> Create a new lead record in the CRM pipeline

<Note>
  Creates a lead that can be tracked, engaged, and converted into a customer or account.
</Note>

## Request Body

<ParamField body="firstName" type="string" required>
  First name of the lead.

  **Example:** `Sarah`
</ParamField>

<ParamField body="lastName" type="string" required>
  Last name of the lead.

  **Example:** `Johnson`
</ParamField>

<ParamField body="email" type="string" required>
  Email address of the lead. Must be unique.

  **Example:** `sarah.johnson@company.com`
</ParamField>

<ParamField body="phone" type="string">
  Phone number of the lead.

  **Example:** `+1-555-234-5678`
</ParamField>

<ParamField body="title" type="string">
  Job title or position.

  **Example:** `VP of Operations`
</ParamField>

<ParamField body="department" type="string">
  Department or division.

  **Example:** `Operations`
</ParamField>

<ParamField body="leadSource" type="string">
  Source or origin of the lead.

  **Options:** `website`, `referral`, `trade_show`, `cold_call`, `social_media`, `partner`, `other`
</ParamField>

<ParamField body="description" type="string">
  Additional details or notes about the lead.
</ParamField>

<ParamField body="mailingStreet" type="string">
  Street address.
</ParamField>

<ParamField body="mailingCity" type="string">
  City.
</ParamField>

<ParamField body="mailingState" type="string">
  State or province.
</ParamField>

<ParamField body="mailingCountry" type="string">
  Country.
</ParamField>

<ParamField body="do_not_call" type="boolean" default="false">
  Whether the lead should not be contacted by phone.
</ParamField>

<ParamField body="email_opt_out" type="boolean" default="false">
  Whether the lead has opted out of email communication.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the created lead.
</ResponseField>

<ResponseField name="object" type="string">
  Object type. Always `lead`.
</ResponseField>

<ResponseField name="firstName" type="string">
  First name of the lead.
</ResponseField>

<ResponseField name="lastName" type="string">
  Last name of the lead.
</ResponseField>

<ResponseField name="email" type="string">
  Email address of the lead.
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number of the lead.
</ResponseField>

<ResponseField name="title" type="string">
  Job title of the lead.
</ResponseField>

<ResponseField name="leadSource" type="string">
  Source of the lead.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the lead. Starts as `new`.
</ResponseField>

<ResponseField name="created_at" type="datetime">
  ISO 8601 timestamp when the lead was created.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/leads' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
      "firstName": "Sarah",
      "lastName": "Johnson",
      "email": "sarah.johnson@company.com",
      "phone": "+1-555-234-5678",
      "title": "VP of Operations",
      "department": "Operations",
      "leadSource": "website",
      "description": "Interested in returns automation"
  }'
  ```

  ```graphql GraphQL theme={null}
  mutation createLead($input: LeadInput!) {
    insert_leads_one(object: $input) {
      id
      firstName
      lastName
      email
      phone
      title
      leadSource
      status
      created_at
    }
  }
  ```

  ```javascript Node.js theme={null}
  const lead = await stateset.leads.create({
    firstName: 'Sarah',
    lastName: 'Johnson',
    email: 'sarah.johnson@company.com',
    phone: '+1-555-234-5678',
    title: 'VP of Operations',
    leadSource: 'website',
  });
  ```

  ```python Python theme={null}
  lead = stateset.leads.create(
    first_name='Sarah',
    last_name='Johnson',
    email='sarah.johnson@company.com',
    phone='+1-555-234-5678',
    title='VP of Operations',
    lead_source='website',
  )
  ```

  ```ruby Ruby theme={null}
  lead = Stateset::Lead.create(
    firstName: 'Sarah',
    lastName: 'Johnson',
    email: 'sarah.johnson@company.com',
    phone: '+1-555-234-5678',
    title: 'VP of Operations',
    leadSource: 'website',
  )
  ```

  ```go Go theme={null}
  lead, err := stateset.Leads.Create(&LeadCreateParams{
    FirstName:  "Sarah",
    LastName:   "Johnson",
    Email:      "sarah.johnson@company.com",
    Phone:      "+1-555-234-5678",
    Title:      "VP of Operations",
    LeadSource: "website",
  })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "e0901f08-3aa1-43c5-af5c-0a9d2fc64e30",
    "object": "lead",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "email": "sarah.johnson@company.com",
    "phone": "+1-555-234-5678",
    "title": "VP of Operations",
    "department": "Operations",
    "leadSource": "website",
    "status": "new",
    "description": "Interested in returns automation",
    "created_at": "2024-06-15T10:30:00.000Z"
  }
  ```

  ```json Error Response (409 Conflict) theme={null}
  {
    "error": {
      "code": "DUPLICATE_RESOURCE",
      "message": "A lead with this email already exists",
      "details": {
        "field": "email",
        "value": "sarah.johnson@company.com"
      },
      "request_id": "req_abc123def456"
    }
  }
  ```

  ```json Error Response (422 Validation Error) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Required fields are missing",
      "details": {
        "missing_fields": ["firstName", "email"]
      },
      "request_id": "req_abc123def456"
    }
  }
  ```
</ResponseExample>