### Example OAuth 2.0 Authorization URL

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

An example of a fully formed URL to initiate the OAuth 2.0 flow. This URL is used to redirect users to Housecall Pro for login and authorization. It includes client ID, redirect URI, and requested scopes.

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

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

### Access Token Response Example (JSON)

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

An example JSON response when successfully exchanging an authorization code for an access token. It includes the access token, token type, expiration time, refresh token, scope, and creation timestamp.

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

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

### Refresh Token Response Example (JSON)

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

An example JSON response when successfully refreshing an access token. It provides a new access token and potentially a new refresh token, along with expiration details.

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

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

### Authenticating API Requests

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

Demonstrates how to use the obtained access token to authenticate requests to Housecall Pro APIs.

```APIDOC
## Authenticating API Requests

### Description
To make authenticated requests to Housecall Pro APIs, include the access token in the `Authorization` header.

### Method
Any (e.g., GET, POST, PUT, DELETE)

### Endpoint
Any Housecall Pro API endpoint

### Headers
- **Authorization** (string) - Required - Format: `Bearer ACCESS_TOKEN`

### Request Example
```http
GET /api/example_endpoint
Authorization: Bearer ACCESS_TOKEN
```

**Note:** Ensure the requested resource is within the scope granted by the user during the OAuth flow.
```

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

### Invalid Token Response Example (JSON)

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

An example JSON response indicating an invalid, expired, revoked, or mismatched authorization grant. This response helps in debugging authentication failures.

```json
{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
```

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

### API Key Authentication Header Example

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

This code snippet demonstrates the correct format for including an API key in the Authorization header for authenticated API requests to the Housecall Pro server.

```http
Authorization: Token 0046421dc0ba47ec87bef0c089415380
```

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

### OAuth 2.0 Authorization Code Flow

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

This section outlines the steps for official Integration Partners to set up OAuth 2.0 authorization using the Authorization Code Flow. This flow allows users to grant your application specific access to their Housecall Pro data securely.

```APIDOC
## 🔐 Setting Up OAuth 2.0 Authorization (For Official Integration Partners Only)

To integrate your application with Housecall Pro using OAuth 2.0, follow the **Authorization Code Flow**.

**Note**: OAuth 2.0 is available exclusively for official integration partners. All other developers should use API key authentication.

### 🎯 OAuth 2.0 Background

OAuth 2.0 is an industry-standard authorization framework that allows third-party applications to access user data without exposing user credentials. It provides secure access, controlled permissions, revokable access, and token expiration.

We use the **Authorization Code Flow**, the most secure OAuth 2.0 flow for server-side applications. This involves redirecting users to Housecall Pro for authentication and then exchanging an authorization code for access tokens.

**User Experience**: Users will be redirected to Housecall Pro to log in, review requested permissions, and then return to your application with authorization granted.

### 🔑 OAuth Endpoints

*   **Authorization Endpoint**: `https://pro.housecallpro.com/oauth/authorize`
    *   Purpose: User login and authorization.
*   **Token Exchange Endpoint**: `https://api.housecallpro.com/oauth/token`
    *   Purpose: Getting and refreshing access tokens.

### 📩 1. Request OAuth App Credentials

Email `apideveloper@housecallpro.com` with:

*   Your **application name** and **purpose**.
*   Your `redirect_uri` (also called `CALLBACK_URL`) — where Housecall Pro will redirect users after authorization.

Upon approval, you will receive:

*   `CLIENT_ID`
*   `CLIENT_SECRET`
*   `REQUESTED_SCOPES` (if applicable)

### 🚦 2. Initiate the OAuth Flow

Redirect users to the authorization URL. This step must be performed using `curl` or in a **browser**, as it requires user login and redirect handling.

#### Request

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

**Replace:**

*   `CLIENT_ID`: Your provided client ID.
*   `CALLBACK_URL`: Your registered redirect URI (must match exactly).
*   `REQUESTED_SCOPES`: (Optional) The scopes requested for your application.

**Example:**

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

**Note**: The OAuth flow begins at `https://pro.housecallpro.com/oauth/authorize` (for user interaction), but all token exchanges happen via `https://api.housecallpro.com/oauth/token`.
```

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

### Exchange Authorization Code for Access Token (cURL)

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

Use a cURL command to exchange an authorization code for an access token. This request includes client credentials, grant type, the authorization code, and the redirect URI. The API responds with access and refresh tokens or an error.

```shell
$ 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"
  }'
