Housecall Pro API

https://docs.housecallpro.com/
Admin
The Housecall Pro API helps service businesses work simpler and grow smarter by offering a public...
Tokens:28,123
Snippets:136
Trust Score:10
Update:1 hour ago
Show doc for...
Tokens:
Raw
### Example Authorization URL

Source: https://docs.housecallpro.com/docs/housecall-public-api/b87d37ae48a0d-authentication

Example authorization URL with sample client_id, redirect_uri, and scope. Used to initiate the OAuth flow.

```text
https://pro.housecallpro.com/oauth/authorize?response_type=code&client_id=abc123xyz&redirect_uri=https://YOUR_WEBSITE_URL/oauth/callback&scope=public
```

--------------------------------

### Successful Token Response

Source: https://docs.housecallpro.com/docs/housecall-public-api/b87d37ae48a0d-authentication

Example response containing access_token, token_type, expires_in, refresh_token, scope, and created_at. expires_in is in seconds.

```json
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "public",
  "created_at": "1750104252"
}
```

--------------------------------

### Partner Job Webhook Payload Example (JSON)

Source: https://docs.housecallpro.com/docs/partner-jobs/46e9e1be07621-webhooks

Example JSON payload for the partner_job.accepted webhook event. The payload includes partner job details, status timestamps, customer, address, schedule, line items, and assigned company (null if unassigned). After the job is assigned, the payload includes Job object data, and attachment URLs expire.

```json
{
  "event": "partner_job.accepted",
  "partner_job": {
    "id": "string",
    "name": "string",
    "job_inbox_partner_id": "string",
    "external_id": "string",
    "total_amount": 75.0,
    "paid_amount": 0.0,
    "paid": "string",
    "expires_at": "string",
    "decline_reason": "string or null",
    "status": "open",
    "status_timestamps": {
      "accepted_at": "2021-01-01T10:00:00Z",
      "declined_at": "2021-01-01T10:00:00Z",
      "assigned_at": "2021-01-01T10:00:00Z",
      "scheduled_at": "2021-01-01T10:00:00Z",
      "pro_en_route": "2021-01-01T10:00:00Z",
      "started_at": "2021-01-01T10:00:00Z",
      "completed_at": "2021-01-01T10:00:00Z"
    },
    "customer": {
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "phone_number": "string",
      "notifications_enabled": true
    },
    "address": {
      "street": "string",
      "street_line2": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "country": "string"
    },
    "schedule": {
      "scheduled_start": "string",
      "scheduled_end": "string"
    },
    "line_items": [
      {
        "name": "string",
        "description": "string",
        "unit_price": 0.0,
        "quantity": 1.0
      }
    ],
    "assigned_company": { // null if unassigned
      "id": "string",
      "name": "string",
      "phone_number": "string",
      "email": "string",
      "website": "string",
      "logo_url": "string",
      "address": {
        "street": "string",
        "street_line_2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      }
    }
  }
}
```

--------------------------------

### Authorization code link (curl GET request)

Source: https://docs.housecallpro.com/docs/partner-jobs/b87d37ae48a0d-authentication

Use this curl command to initiate the OAuth 2.0 authorization code flow. The user will be prompted to log in and authorize the application, then redirected to the callback URL with an authorization code.

```bash
curl -X GET https://pro.housecallpro.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL
```

--------------------------------

### Call Housecall Pro API with Bearer Token

Source: https://docs.housecallpro.com/docs/housecall-public-api/b87d37ae48a0d-authentication

Example HTTP request using the access token in the Authorization header.

```http
GET /api/example_endpoint
Authorization: Bearer ACCESS_TOKEN
```

--------------------------------

### Successful Refresh Token Response

Source: https://docs.housecallpro.com/docs/housecall-public-api/b87d37ae48a0d-authentication

Example JSON response returned when the refresh token request succeeds. The expires_in field indicates the token lifetime in seconds.

```json
{
    "access_token": "ACCESS_TOKEN",
    "token_type": "Bearer",
    "expires_in": 2629745,
    "refresh_token": "REFRESH_TOKEN",
    "scope": "public",
    "created_at": 1752092974
}
```

--------------------------------

### Initiate OAuth Flow with curl

Source: https://docs.housecallpro.com/docs/housecall-public-api/b87d37ae48a0d-authentication

Redirect users to the authorization URL using curl. Replace CLIENT_ID, CALLBACK_URL, and optionally REQUESTED_SCOPES. Must be performed via curl or browser, not Postman.

```bash
curl -X GET https://pro.housecallpro.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=REQUESTED_SCOPES
```

