Colab Commerce
All recipes
Recipe

Create a lead with a quote request

Capture a new sales prospect together with the products they want a quote on in a single POST /v1/leads call — no follow-up request required.

LLM Instruction Set

Markdown built for an LLM to ingest this recipe verbatim.

Overview

The most common Colab Commerce integration is capturing a new sales prospect together with the products they're asking about. You can do this in a single POST /v1/leads request by nesting an initial LeadActivity::QuoteRequest under the lead's lead_activities attribute. No second call is needed.

Key points

  • Authenticate with your API key via the X-Api-Key header — see Authentication.
  • The lead's owner is always set server-side to the authenticated user's Company. Any owner_id / owner_type you send in the payload is ignored.
  • assignee is optional. When supplied it must be a CompanyRetailerLocation that belongs to the same company — send assignee_type: "CompanyRetailerLocation" and assignee_id: <crl uuid>. Omit both fields to leave the lead unassigned for downstream round-robin or manual assignment.
  • Provide at least one contact channel — emails or phone_numbers (or both).
  • The quote request payload lives under data.products and must contain at least one product. Each product is a free-form hash; recognized keys are name, category, quantity, price, sku, url, image_url, and options. Any other keys are preserved on the activity but ignored by the model.
  • Optional data.notes captures a freeform shopper message; optional data.additionalData is a passthrough object for anything else your form collects.

Request — unassigned (most common)

The minimal shape: a lead with at least one contact channel and one nested LeadActivity::QuoteRequest carrying a product list. The lead lands unassigned and is routed downstream.

HTTP
POST /v1/leads
Content-Type: application/json
X-Api-Key: <api_key>

{
  "lead": {
    "name": "Jane Customer",
    "emails": [{ "email": "jane@example.com" }],
    "phone_numbers": [
      { "phone_number": "+15555550100", "country_code": "US" }
    ],
    "location": {
      "street_line_one": "123 Main St",
      "city": "Calgary",
      "province": "AB",
      "postal_code": "T2P 1J9",
      "country": "CA"
    },
    "lead_activities": [
      {
        "type": "LeadActivity::QuoteRequest",
        "data": {
          "notes": "Looking for delivery before the long weekend.",
          "products": [
            {
              "name": "Westwood Sofa",
              "sku": "WS-3001-CHAR",
              "category": "Sofas",
              "quantity": 1,
              "price": 1899.00,
              "url": "https://example.com/products/westwood-sofa",
              "image_url": "https://example.com/img/ws-3001.jpg",
              "options": {
                "color": "Charcoal",
                "fabric": "Performance Weave"
              }
            }
          ]
        }
      }
    ]
  }
}

Request — pre-assigned to a retailer location

Use this shape when your form already knows which retailer location should handle the lead (for example, a "request a quote from this store" button on a store detail page). The assignee must be a CompanyRetailerLocation owned by your company.

HTTP
POST /v1/leads
Content-Type: application/json
X-Api-Key: <api_key>

{
  "lead": {
    "name": "Jane Customer",
    "assignee_type": "CompanyRetailerLocation",
    "assignee_id": "9b8f0d2e-1a3c-4b6d-8e9f-0a1b2c3d4e5f",
    "emails": [{ "email": "jane@example.com" }],
    "phone_numbers": [
      { "phone_number": "+15555550100", "country_code": "US" }
    ],
    "lead_activities": [
      {
        "type": "LeadActivity::QuoteRequest",
        "source_type": "CompanyRetailerLocation",
        "source_id": "9b8f0d2e-1a3c-4b6d-8e9f-0a1b2c3d4e5f",
        "data": {
          "notes": "Customer requested in-store pickup.",
          "products": [
            {
              "name": "Westwood Sofa",
              "sku": "WS-3001-CHAR",
              "quantity": 1,
              "price": 1899.00,
              "options": { "color": "Charcoal" }
            },
            {
              "name": "Westwood Loveseat",
              "sku": "WL-3002-CHAR",
              "quantity": 1,
              "price": 1499.00
            }
          ],
          "additionalData": {
            "campaign": "spring-2026",
            "referrer": "https://example.com/landing/spring-promo"
          }
        }
      }
    ]
  }
}

cURL

Save either payload above as lead.json and POST it from your shell:

bash
curl -X POST "https://api.colabcommerce.com/v1/leads" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $CC_API_KEY" \
  -d @lead.json

JavaScript (Node 18+)

Never call this from a browser — API keys must stay server-side.

JavaScript
// Node 18+ — never call this from a browser; the API key must stay server-side.
const res = await fetch('https://api.colabcommerce.com/v1/leads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.CC_API_KEY,
  },
  body: JSON.stringify({
    lead: {
      name: 'Jane Customer',
      emails: [{ email: 'jane@example.com' }],
      phone_numbers: [
        { phone_number: '+15555550100', country_code: 'US' },
      ],
      lead_activities: [
        {
          type: 'LeadActivity::QuoteRequest',
          data: {
            notes: 'Looking for delivery before the long weekend.',
            products: [
              {
                name: 'Westwood Sofa',
                sku: 'WS-3001-CHAR',
                quantity: 1,
                price: 1899.0,
                options: { color: 'Charcoal' },
              },
            ],
          },
        },
      ],
    },
  }),
})

if (!res.ok) {
  const error = await res.json()
  throw new Error(`Lead create failed: ${res.status} ${JSON.stringify(error)}`)
}

const { lead } = await res.json()

Response

On success the API returns 201 Created and the serialized lead. The newly-created quote request is returned as the first element of lead_activities. See Errors for the envelope returned on validation failure.

201 Created
{
  "lead": {
    "id": "f1c0e7d4-...-...",
    "name": "Jane Customer",
    "status": "New",
    "created_at": "2026-05-19T15:42:11Z",
    "emails": [{ "id": "...", "email": "jane@example.com" }],
    "phone_numbers": [
      {
        "id": "...",
        "phone_number": "+15555550100",
        "country_code": "US",
        "formatted": "+1 555-555-0100"
      }
    ],
    "location": {
      "id": "...",
      "street_line_one": "123 Main St",
      "city": "Calgary",
      "province": "AB",
      "postal_code": "T2P 1J9",
      "country": "CA",
      "latitude": 51.0447,
      "longitude": -114.0719
    },
    "lead_activities": [
      {
        "id": "...",
        "type": "LeadActivity::QuoteRequest",
        "data": {
          "notes": "Looking for delivery before the long weekend.",
          "products": [
            {
              "name": "Westwood Sofa",
              "sku": "WS-3001-CHAR",
              "quantity": 1,
              "price": 1899.0,
              "...": "..."
            }
          ]
        }
      }
    ]
  }
}