```

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

### Authentication Methods

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

Housecall Pro supports two primary methods for API authentication: API Keys for Pro users and OAuth 2.0 for verified Integration Partners. Both methods require the token or key to be included in the Authorization header.

```APIDOC
## Authentication

Housecall Pro uses both API keys and OAuth 2.0 as a means of authenticating with our API.

*   **API Key**: For Pro users building custom integrations. Learn more about generating your API Keys [here](link-to-api-key-generation).
*   **OAuth 2.0**: For verified Integration Partners to authenticate users.

Both methods require the `Authorization` header to be set correctly:

### API Key Authentication
```
Authorization: Token 0046421dc0ba47ec87bef0c089415380
```

### OAuth 2.0 Authentication
```
Authorization: Bearer d7f65570a4714ae944fbe58acc05ffb20c29534170ac483a3683b91f8dfe9d43
```

**Note**: The header must start with either `Token` or `Bearer` exactly as shown. If you encounter authentication errors, please send your cURL command to apideveloper@housecallpro.com for investigation.
```

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

### API Request Authentication Header

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

Demonstrates how to include the access token in the Authorization header for making authenticated requests to the Housecall Pro API. The token should be prefixed with 'Bearer '.

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

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

### Exchange Authorization Code for Access Token

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

This endpoint is used to exchange an authorization code, obtained after user login and consent, for an access token and a refresh token.

```APIDOC
## POST /oauth/token

### Description
Exchanges an authorization code for an access token and refresh token.

### Method
POST

### Endpoint
https://api.housecallpro.com/oauth/token

### Parameters
#### Request Body
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
- **grant_type** (string) - Required - Must be set to "authorization_code".
- **code** (string) - Required - The authorization code received after user authorization.
- **redirect_uri** (string) - Required - The callback URL registered with Housecall Pro.

