Push Leads & Appointments
Directly Into PocketBoss
Connect your lead providers, scheduling tools, and CRM platforms to PocketBoss with our REST API. Simple API key authentication, JSON payloads, instant results.
Instant Delivery
Leads and appointments appear in your dashboard immediately
API Key Auth
Secure Bearer token authentication on every request
Smart Dedup
Duplicate leads are merged automatically by email or phone
Quick Start
Three steps to your first integration.
Generate an API Key
In your PocketBoss dashboard, go to Profile → scroll to API Keys → click Generate Key. Choose which permissions to grant (Push Leads, Push Appointments, Read Appointments).
Keep your key safe. It's shown once at creation. If lost, delete it and generate a new one.
Authenticate Your Requests
Include your API key in every request as a Bearer token:
Authorization: Bearer YOUR_API_KEYSend Your First Request
Push a lead or appointment using the endpoints below. All requests use JSON bodies with Content-Type: application/json.
Base URL
https://api.thepocketboss.com/api/v1Push Leads
Create a new lead in the business CRM. Duplicates are automatically merged by email or phone.
/api/v1/leadsRequest Body
{
"firstName": "John",
"lastName": "Smith",
"email": "[email protected]",
"phone": "5551234567",
"source": "HomeAdvisor",
"serviceRequested": "Kitchen Remodel",
"notes": "Budget around 25k",
"address": "123 Main St",
"city": "Cleveland",
"state": "TN",
"zip": "37311",
"urgency": "high",
"externalId": "LEAD-12345"
}- *Required: firstName (or name) + at least one of email or phone
- *All other fields are optional
- *urgency: "low", "medium", "high", or "emergency"
- *externalId: your system's ID for this lead, stored for reference
- *If a lead with the same email or phone exists, their record is updated (not duplicated)
Response
Response201 Created (or 200 Updated if duplicate)
{
"success": true,
"action": "created",
"lead": {
"id": "6a0698c96c24caa71a452d0a",
"externalId": "LEAD-12345",
"firstName": "John",
"lastName": "Smith",
"email": "[email protected]",
"phone": "5551234567",
"type": "lead",
"status": "new",
"source": "HomeAdvisor",
"createdAt": "2026-05-15T03:53:45.108Z"
}
}All Supported Fields
| Field | Type | Description |
|---|---|---|
| firstName* | string | First name (or use name for full name) |
| lastName | string | Last name |
| email* | string | Email (required if no phone) |
| phone* | string | Phone (required if no email) |
| source | string | Lead provider name (e.g. "HomeAdvisor", "Thumbtack") |
| serviceRequested | string | What the customer needs |
| notes | string | Free-text notes |
| address, city, state, zip | string | Customer address |
| urgency | string | low, medium, high, or emergency |
| propertyType | string | residential, commercial, or business |
| preferredContactMethod | string | call, text, or email |
| externalId | string | Your system's ID for tracking |
| metadata | object | Arbitrary key/value pairs stored on the contact |
* At minimum: firstName (or name) + email or phone
Push Appointments
Create an appointment on the business calendar. A CRM contact is automatically matched or created by email/phone.
/api/v1/appointmentsRequest Body
{
"title": "HVAC quarterly maintenance",
"startDate": "2026-05-15T14:00:00Z",
"duration": 90,
"clientName": "Sarah Johnson",
"clientEmail": "[email protected]",
"clientPhone": "5551234567",
"location": "123 Main St, NYC",
"notes": "Pushed via Google Calendar sync",
"category": "Maintenance",
"externalId": "calendar-event-99887"
}- *Required: title, startDate (ISO 8601 datetime), clientName
- *All other fields are optional
- *duration is in minutes (default: 60). Alternatively send endDate
- *Categories: Maintenance, Repair, Consultation, Installation, Service, Remodeling, Projects
- *externalId: your system's ID for this event, stored for reference
Response
Response201 Created
{
"success": true,
"action": "created",
"appointment": {
"id": "6a0698ed6c24caa71a453323",
"externalId": "calendar-event-99887",
"title": "HVAC quarterly maintenance",
"startDate": "2026-05-15T14:00:00.000Z",
"endDate": "2026-05-15T15:30:00.000Z",
"duration": 90,
"status": "Scheduled",
"clientName": "Sarah Johnson",
"clientEmail": "[email protected]",
"category": "Maintenance",
"source": "api",
"createdAt": "2026-05-15T03:54:21.854Z"
}
}All Supported Fields
| Field | Type | Description |
|---|---|---|
| title* | string | Appointment title / service name |
| startDate* | string | ISO 8601 datetime (e.g. 2026-05-15T14:00:00Z) |
| clientName* | string | Customer full name |
| endDate | string | ISO 8601 end time (or use duration) |
| duration | number | Minutes (default: 60) |
| clientEmail | string | Customer email |
| clientPhone | string | Customer phone |
| location | string | Job location address |
| notes | string | Free-text notes |
| category | string | Maintenance, Repair, Consultation, Installation, Service, Remodeling, Projects |
| externalId | string | Your system's event ID for tracking |
| metadata | object | Arbitrary key/value pairs |
* Required fields
Error Handling
All errors return a JSON object with an error code and human-readable message.
| Status | Error Code | Meaning |
|---|---|---|
| 400 | validation_error | Missing or invalid field. Check the field property for which one. |
| 401 | unauthorized | Missing or invalid API key. |
| 403 | forbidden | API key doesn't have permission for this endpoint. |
| 409 | duplicate_lead | Exact duplicate (rare, usually dedup merges instead). |
| 429 | rate_limited | Too many requests. Back off and retry. |
| 500 | internal_error | Something went wrong on our end. Retry or contact support. |
Good to Know
Rate Limits
Requests are rate-limited per API key. If you hit a 429, back off for a few seconds and retry. Normal integrations won't hit limits.
Email Notifications
Business owners receive an email notification for each new lead and appointment pushed via the API. This can be toggled per API key.
Deduplication
Leads are matched by email first, then phone. If a match is found, the existing contact is updated with new info instead of creating a duplicate.
CRM Integration
Appointments auto-create or match a CRM contact by email/phone. Every API action is logged in the customer's CRM timeline.
Ready to Integrate?
Log in to your PocketBoss account, generate an API key, and start pushing leads in minutes.