Public API — POST /leads Endpoint

Overview

The POST /api/v1/leads endpoint lets you submit leads to BlueClerk programmatically. It accepts business name, contact details, and addresses in either a simple string format or a structured object format - giving you flexibility based on how much address data you have available.

Address Formats

String Format

When you only have a single address line, pass it as a string:

{
  "businessName": "ABC Plumbing",
  "contactName": "John Smith",
  "email": "john@abcplumbing.com",
  "phone": "555-1234",
  "address": "123 Main St, Austin, TX 78701",
  "notes": "Interested in HVAC services",
  "source": "Website form"
}

What happens: BlueClerk stores the entire string in the streetAddress field and stubs out city/state/zip fields. This is perfect for partners without structured address data.

Object Format

When you have full address components, pass them as an object:

{
  "businessName": "ABC Plumbing",
  "contactName": "John Smith",
  "email": "john@abcplumbing.com",
  "phone": "555-1234",
  "address": {
    "streetAddress": "123 Main St",
    "address2": "Suite 200",
    "city": "Austin",
    "state": "TX",
    "zipCode": "78701"
  },
  "notes": "Interested in HVAC services",
  "source": "Website form"
}

What happens: BlueClerk stores each component in its proper field, enabling better property matching and geocoding.

Required Fields

• businessName - The lead company name (1-200 characters)

Optional Fields

• contactName - Primary contact person (max 200 characters)
• email - Contact email address (max 200 characters, must be valid email)
• phone - Contact phone number (max 40 characters)
• address - String (max 500 characters) OR object with streetAddress, address2, city, state, zipCode
• notes - Additional context about the lead (max 2000 characters)
• source - Where the lead came from (max 80 characters)

Authentication

This endpoint requires OAuth 2.0 authentication with the leads:write scope. Include your bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Response

Success (201 Created):

{
  "id": "lead_abc123",
  "businessName": "ABC Plumbing",
  "contactName": "John Smith",
  "email": "john@abcplumbing.com",
  "phone": "555-1234",
  "property": {
    "id": "prop_xyz789",
    "streetAddress": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zipCode": "78701"
  },
  "ticket": {
    "id": "ticket_def456",
    "ticketNumber": "T-2024-001",
    "status": "OPEN"
  }
}

Error (400 Bad Request):

{
  "error": "Invalid request body: businessName is required"
}

Use Cases

• String address format - Perfect for web scraping, quick lead capture forms, or situations where you only have a single address line
• Object address format - Ideal when you have structured CRM data or detailed form submissions

Tips

• Use string format when simplicity matters - BlueClerk handles the rest
• Use object format for best property matching and geocoding accuracy
• Include source to track lead origin and conversion rates
• Notes field is great for capturing lead context or initial requirements