Overview

What is this? The Create Customer API lets you automatically send customer information from your website, CRM, or lead platform directly into SubcontractorHub — creating both a customer record and a proposal in one step.

Why does it matter? Instead of manually typing in every new lead, this API does it for you. When a customer fills out a form on your website or gets captured in another system, their info flows straight into SubcontractorHub. No copy-pasting, no missed leads, no delays.

📌 What's an API? An API (Application Programming Interface) is like a messenger that carries information between two software systems. Think of it as an automatic bridge — when a lead comes in on one side, the API delivers it to SubcontractorHub on the other side, without anyone needing to manually enter data.

Prerequisites

Before you begin, make sure you have:

✅ Your SubcontractorHub Public API Key (contact your Account Manager if you don't have one)
✅ A developer or tech partner who can set up the API connection on your website or CRM
✅ The customer fields you want to send (name, email, address, job type, etc.)

Step-by-Step Instructions

Step 1: Get Your API Key

Contact your SubcontractorHub Account Manager to receive your Public API Key. This key is like a password that proves your system is authorized to send data.

Step 2: Set Up the API Connection

Share these details with your developer or tech partner:

URL: https://api.virtualsaleportal.com/api/public/create-customer
Method: POST
Header: Accept: application/json

Step 3: Map Your Customer Fields

Here's what information you can send. Fields marked Required must be included:

Field	Required?	What It Is
public_api_key	✅ Yes	Your authentication API key
external_id	✅ Yes	The customer ID from your other system (helps avoid duplicates)
source	✅ Yes	Where the lead came from (e.g., "Website", "Referral", "Door Knock")
first_name	✅ Yes	Customer's first name
last_name	Optional	Customer's last name
email	✅ Yes	Customer's email address
phone	Optional	Customer's phone number
street	✅ Yes	Street address
city	✅ Yes	City
state	✅ Yes	State (2-letter abbreviation, e.g., "CA", "TX")
postal_code	✅ Yes	ZIP code
country	Optional	Country (defaults to US)
job_type	✅ Yes	Type of project: Solar, Roof, HVAC, Fence, or Battery
owner email	✅ Yes	Email of the sales rep who should own this lead

Step 4: Send a Test Request

Have your developer send a test request with sample data. Here's an example of what the data looks like:

{
  " public_api_key": "YOUR_API_KEY",
  " customer": {
    " territory": "Bay Area CA",
    " street": "123 Main Street",
    " state": "CA",
    " source": "Website Lead Form",
    " postal_code": "94102",
    " phone": "555-123-4567",
    " last_name": "Johnson",
    " job_type": "Solar",
    " first_name": "Mike",
    " external_id": "LEAD-001",
    " email": " mike.johnson@email.com",
    " country": "US",
    " city": "San Francisco"
  },
  " owner": {
    " email": " sarah.rep@yourcompany.com"
  }
}

Step 5: Verify in SubcontractorHub

After sending the test, log into SubcontractorHub and check: - The new customer appears in your Customers tab - A proposal has been automatically created for them - The lead is assigned to the correct sales rep

💡 Pro Tip: Use a consistent naming convention for your source field (like "Website", "Google Ads", "Referral"). This makes it easy to track where your best leads come from in SubcontractorHub reports.

Real-World Example

Scenario: Tom's Roofing & Solar has a website where homeowners request free estimates. Before the API, Tom's office manager spent 2 hours every morning copying leads from the website into SubcontractorHub.

After connecting the Create Customer API, every new web form submission automatically creates a customer and proposal in SubcontractorHub — assigned to the right sales rep based on territory. Tom's team now responds to leads within minutes instead of hours, and they've stopped losing leads that fell through the cracks.

Troubleshooting / FAQ

Problem	Solution
Getting an "unauthorized" error	Double-check your API key. Contact your Account Manager if it's not working.
Owner email error	The owner email must belong to an existing user in your SubcontractorHub account. Verify the email is correct.
Customer not showing up	Make sure all required fields are included. Check that the `job_type` is one of: Solar, Roof, HVAC, Fence, or Battery.
Duplicate customers appearing	Use unique `external_id` values for each customer to prevent duplicates.

Change Log Summary

What Changed	Details
Title	Changed from "Create Customer API" to benefit-oriented title
Language	Added plain-English explanation of what an API is; removed raw technical formatting
Structure	Organized into clear steps with a field reference table
Added	Prerequisites, real-world example, troubleshooting table, pro tip, sample payload with comments
Format	Made field requirements scannable with table format; bold key terms

Original Article ID: 11698543 · Category: Starter Guide · Priority Topic: APIs

Create Customer Api