Skip to main content

ArcSite & Housecall Pro

Updated today

This guide explains how to connect ArcSite to Housecall Pro (HCP), automatically create ArcSite Projects from HCP Estimates, and push ArcSite Drawing outputs (PDF + line items) back into HCP.

This step-by-step guide is designed for operational, non-technical users.

1. Setup

1.1 Prerequisites

Before you begin, confirm the following:

  1. Active ArcSite account

    1. You can sign in to ArcSite Web.

    2. You are in the correct ArcSite company/organization where projects should be created.

  2. Active Housecall Pro (HCP) account

    1. You can sign in to HCP.

    2. You can access the company that will send webhooks and receive ArcSite pushes.

  3. Required permissions

    1. In HCP, you can:

      1. Create / manage API keys (or “tokens”) for API access.

      2. Create / edit Webhooks (including setting a webhook secret).

      3. View Estimates, Options, and edit Option line items.

      4. Upload attachments to Estimate Options.

    2. In ArcSite, you can:

      1. Manage Integrations / App connections for your company.

      2. Choose a Default Project Owner.

      3. Create projects, or have permissions that allow ArcSite to create projects on your behalf.

  4. Data hygiene recommendation (important for Sales Rep matching)

    1. The employees assigned to an HCP Estimate should have email addresses.

    2. To ensure employees are automatically added as collaborators, their HCP email addresses must match active user emails in the same ArcSite company.

1.2 Generating an API Key in HCP (do this first)

ArcSite uses an HCP API key to:

  • Validate the connection

  • Retrieve company information

  • Read Estimates and Options

  • Update Option line items

  • Upload drawing PDF attachments to an Option

  1. In Housecall Pro, navigate to the Apps → Integrations App

  2. Create a new API key. Generate new API key with Full-access Permission.

  3. Ensure the API key has permissions to:

    1. Read company information (ArcSite reads /company during setup)

    2. Read customers (ArcSite validates the key by reading /customers)

    3. Read estimates (ArcSite reads /estimates/{estimate_id})

    4. Update estimate option line items (bulk update)

    5. Upload attachments to estimate options (PDF uploads)

  4. Copy the API key and keep it secure.

1.3 Configuring Webhooks in HCP (required for project creation)

ArcSite creates a Project automatically when HCP notifies ArcSite that an Estimate has been scheduled.

  1. In Housecall Pro, navigate to the Webhook App page.

  2. Create a new webhook with these settings:

    1. Activate the Webhook App.

    2. Enter the Webhook URL (ArcSite endpoint): https://user.arcsite.com/user/service/housecall_pro/webhooks/

    3. Webhook Secret (Signing Secret):

      1. Copy the Signing Secret. You will paste the exact same value into ArcSite during connection.

  3. Enable the required event(s):

    1. Estimate scheduled event:

      1. The event name used by this integration is estimate.scheduled.

  4. Save the changes by clicking the Save button at the bottom of the page.

Why webhooks are required:

  1. ArcSite Project creation is triggered only by the HCP webhook event estimate.scheduled.

  2. Without this webhook, ArcSite will not automatically create Projects from HCP Estimates.

Technical note (for troubleshooting):

  1. HCP signs webhook requests using HMAC-SHA256 with your webhook secret.

  2. ArcSite expects these headers from HCP:

    1. Api-Timestamp

    2. Api-Signature

  3. If webhook delivery fails, the most common cause is a secret mismatch between HCP and ArcSite.

1.4 Connecting ArcSite to HCP (paste API Key + Webhook Secret)

You initiate the connection from ArcSite, after you have prepared the HCP API Key and Webhook Secret.

  1. In ArcSite Web, go to:

    1. Settings → Integrations → Housecall Pro

      • If you do not see Housecall Pro, you may not have the required permission. Ask your ArcSite admin.

  2. Paste the required information:

    1. Paste the HCP API Key

    2. Paste the Webhook Secret (must match the webhook secret configured in HCP)

  3. Save / Connect.

  4. What you should expect after a successful connection:

    1. ArcSite shows the integration as Connected.

    2. ArcSite stores your HCP Company ID and Company Name (retrieved from HCP automatically).

1.5 Validating the connection (what ArcSite checks)

  1. In ArcSite Web → Settings → Integrations → Housecall Pro:

    1. ArcSite validates the API key by making a lightweight API request to HCP.

    2. ArcSite fetches HCP Company information and stores:

      1. Company ID

      2. Company Name

  2. Common connection errors and how to resolve them:

    1. “The API Key is invalid”

      1. Regenerate the key in HCP and paste the new key in ArcSite.

    2. “The API Key does not have permission”

      1. Ensure the key has access to Estimates / Options / attachments.

    3. Webhook signature errors later (during project creation)

      1. Double-check the webhook secret matches exactly on both sides (HCP webhook and ArcSite integration screen).

