Requests API Guide

Requests API

The Requests API allows demand-side partners to programmatically create service requests on behalf of homeowners. When a request is created, matched professionals receive it as a lead.

Creating a Request

POST /api/v4/requests
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "categoryID": "201565295100608806",
  "zipCode": "94102",
  "details": {
    "propertyType": "house",
    "sqft": 1500,
    "timeline": "within_week",
    "description": "Need kitchen cabinets repainted white"
  },
  "customer": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+14155550199"
  },
  "utmData": {
    "utm_source": "partner-name",
    "utm_medium": "api"
  }
}

Response

{
  "requestID": "548954743629463556",
  "status": "active",
  "matchedBusinesses": 5,
  "category": {
    "id": "201565295100608806",
    "name": "Interior Painting"
  },
  "createdAt": "2026-02-15T10:30:00Z"
}

Targeting Specific Businesses

You can optionally target specific businesses by including businessIDs:

{
  "searchID": "548954743629463556",
  "businessIDs": ["468046965846925323", "468046965846925324"],
  "categoryID": "201565295100608806"
}

Request Lifecycle

1. Created — Request submitted and validated
2. Matching — System identifies qualified pros in the area
3. Active — Pros can view and respond to the lead
4. Hired — Customer selects a pro
5. Completed — Job is done and reviewed
6. Expired — No pro was hired within 7 days