--------------------------------

### Partner Lead Webhook Events

Source: https://docs.housecallpro.com/docs/partner-jobs/46e9e1be07621-webhooks

List of partner lead webhook events with their event keys and descriptions.

```APIDOC
## Partner Lead Webhook Events

| Event Name | Event Key | Description |
| --- | --- | --- |
| Partner Lead Assigned | partner_lead.assigned | The partner lead was successfully delivered to the Assigned Pro's Job Inbox |
| Partner Lead Converted | partner_lead.converted | The assigned Pro copied the partner lead to an estimate or a job |
| Partner Lead Scheduled | partner_lead.scheduled | The assigned Pro set a schedule for the partner lead |
| Partner Lead Pro En Route | partner_lead.pro_en_route | The assigned Pro is on their way to the customer |
| Partner Lead Started | partner_lead.started | The assigned Pro started the partner lead |
| Partner Lead Completed | partner_lead.completed | The assigned Pro completed the partner lead |
| Partner Lead Unassigned | partner_lead.unassigned | The estimate or job associated with the partner lead was deleted or cancelled |
| Partner Lead Sent | partner_lead.sent | The assigned Pro sent the partner lead estimate |
```

--------------------------------

### Partner Lead Webhook Protocol

Source: https://docs.housecallpro.com/docs/partner-jobs/46e9e1be07621-webhooks

Details the delivery headers and payload format for partner lead webhooks.

```APIDOC
## Partner Lead Webhook Protocol

### Delivery Headers

| Header | Description |
| --- | --- |
| Content-Type | Always equal to: 'application/json' |
| Api-Signature | HMAC hex digest of the timestamp and request body joined by '.' respectively, generated using the SHA-256 hash function and the partners secret as the HMAC key |
| Api-Timestamp | Timestamp of the instant the event fired |

### Webhook Payload

(No payload details provided in the source.)
```

--------------------------------

### Callback URL with Authorization Code

Source: https://docs.housecallpro.com/docs/housecall-public-api/b87d37ae48a0d-authentication

The redirect URL after user authorization, containing the authorization code.

```text
https://YOUR_WEBSITE_URL/auth/housecall/callback?code=AUTHORIZATION_CODE
```

--------------------------------

### Job Appointment Webhook Protocol (except job.appointment.appointment_discarded)

Source: https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks

Payload structure for job appointment webhook events, excluding the discarded event. Includes company_id, event, event_occurred_at, and appointment details with dispatched employees.

```APIDOC
## Job Appointment Webhook Protocol (except job.appointment.appointment_discarded)

### Description
Payload structure for job appointment webhook events, excluding the discarded event. Includes company_id, event, event_occurred_at, and appointment details with dispatched employees.

### Payload
```json
{
  "company_id": "string",
  "event": "string",
  "event_occurred_at": "string",
  "appointment": {
    "id": "string",
    "start_time": "string",
    "end_time": "string",
    "arrival_window_minutes": 0,
    "job_id": "string",
    "dispatched_employees": [
      {
        "id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "string",
        "mobile_number": "string",
        "color_hex": "string",
        "avatar_url": "string",
        "role": "string"
      }
    ]
  }
}
```

### Fields
- **company_id** (string) - The company identifier.
- **event** (string) - The event name (e.g., job.appointment.scheduled).
- **event_occurred_at** (string) - Timestamp when the event occurred.
- **appointment.id** (string) - The appointment identifier.
- **appointment.start_time** (string) - Start time of the appointment.
- **appointment.end_time** (string) - End time of the appointment.
- **appointment.arrival_window_minutes** (integer) - Arrival window in minutes.
- **appointment.job_id** (string) - The job identifier.
- **appointment.dispatched_employees** (array) - List of dispatched employees.
  - **id** (string) - Employee identifier.
  - **first_name** (string) - Employee first name.
  - **last_name** (string) - Employee last name.
  - **email** (string) - Employee email.
  - **mobile_number** (string) - Employee mobile number.
  - **color_hex** (string) - Color hex code.
  - **avatar_url** (string) - Avatar URL.
  - **role** (string) - Employee role.
```

--------------------------------

### Estimate Webhook Events

Source: https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks

Lists all estimate-related webhook events with their event keys and descriptions.