1.6 Default Project Owner Setting (Important)

ArcSite needs a default person to “own” new Projects created automatically from HCP webhooks.

  1. What “Default Project Owner” means

    1. It is the ArcSite user who will be set as the Project Owner for Projects created from HCP estimate.scheduled events.

  2. When it is used

    1. Every time ArcSite receives an HCP estimate.scheduled webhook and creates a new Project.

2. Workflow

2.1 Scheduling an Estimate in HCP (what triggers ArcSite project creation)

ArcSite creates the Project when the Estimate is scheduled in HCP.

  1. In Housecall Pro, create an Estimate for the customer.

  2. Add/confirm required customer/job data:

    1. Customer first name and last name

    2. Customer email (recommended)

    3. Service address (street, city, state, zip)

  3. Assign employees (strongly recommended):

    1. Add one or more Assigned Employees to the Estimate.

    2. Ensure each assigned employee has an email in HCP.

    3. Best practice: those emails should match ArcSite user emails in your ArcSite company.

  4. Schedule the Estimate.

    1. When scheduled, HCP sends the webhook event estimate.scheduled to ArcSite.

You can schedule an Estimate in Estimate Detail Page:

Or in the Pipeline table:

2.2 Automatic ArcSite Project Creation

This step is automatic after the HCP webhook is configured and working.

  1. What happens automatically:

    1. HCP sends estimate.scheduled to ArcSite.

    2. ArcSite creates a new Project.

    3. ArcSite links the Project to the HCP Estimate ID internally.

  2. What users should expect to see in ArcSite:

    1. A new Project appears in ArcSite (typically within minutes).

    2. The Project owner is the configured Default Project Owner.

  3. Duplicate prevention:

    1. If an ArcSite Project already exists for the same HCP Estimate, ArcSite will not create another one.

2.3 Project Naming Rules

ArcSite generates the Project name from the scheduled HCP Estimate.

  1. Naming format:

    1. Estimate # {estimate_number} - {customer_name} - {address_street}

  2. Fields used from HCP:

    1. estimate.estimate_number

    2. estimate.customer.first_name + estimate.customer.last_name

    3. estimate.address.street

  3. Notes / limitations:

    1. If a field is missing, ArcSite omits that part.

    2. If all parts are missing, ArcSite uses a generic name: HCP Estimate.

2.4 Project Profile Mapping (HCP → ArcSite)

When the Project is created, ArcSite maps HCP fields into the ArcSite Project Profile.

  1. Mapping behavior:

    1. Customer and address fields are copied into the ArcSite Project’s client profile.

    2. “Support contact” fields are populated from the first assigned employee (if any).

  2. Optional mapping table:

ArcSite Project Profile Field

Source in HCP Estimate payload

Client name

customer.first_name + customer.last_name

Client email

customer.email

Phone

customer.mobile_number (fallback: home_number)

Second phone

customer.work_number

Street

address.street

City

address.city

State

address.state

ZIP

address.zip

Support name

First item in assigned_employees: first_name + last_name

Support email

First item in assigned_employees: email

Support phone

First item in assigned_employees: phone

2.5 Sales Rep and Collaborator Assignment Logic

ArcSite uses HCP “Assigned Employees” to add collaborators to the ArcSite Project.

  1. Matching method:

    1. ArcSite takes the list of assigned_employees from the HCP Estimate payload.

    2. ArcSite extracts their email values.

    3. ArcSite searches for active ArcSite users within the same ArcSite company with matching emails.

  2. What happens when there is a match:

    1. Each matched user is added to the Project as a Collaborator.

    2. If at least one match succeeds:

      1. The first matched ArcSite user becomes the Project’s “Support contact” in ArcSite (support name/email/phone are updated to match the ArcSite user record).

      2. This does not change the Project Owner (the owner stays as the Default Project Owner).

  3. What happens when there is no match:

    1. The Project is still created.

    2. No collaborators are added for missing/unmatched emails.

    3. Support contact remains:

      1. Set from HCP first assigned employee fields (if present), but not linked to an ArcSite user; or

      2. Blank, if no assigned employees were provided.

  4. Common causes of missing matches:

    1. Assigned employee has no email in HCP.

    2. Assigned employee email does not match the ArcSite user’s email.

    3. The ArcSite user exists but is not active or not in the same ArcSite company.