### Request Example
```json
{
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "CALLBACK_URL"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token for authenticating API requests.
- **token_type** (string) - The type of token, typically "Bearer".
- **expires_in** (integer) - The token's lifetime in seconds.
- **refresh_token** (string) - A token to obtain a new access token when the current one expires.
- **scope** (string) - The scope of the granted permissions.
- **created_at** (string) - The timestamp when the token was created.

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

#### Error Response (e.g., 400)
- **error** (string) - An error code, e.g., "invalid_grant".
- **error_description** (string) - A description of the error.

#### Error Response Example
```json
{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
```
```

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

### Initiate OAuth 2.0 Authorization Code Flow

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

This cURL command initiates the OAuth 2.0 Authorization Code Flow by redirecting users to the Housecall Pro authorization endpoint. Replace placeholders with your specific credentials and redirect URI.

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

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

### OAuth 2.0 Bearer Token Authentication Header Example

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

This code snippet shows the required format for an OAuth 2.0 Bearer token in the Authorization header when making authenticated API requests to Housecall Pro.

```http
Authorization: Bearer d7f65570a4714ae944fbe58acc05ffb20c29534170ac483a3683b91f8dfe9d43
```

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

### Refreshing Expired Access Tokens

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

Use this endpoint with a refresh token to obtain a new access token when the current one has expired.

```APIDOC
## POST /oauth/token (Refresh Token)

### Description
Obtains a new access token using a refresh token.

### Method
POST

### Endpoint
https://api.housecallpro.com/oauth/token

### Parameters
#### Request Body
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
- **grant_type** (string) - Required - Must be set to "refresh_token".
- **refresh_token** (string) - Required - The refresh token previously obtained.
- **redirect_uri** (string) - Required - The callback URL registered with Housecall Pro.

### Request Example
```json
{
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "grant_type": "refresh_token",
    "refresh_token": "the_refresh_token_value_goes_here",
    "redirect_uri": "CALLBACK_URL"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The new access token.
- **token_type** (string) - The type of token, typically "Bearer".
- **expires_in** (integer) - The new token's lifetime in seconds.
- **refresh_token** (string) - A new refresh token (may be the same or different).
- **scope** (string) - The scope of the granted permissions.
- **created_at** (string) - The timestamp when the new token was created.

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

#### Error Response (e.g., 400)
- **error** (string) - An error code, e.g., "invalid_grant".
- **error_description** (string) - A description of the error.

#### Error Response Example
```json
{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
```
```

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

### Get Company Information (including Location IDs)

Source: https://docs.housecallpro.com/docs/housecall-public-api/4c64fe617d191-multi-location-enabled-ap-is

Retrieve company details, including a list of all location IDs. This is the first step in setting up multi-location API access.

```APIDOC
## GET /company

### Description
Retrieves all information about the company, including a list of its locations. This endpoint is crucial for identifying location IDs needed for multi-location API requests.

### Method
GET

### Endpoint
https://api.housecallpro.com/company

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Example
None (GET request)

### Response
#### Success Response (200)
- **locations** (array) - An array of location objects, each containing details and an ID for a specific location.
- **Other company details** (various types) - Additional information about the company.

#### Response Example
{
  "locations": [
    {
      "id": "ce348586-c67a-4d5b-812f-9480514f84f2",
      "name": "Main Office",
      "address": "123 Main St, Anytown, CA 90210"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "Branch Office",
      "address": "456 Oak Ave, Otherville, CA 90211"
    }
  ]
}
```

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

### Retrieve Location IDs using GET company endpoint

Source: https://docs.housecallpro.com/docs/housecall-public-api/4c64fe617d191-multi-location-enabled-ap-is

This API call retrieves all location information associated with a company account. The response includes a 'locations' object containing details for each location, including their IDs, which are necessary for subsequent multi-location API requests. This endpoint is essential for setting up multi-location API access.

```HTTP
GET https://api.housecallpro.com/company
```

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

### Webhooks

Source: https://docs.housecallpro.com/index

Receive real-time events for various actions within Housecall Pro, such as job creation, completion, and payment.

```APIDOC
## Webhook Events

### Description
Housecall Pro can send real-time notifications to your specified webhook URL when certain events occur.

### Supported Events
- **job.created**: Triggered when a new job is created.
- **job.scheduled**: Triggered when a job's schedule is updated.
- **job.completed**: Triggered when a job is marked as completed.
- **job.paid**: Triggered when a job is marked as paid.
- **estimate.created**: Triggered when a new estimate is created.
- **estimate.completed**: Triggered when an estimate is completed.
- **estimate.won**: Triggered when an estimate is marked as won.
- **customer.created**: Triggered when a new customer is created.
- **customer.updated**: Triggered when a customer's information is updated.

### Setting Up Webhooks
To set up webhooks, navigate to the "Integrations" or "Webhooks" section in your Housecall Pro account settings and provide your desired webhook URL. You may also need to configure which events you wish to receive notifications for.

### Request Example (job.created event)
```json
{
  "eventType": "job.created",
  "data": {
    "jobId": "job_789ghi",
    "customerId": "cust_123abc",
    "title": "Plumbing Repair",
    "createdAt": "2023-10-27T11:00:00Z"
  }
}
```
```

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

### Pricebook API - Materials

Source: https://docs.housecallpro.com/docs/housecall-public-api/p5zsg5n9sbiij-pricebook-api

Endpoints for managing materials within the Pricebook API. This includes indexing, creating, updating, and deleting materials.

```APIDOC
## GET /pricebook/v1/materials

### Description
Retrieves a list of all materials available in the pricebook.

### Method
GET

### Endpoint
/pricebook/v1/materials

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

### Response
#### Success Response (200)
- **materials** (array) - A list of material objects.
  - **id** (string) - The unique identifier for the material.
  - **name** (string) - The name of the material.
  - **price** (number) - The price of the material.

#### Response Example
```json
{
  "materials": [
    {
      "id": "mat_123",
      "name": "Standard Bolt",
      "price": 1.50
    }
  ]
}
```
```

```APIDOC
## POST /pricebook/v1/materials

### Description
Creates a new material in the pricebook.

### Method
POST

### Endpoint
/pricebook/v1/materials

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

#### Request Body
- **name** (string) - Required - The name of the material.
- **price** (number) - Required - The price of the material.

### Request Example
```json
{
  "name": "Heavy Duty Screw",
  "price": 2.75
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the newly created material.
- **name** (string) - The name of the material.
- **price** (number) - The price of the material.

#### Response Example
```json
{
  "id": "mat_456",
  "name": "Heavy Duty Screw",
  "price": 2.75
}
```
```

```APIDOC
## PUT /pricebook/v1/materials/{material_id}

### Description
Updates an existing material in the pricebook.

### Method
PUT

### Endpoint
/pricebook/v1/materials/{material_id}

### Parameters
#### Path Parameters
- **material_id** (string) - Required - The ID of the material to update.

#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

#### Request Body
- **name** (string) - Optional - The updated name of the material.
- **price** (number) - Optional - The updated price of the material.

### Request Example
```json
{
  "price": 3.00
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the updated material.
- **name** (string) - The name of the material.
- **price** (number) - The updated price of the material.

#### Response Example
```json
{
  "id": "mat_456",
  "name": "Heavy Duty Screw",
  "price": 3.00
}
```
```

```APIDOC
## DELETE /pricebook/v1/materials/{material_id}

### Description
Deletes a material from the pricebook.

### Method
DELETE

### Endpoint
/pricebook/v1/materials/{material_id}

### Parameters
#### Path Parameters
- **material_id** (string) - Required - The ID of the material to delete.

#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

### Response
#### Success Response (204)
No content is returned on successful deletion.

#### Response Example
(No content)
```

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

### Job Management API

Source: https://docs.housecallpro.com/index

Endpoints for creating and retrieving job information. Manage work orders and associated details.

```APIDOC
## POST /api/jobs

### Description
Creates a new job in the Housecall Pro system.

### Method
POST

### Endpoint
/api/jobs

#### Request Body
- **customerId** (string) - Required - The ID of the customer associated with the job.
- **title** (string) - Required - A brief title for the job.
- **description** (string) - Optional - A detailed description of the work to be performed.
- **scheduledTime** (string) - Optional - The scheduled date and time for the job (ISO 8601 format).

### Request Example
```json
{
  "customerId": "cust_123abc",
  "title": "Plumbing Repair",
  "description": "Fix leaky faucet in kitchen.",
  "scheduledTime": "2023-10-28T14:00:00Z"
}
```

### Response
#### Success Response (201)
- **jobId** (string) - The unique identifier for the newly created job.

#### Response Example
```json
{
  "jobId": "job_789ghi"
}
```
```

```APIDOC
## GET /api/jobs/{jobId}

### Description
Retrieves details for a specific job.

### Method
GET

### Endpoint
/api/jobs/{jobId}

#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the job to retrieve.

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the job.
- **customerId** (string) - The ID of the customer associated with the job.
- **title** (string) - The title of the job.
- **description** (string) - The description of the job.
- **status** (string) - The current status of the job (e.g., "Scheduled", "Completed", "Paid").
- **createdAt** (string) - The timestamp when the job was created.

#### Response Example
```json
{
  "jobId": "job_789ghi",
  "customerId": "cust_123abc",
  "title": "Plumbing Repair",
  "description": "Fix leaky faucet in kitchen.",
  "status": "Scheduled",
  "createdAt": "2023-10-27T11:00:00Z"
}
```
```

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

### Housecall v1 API Overview

Source: https://docs.housecallpro.com/docs/housecall-public-api/a4ca20a18010c-housecall-v1-api

General information about the Housecall v1 API, including its base URL and areas it covers.

```APIDOC
## Housecall v1 API Overview

### Description
Provides access to various functionalities of the Housecall Pro platform for managing business operations. This includes managing customers, estimates, jobs, invoices, pricebooks, and more.

### API Base URL
`https://api.housecallpro.com`

### Key Features
- Customer Management
- Estimate and Job Management
- Invoice and Pricebook Management
- Webhooks for real-time updates
- Multi-location support for certain APIs
```

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

### Refresh Expired Access Token (cURL)

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

Use a cURL command to refresh an expired access token using a refresh token. This request is similar to the initial token exchange but uses 'refresh_token' as the grant type.

```shell
$ 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": "refresh_token",
"refresh_token": "the_refresh_token_value_goes_here",
"redirect_uri": "CALLBACK_URL"
}'
```

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

### Customers API

Source: https://docs.housecallpro.com/docs/housecall-public-api/a4ca20a18010c-housecall-v1-api

Endpoints for managing customer information, including creating, retrieving, updating, and deleting customers.

```APIDOC
## Customers API

### Description
Manage customer records within the Housecall Pro system. This API allows for CRUD (Create, Read, Update, Delete) operations on customer data.

### Endpoints
- `GET /v1/customers`: Retrieve a list of customers.
- `POST /v1/customers`: Create a new customer.
- `GET /v1/customers/{id}`: Retrieve a specific customer by ID.
- `PUT /v1/customers/{id}`: Update a specific customer by ID.
- `DELETE /v1/customers/{id}`: Delete a specific customer by ID.
```

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

### Pricebook API - Price Forms

Source: https://docs.housecallpro.com/docs/housecall-public-api/p5zsg5n9sbiij-pricebook-api

Endpoints for managing price forms within the Pricebook API. This includes indexing, creating, showing, updating, and deleting price forms.

```APIDOC
## GET /pricebook/v1/price_forms

### Description
Retrieves a list of all price forms.

### Method
GET

### Endpoint
/pricebook/v1/price_forms

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

### Response
#### Success Response (200)
- **price_forms** (array) - A list of price form objects.
  - **id** (string) - The unique identifier for the price form.
  - **name** (string) - The name of the price form.

#### Response Example
```json
{
  "price_forms": [
    {
      "id": "pf_xyz",
      "name": "Standard Labor Rate"
    }
  ]
}
```
```

```APIDOC
## POST /pricebook/v1/price_forms

### Description
Creates a new price form.

### Method
POST

### Endpoint
/pricebook/v1/price_forms

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

#### Request Body
- **name** (string) - Required - The name of the price form.

### Request Example
```json
{
  "name": "Overtime Labor Rate"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the newly created price form.
- **name** (string) - The name of the price form.

#### Response Example
```json
{
  "id": "pf_uvw",
  "name": "Overtime Labor Rate"
}
```
```

```APIDOC
## GET /pricebook/v1/price_forms/{price_form_id}

### Description
Retrieves a specific price form by its ID.

### Method
GET

### Endpoint
/pricebook/v1/price_forms/{price_form_id}

### Parameters
#### Path Parameters
- **price_form_id** (string) - Required - The ID of the price form to retrieve.

#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the price form.
- **name** (string) - The name of the price form.

#### Response Example
```json
{
  "id": "pf_xyz",
  "name": "Standard Labor Rate"
}
```
```

```APIDOC
## PUT /pricebook/v1/price_forms/{price_form_id}

### Description
Updates an existing price form.

### Method
PUT

### Endpoint
/pricebook/v1/price_forms/{price_form_id}

### Parameters
#### Path Parameters
- **price_form_id** (string) - Required - The ID of the price form to update.

#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

#### Request Body
- **name** (string) - Optional - The updated name of the price form.

### Request Example
```json
{
  "name": "Standard Labor Rate (Updated)"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the updated price form.
- **name** (string) - The updated name of the price form.

#### Response Example
```json
{
  "id": "pf_xyz",
  "name": "Standard Labor Rate (Updated)"
}
```
```

```APIDOC
## DELETE /pricebook/v1/price_forms/{price_form_id}

### Description
Deletes a price form.

### Method
DELETE

### Endpoint
/pricebook/v1/price_forms/{price_form_id}

### Parameters
#### Path Parameters
- **price_form_id** (string) - Required - The ID of the price form to delete.

#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

### Response
#### Success Response (204)
No content is returned on successful deletion.

#### Response Example
(No content)
```

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

### Customer Management API

Source: https://docs.housecallpro.com/index

Endpoints for creating and retrieving customer information. Manage your customer base efficiently through the API.

```APIDOC
## POST /api/customers

### Description
Creates a new customer in the Housecall Pro system.

### Method
POST

### Endpoint
/api/customers

#### Request Body
- **firstName** (string) - Required - The first name of the customer.
- **lastName** (string) - Required - The last name of the customer.
- **email** (string) - Optional - The email address of the customer.
- **phone** (string) - Optional - The phone number of the customer.

### Request Example
```json
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "123-456-7890"
}
```

### Response
#### Success Response (201)
- **customerId** (string) - The unique identifier for the newly created customer.

#### Response Example
```json
{
  "customerId": "cust_123abc"
}
```
```

```APIDOC
## GET /api/customers/{customerId}

### Description
Retrieves detailed information for a specific customer.

### Method
GET

### Endpoint
/api/customers/{customerId}

#### Path Parameters
- **customerId** (string) - Required - The unique identifier of the customer to retrieve.

### Response
#### Success Response (200)
- **customerId** (string) - The unique identifier for the customer.
- **firstName** (string) - The first name of the customer.
- **lastName** (string) - The last name of the customer.
- **email** (string) - The email address of the customer.
- **phone** (string) - The phone number of the customer.
- **createdAt** (string) - The timestamp when the customer was created.

#### Response Example
```json
{
  "customerId": "cust_123abc",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "123-456-7890",
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

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

### Attachments and Links API

Source: https://docs.housecallpro.com/index

Endpoints for adding attachments and links to jobs. Enhance job records with relevant documents and URLs.

```APIDOC
## POST /api/jobs/{jobId}/attachments

### Description
Adds an attachment or a link to a specific job.

### Method
POST

### Endpoint
/api/jobs/{jobId}/attachments

#### Path Parameters
- **jobId** (string) - Required - The ID of the job to which the attachment/link will be added.

#### Request Body
- **url** (string) - Required if type is 'link' - The URL of the resource.
- **fileName** (string) - Required if type is 'file' - The name of the file.
- **fileContent** (string) - Required if type is 'file' - The base64 encoded content of the file.
- **type** (string) - Required - The type of item to add ('file' or 'link').

### Request Example
```json
{
  "url": "https://example.com/document.pdf",
  "type": "link"
}
```

### Response
#### Success Response (201)
- **attachmentId** (string) - The unique identifier for the added attachment or link.

#### Response Example
```json
{
  "attachmentId": "att_abc123"
}
```
```

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

### Specifying Location Context with X-Company-Id Header

Source: https://docs.housecallpro.com/docs/housecall-public-api/4c64fe617d191-multi-location-enabled-ap-is

Learn how to use the `X-Company-Id` header to specify which location's data you want to access in your API requests.

```APIDOC
## Using X-Company-Id Header

### Description
To query or manage data for a specific location, include the `X-Company-Id` header in your API request, setting its value to the desired location ID obtained from the `/company` endpoint.

### Method
All supported HTTP methods (GET, POST, PUT, DELETE, etc.)

### Endpoint
Any supported Housecall Pro API endpoint

### Parameters
#### Headers
- **X-Company-Id** (string) - Required - The ID of the location whose data you want to access.

### Request Example
```
GET https://api.housecallpro.com/jobs

Headers:
  Authorization: Bearer YOUR_API_KEY
  X-Company-Id: ce348586-c67a-4d5b-812f-9480514f84f2
```

### Response
#### Success Response (200)
- The response will contain data relevant to the location specified in the `X-Company-Id` header.

#### Response Example
(Response content will vary based on the endpoint and the specified location's data)
```

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

### Pricebook API - Material Categories

Source: https://docs.housecallpro.com/docs/housecall-public-api/p5zsg5n9sbiij-pricebook-api

Endpoints for managing material categories within the Pricebook API. This includes indexing, creating, updating, and deleting categories.

```APIDOC
## GET /pricebook/v1/material_categories

### Description
Retrieves a list of all material categories.

### Method
GET

### Endpoint
/pricebook/v1/material_categories

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

### Response
#### Success Response (200)
- **categories** (array) - A list of material category objects.
  - **id** (string) - The unique identifier for the category.
  - **name** (string) - The name of the category.

#### Response Example
```json
{
  "categories": [
    {
      "id": "cat_abc",
      "name": "Fasteners"
    }
  ]
}
```
```

```APIDOC
## POST /pricebook/v1/material_categories

### Description
Creates a new material category.

### Method
POST

### Endpoint
/pricebook/v1/material_categories

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

#### Request Body
- **name** (string) - Required - The name of the material category.

### Request Example
```json
{
  "name": "Plumbing Supplies"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the newly created category.
- **name** (string) - The name of the category.

#### Response Example
```json
{
  "id": "cat_def",
  "name": "Plumbing Supplies"
}
```
```

```APIDOC
## PUT /pricebook/v1/material_categories/{category_id}

### Description
Updates an existing material category.

### Method
PUT

### Endpoint
/pricebook/v1/material_categories/{category_id}

### Parameters
#### Path Parameters
- **category_id** (string) - Required - The ID of the category to update.

#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

#### Request Body
- **name** (string) - Optional - The updated name of the category.

### Request Example
```json
{
  "name": "Advanced Plumbing Supplies"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the updated category.
- **name** (string) - The updated name of the category.

#### Response Example
```json
{
  "id": "cat_def",
  "name": "Advanced Plumbing Supplies"
}
```
```

```APIDOC
## DELETE /pricebook/v1/material_categories/{category_id}

### Description
Deletes a material category.

### Method
DELETE

### Endpoint
/pricebook/v1/material_categories/{category_id}

### Parameters
#### Path Parameters
- **category_id** (string) - Required - The ID of the category to delete.

#### Query Parameters
- **api_key** (string) - Required - Your organization-specific API key.

### Response
#### Success Response (204)
No content is returned on successful deletion.

#### Response Example
(No content)
```

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

### Employee Management API

Source: https://docs.housecallpro.com/index

Endpoints for creating and retrieving employee information. Manage your team members and their roles.

```APIDOC
## POST /api/employees

### Description
Creates a new employee profile in the Housecall Pro system.

### Method
POST

### Endpoint
/api/employees

#### Request Body
- **firstName** (string) - Required - The first name of the employee.
- **lastName** (string) - Required - The last name of the employee.
- **role** (string) - Required - The role of the employee (e.g., "Field Tech", "Office Admin").
- **email** (string) - Optional - The email address of the employee.

### Request Example
```json
{
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "Field Tech",
  "email": "jane.smith@company.com"
}
```

### Response
#### Success Response (201)
- **employeeId** (string) - The unique identifier for the newly created employee.

#### Response Example
```json
{
  "employeeId": "emp_456def"
}
```
```

```APIDOC
## GET /api/employees/{employeeId}

### Description
Retrieves details for a specific employee.

### Method
GET

### Endpoint
/api/employees/{employeeId}

#### Path Parameters
- **employeeId** (string) - Required - The unique identifier of the employee to retrieve.

### Response
#### Success Response (200)
- **employeeId** (string) - The unique identifier for the employee.
- **firstName** (string) - The first name of the employee.
- **lastName** (string) - The last name of the employee.
- **role** (string) - The role of the employee.
- **email** (string) - The email address of the employee.
- **isActive** (boolean) - Indicates if the employee account is active.

#### Response Example
```json
{
  "employeeId": "emp_456def",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "Field Tech",
  "email": "jane.smith@company.com",
  "isActive": true
}
```
```

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

### Initiate OAuth 2.0 Authorization Code Flow

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

This cURL command initiates the OAuth 2.0 authorization code flow. It requires your client ID and redirect URI, and prompts the user to log in and authorize the application.

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

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

### Pricebook API

Source: https://docs.housecallpro.com/docs/housecall-public-api/a4ca20a18010c-housecall-v1-api

Endpoints for managing the company's pricebook, including services, materials, and their associated costs.

```APIDOC
## Pricebook API

### Description
Manage the company's pricebook, which includes services, materials, and their pricing details. This ensures accurate cost calculation for estimates and invoices.

### Endpoints
- `GET /v1/pricebook/services`: Retrieve a list of services in the pricebook.
- `POST /v1/pricebook/services`: Add a new service to the pricebook.
- `GET /v1/pricebook/materials`: Retrieve a list of materials in the pricebook.
- `POST /v1/pricebook/materials`: Add a new material to the pricebook.
```

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

### Webhooks API

Source: https://docs.housecallpro.com/docs/housecall-public-api/a4ca20a18010c-housecall-v1-api

Endpoints for managing webhooks to receive real-time notifications about events within the Housecall Pro system.

```APIDOC
## Webhooks API

### Description
Configure and manage webhooks to receive real-time event notifications from Housecall Pro. This enables asynchronous updates and integrations.

### Endpoints
- `POST /v1/webhooks`: Register a new webhook endpoint.
- `GET /v1/webhooks`: Retrieve a list of registered webhooks.
- `DELETE /v1/webhooks/{id}`: Unregister a webhook.
```

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

### Invoices API

Source: https://docs.housecallpro.com/docs/housecall-public-api/a4ca20a18010c-housecall-v1-api

Endpoints for managing invoices, including creation, retrieval, updating, and sending invoices to customers.

```APIDOC
## Invoices API

### Description
Manage customer invoices. This API allows for the creation, retrieval, and updating of invoices, as well as actions like sending them to customers.

### Endpoints
- `GET /v1/invoices`: Retrieve a list of invoices.
- `POST /v1/invoices`: Create a new invoice.
- `GET /v1/invoices/{id}`: Retrieve a specific invoice by ID.
- `PUT /v1/invoices/{id}`: Update a specific invoice by ID.
- `POST /v1/invoices/{id}/send`: Send an invoice to a customer.
```

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

### Jobs API

Source: https://docs.housecallpro.com/docs/housecall-public-api/a4ca20a18010c-housecall-v1-api

Endpoints for managing job details, including scheduling, status updates, and retrieving job information.

```APIDOC
## Jobs API

### Description
Manage all aspects of job scheduling, execution, and completion. This includes retrieving job details, updating statuses, and accessing associated information.

### Endpoints
- `GET /v1/jobs`: Retrieve a list of jobs.
- `POST /v1/jobs`: Create a new job.
- `GET /v1/jobs/{id}`: Retrieve a specific job by ID.
- `PUT /v1/jobs/{id}`: Update a specific job by ID.
- `GET /v1/jobs/{id}/appointments`: Retrieve appointments for a specific job.
```

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

### Estimates API

Source: https://docs.housecallpro.com/docs/housecall-public-api/a4ca20a18010c-housecall-v1-api

Endpoints for managing estimates, including creating, retrieving, updating, and converting estimates to jobs.

```APIDOC
## Estimates API

### Description
Manage estimates for potential jobs. This API allows for the creation, retrieval, updating, and conversion of estimates into jobs.

### Endpoints
- `GET /v1/estimates`: Retrieve a list of estimates.
- `POST /v1/estimates`: Create a new estimate.
- `GET /v1/estimates/{id}`: Retrieve a specific estimate by ID.
- `PUT /v1/estimates/{id}`: Update a specific estimate by ID.
- `POST /v1/estimates/{id}/convert-to-job`: Convert an estimate to a job.
```

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

### API Key Authentication

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

Use an API Key for authentication when utilizing Housecall Pro's matching algorithm to find service providers. The API key should be included in the Authorization header.

```APIDOC
## API Key Authentication

### Description
Use an API Key for authentication when utilizing Housecall Pro's matching algorithm to find service providers. The API key should be included in the Authorization header.

### Method
Not Applicable (Header-based authentication)

### Endpoint
Not Applicable (Header-based authentication)

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - `Token YOUR_API_KEY`

### Request Example
```
Authorization: Token 0046421dc0ba47ec87bef0c089415380
```

### Response
N/A (Authentication is handled via header)

### Error Handling
If you receive an authentication error, please send your cURL command to jobinbox@housecallpro.com for investigation.
```

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

### Specify Location Context with X-Company-Id Header

Source: https://docs.housecallpro.com/docs/housecall-public-api/4c64fe617d191-multi-location-enabled-ap-is

When making requests to supported endpoints, include the 'X-Company-Id' header with the desired location ID. This header determines which location's data the request will apply to, enabling targeted data management across different company locations. This method replaces the older 'location_ids' parameter for more consistent behavior.

```HTTP
X-Company-Id: ce348586-c67a-4d5b-812f-9480514f84f2
```

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

### Refresh OAuth 2.0 Access Token

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

This cURL command demonstrates how to use a refresh token to obtain a new OAuth 2.0 access token when the current one has expired. It requires your client ID, client secret, refresh token, and 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": "refresh_token", \
  "refresh_token": "the_refresh_token_value_goes_here", \
  "redirect_uri": "CALLBACK_URL" \
}'
```

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

### Request OAuth 2.0 Access Token

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

This cURL command is used to request an OAuth 2.0 access token and refresh token after completing the authorization code flow. It requires your client ID, client secret, authorization code, and 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" \
}'
```