```APIDOC
## Estimate Webhook Events

| Event Name | Event Key | Description |
| --- | --- | --- |
| Estimate Created | estimate.created | Estimate created |
| Estimate Updated | estimate.updated | Estimate updated |
| Estimate Scheduled | estimate.scheduled | Estimate scheduled |
| Estimate On My Way | estimate.on_my_way | Pro set estimate status to on my way |
| Estimate Copied to Job | estimate.copy_to_job | Pro created a job from the estimate |
| Estimate Sent | estimate.sent | Pro sent the estimate to a customer |
| Estimate Finished | estimate.completed | Pro set estimate status to finished |
| Estimate Option Created | estimate.option.created | An estimate option was created |
| Estimate Option Approval Status Changed | estimate.option.approval_status_changed | Estimate option was approved or declined |
```

--------------------------------

### Partner Job Webhook Protocol

Source: https://docs.housecallpro.com/docs/partner-jobs/46e9e1be07621-webhooks

Describes the delivery headers and the webhook payload structure for partner job events.

```APIDOC
## Partner Job Webhook Protocol

### Delivery Headers

| Header | Description |
| --- | --- |
| Content-Type | Always equal to: 'application/json' |
| Api-Signature | HMAC hex digest of the timestamp and request body joined by '.' respectively, generated using the SHA-256 hash function and the partners secret as the HMAC key |
| Api-Timestamp | Timestamp of the instant the event fired |

### Webhook Payload

```json
{
  "event": "partner_job.accepted",
  "partner_job": {
    "id": "string",
    "name": "string",
    "job_inbox_partner_id": "string",
    "external_id": "string",
    "total_amount": 75.0,
    "paid_amount": 0.0,
    "paid": "string",
    "expires_at": "string",
    "decline_reason": "string or null",
    "status": "open",
    "status_timestamps": {
      "accepted_at": "2021-01-01T10:00:00Z",
      "declined_at": "2021-01-01T10:00:00Z",
      "assigned_at": "2021-01-01T10:00:00Z",
      "scheduled_at": "2021-01-01T10:00:00Z",
      "pro_en_route": "2021-01-01T10:00:00Z",
      "started_at": "2021-01-01T10:00:00Z",
      "completed_at": "2021-01-01T10:00:00Z"
    },
    "customer": {
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "phone_number": "string",
      "notifications_enabled": true
    },
    "address": {
      "street": "string",
      "street_line2": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "country": "string"
    },
    "schedule": {
      "scheduled_start": "string",
      "scheduled_end": "string"
    },
    "line_items": [
      {
        "name": "string",
        "description": "string",
        "unit_price": 0.0,
        "quantity": 1.0
      }
    ],
    "assigned_company": {
      "id": "string",
      "name": "string",
      "phone_number": "string",
      "email": "string",
      "website": "string",
      "logo_url": "string",
      "address": {
        "street": "string",
        "street_line_2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      }
    }
  }
}
```

Note: Once the job gets past the `assigned` state, the payload will start including data related to the `Job` object that was created on the Service Pro's account. When the Service Pros complete the job and have added attachments, you will be able to fetch them from the provided URLs, but these URLs expire, so fetch the attachments and don't just store the URLs.
```

--------------------------------

### Request access token (curl POST request)

Source: https://docs.housecallpro.com/docs/partner-jobs/b87d37ae48a0d-authentication

Exchange the authorization code for an access token and refresh token. The request must include the client ID, client secret, grant type 'authorization_code', the authorization code, and the redirect URI.

```bash
curl -X POST \
https://api.housecallpro.com/oauth/token \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "CALLBACK_URL"
}'
```

--------------------------------

### Partner Job Webhook Events

Source: https://docs.housecallpro.com/docs/partner-jobs/46e9e1be07621-webhooks

Lists the webhook events that can be triggered for partner jobs, including event names and keys.

```APIDOC
## Partner Job Webhook Events

| Event Name | Event Key | Description |
| --- | --- | --- |
| Partner Job Accepted | partner_job.accepted | HCP accepted the partner job (should always accept available job) |
| Partner Job Declined | partner_job.declined | HCP declined the job because of one of the following reasons: HCP didn't find any organization to match the partner job requirements, All matching organizations declined the partner job, Partner job expired |
| Partner Job Assigned | partner_job.assigned | HCP assigned a Pro to do the partner job |
| Partner Job Scheduled | partner_job.scheduled | The assigned Pro set a schedule for the job |
| Partner Job Pro En Route | partner_job.pro_en_route | The assigned Pro is on his way to the customer |
| Partner Job Started | partner_job.started | The assigned Pro started the partner job |
| Partner Job Completed | partner_job.completed | The assigned Pro completed the partner job |
| Partner Job Unassigned | partner_job.unassigned | The assigned Pro canceled the job, which makes the job available to other Pros |
```
Tokens:
Raw