2.6 Creating Drawings in ArcSite

  1. Open the automatically created Project in ArcSite.

  2. Create or update Drawings in the Project:

    1. Add measurements and takeoffs as needed.

    2. Ensure products and custom price items are correctly set up, if you want them pushed as line items.

  3. Prepare content for export/push:

    1. Confirm the drawing version is ready to be exported (the push is version-aware for PDF uploads).

2.7 Pushing Drawings and Line Items to HCP

In the ArcSite App, trigger the push by clicking “Yes” on the pop-up that asks, “Do you want to push this proposal to Housecall Pro?”

ScreenRecording_02-09-2026 14-29-32_1.MP4

ArcSite pushes data to HCP from ArcSite during the export flow.

  1. Where the push action happens in ArcSite:

    1. In the Project, export your Proposal / output.

    2. During export, ArcSite will trigger the Housecall Pro push for the drawing version being exported.

  2. What data is pushed to HCP:

    1. Drawing PDF uploaded as an attachment to an HCP Estimate Option

    3. Line Items written into the same HCP Estimate Option, including:

      1. Products from the ArcSite takeoff

      2. Custom price items (if used in ArcSite)

      3. Markup (as separate line item(s) if used in ArcSite)

      4. Discounts (as separate line item(s) if used in ArcSite)

      5. Tax (as a separate “Tax” line item if used in ArcSite)

  3. Important behavior:

    1. The push targets an Estimate Option inside the linked HCP Estimate.

    2. Option selection rules are critical and explained in the next section.

  4. Line item update behavior (important):

    1. ArcSite updates line items using a bulk replace strategy (it replaces the option’s line items with ArcSite-generated line items).

    2. If ArcSite generates no line items for the drawing, ArcSite does not modify existing HCP line items for that option.

2.8 Estimate Option Selection Logic (Critical)

ArcSite must choose which HCP Estimate Option to write to. This selection has strict rules.

  1. First push for a Project (no previous record):

    1. ArcSite retrieves the HCP Estimate’s Options.

    2. ArcSite sorts options by create time.

    3. ArcSite selects the earliest created option.

  2. Later pushes for the same Project:

    1. ArcSite re-uses the same Option ID that was used previously for that Project.

  3. Approval / availability rules:

    1. ArcSite will push only if the selected option’s approval_status is:

      1. empty / not set

      2. expired

      This means that options with any status prior to 'Approved' are available for the push (e.g., Schedule, OMW, Finish, Send, etc.).

    2. If the selected option has any other approval status (for example, pending or approved), ArcSite will block the push.

  4. Operational implications (read carefully):

    1. You cannot manually choose a different option in ArcSite for the first push.

    2. If the earliest created option is not editable, the push will fail until you fix the option situation in HCP.

    3. If an option is deleted in HCP between pushes, ArcSite automatically recovers by selecting a new available option.

  5. Recommended setup to avoid first-push failures:

    1. In HCP, ensure the earliest created option in the Estimate is the one you want ArcSite to update.

    2. Ensure that option is not approved (editable) at the time of the first push.

    3. Ensure the Estimate has at least one available option before pushing (ArcSite cannot push without an option).

Basically, most push errors related to an Option’s status can be resolved by creating a new Option on the Estimate in HCP.

Currently, ArcSite will automatically fall back to the newly created Option if there are no other existing Options available.

Currently, because there is no API support for creating an Option, ArcSite uses an automatic fallback to another available Option to complete the push. This may result in overwriting data in an existing Option.

Therefore, unless it’s necessary, we recommend not deleting Options in HCP that have already been pushed from ArcSite.

2.9 Drawing Version Behavior (prevents duplicate uploads)

ArcSite treats Drawing PDF uploads as “version-aware.”

  1. When a new drawing version is exported:

    1. ArcSite uploads the PDF again as a new attachment in HCP.

  2. When the same drawing version is exported again:

    1. ArcSite will not upload the same PDF attachment again.

    2. This prevents duplicate attachments for repeated exports of the same drawing version.

  3. What to expect in HCP:

    1. Over time, you may see multiple attachments for the same drawing if you export multiple versions.

2.10 Push Error Handling

If a push fails, ArcSite stops the push and shows an error to the user.

  1. How errors are displayed:

    1. ArcSite will show an error during the export/push flow (exact UI depends on your ArcSite version).

  2. Common error scenarios and recommended actions:

    1. No option found in HCP Estimate

      1. In HCP, create at least one option in the Estimate, then retry the export/push.

    2. Option cannot be updated because it is not editable

      1. In HCP, ensure the selected option is editable (approval status empty or expired or Completed), or adjust the Estimate’s options so the earliest created option is editable.

    3. Option deleted / not found

      1. Verify the Estimate still exists and the option still exists in HCP.

    4. API key invalid / permission error

      1. Regenerate the API key in HCP and update it in ArcSite.

    5. File too large

      1. Reduce the drawing export size if possible, or split content across drawings.

    6. Rate limit / temporary HCP API issues

      1. Wait and try again later.

3. FAQ & Key Behaviors

3.1 How Markup Is Handled

  1. Markup is pushed as separate line item(s) in HCP.

  2. ArcSite splits markup into:

    1. A taxable markup line item (if applicable)

    2. A non-taxable markup line item (if applicable)

  3. Why this approach is used:

    1. HCP line items are the most reliable, auditable way to represent markup in the option total.

3.2 How Tax Is Handled

  1. Tax is pushed as a separate “Tax” line item in HCP.

  2. Tax behavior:

    1. ArcSite respects taxable vs non-taxable logic from ArcSite products and pricing.

    2. The “Tax” line item is non-taxable (it represents the tax amount itself).

  3. Alignment with HCP tax calculations:

    1. ArcSite sends the tax amount as a line item rather than expecting HCP to recalculate it.

3.3 Can Approved Estimates / Options Be Updated?

  1. ArcSite will not update an option that is already approved (or otherwise not editable).

  2. ArcSite push is allowed only when the selected option approval status is:

    1. empty / not set, or

    2. expired

    This means that options with any status prior to 'Approved' are available for the push (e.g., Schedule, OMW, Finish, Send, etc.).

  3. If you need to push updates after approval:

    1. Create a new editable option in HCP before first pushing (and ensure it will be the earliest created option for first push scenarios), or

    2. Use HCP workflows to make an option editable again, if supported by HCP.

3.4 What Happens If Assigned Employees Are Missing?

  1. ArcSite will still create the Project (as long as the webhook event is received and valid).

  2. No collaborators will be added automatically.

  3. The support contact fields may remain blank.

  4. The Project Owner will be the configured Default Project Owner.

3.5 Common Questions & Edge Cases

Duplicate pushes

  1. Drawing PDF

    1. The same drawing version is uploaded only once.

    2. New versions are uploaded again (as new attachments).

  2. Line items

    1. ArcSite uses a bulk update strategy to keep HCP line items synchronized.

    2. During a push, the option’s existing line items are replaced by the new line items generated in ArcSite (when ArcSite has line items to send).

    3. If ArcSite generates no line items, ArcSite does not change existing HCP line items.

Missing data

  1. Missing customer name/address fields may result in a shorter project name.

  2. Missing assigned employee emails prevent collaborator auto-assignment.

Partial configurations

  1. API key connected but webhook not configured:

    1. ArcSite will not auto-create projects (because it never receives estimate.scheduled).

  2. Webhook configured but secret does not match:

    1. ArcSite will reject the webhook (project will not be created).

Multiple drawings in one ArcSite Project (important limitation)

  1. Current behavior:

    1. All drawings inside the same ArcSite Project push to the same HCP Estimate Option.

  2. Result:

    1. Pushing from one drawing can overwrite the option line items from a previous push of another drawing.

  3. Recommended operational best practice:

    1. If you need separate options per drawing, use separate projects/estimates until HCP provides an API for option creation that enables one-drawing-to-one-option behavior.

Precision Loss in Line Item Pricing (Edge Case)

When does this occur?

In most cases, pricing precision is maintained accurately. However, precision loss may occur when a product's unit price in ArcSite has more than 2 decimal places (e.g., $0.045 per unit) combined with a large quantity.

Why does this happen?

This is due to Housecall Pro API limitations in how it processes sub-cent unit prices:

  • ArcSite calculates and sends: unit_price = 4.5 cents (for $0.045)

  • HCP's system processes this as: unit_price = 4 cents (truncating the decimal)

  • With quantity = 240:

    • Expected total: 4.5 cents × 240 = 1,080 cents = $10.80

    • Actual total in HCP: 4 cents × 240 = 960 cents = $9.60

    • Difference: $1.20 (11% error)

Recommendation:

To avoid precision loss:

  1. Use unit prices with 2 or fewer decimal places (e.g., $0.05 instead of $0.045)

  2. If you need granular pricing, adjust the quantity or bundling rather than using very low per-unit prices

  3. Review pushed line items in HCP after export to verify totals match expectations

Related Articles
ArcSite + JobNimbus
ArcSite + Quickbooks
ArcSite + Zoho CRM
ArcSite + Jobber
ArcSite + ServiceTitan
Did this answer your question?