Overview:
This integration utilizes the most complex JSON. It allows for the highest level of customization including dynamically switching between project types. This requires a high level of technical expertise to properly configure. For a simplier payloads, please see our Standard Website Integration page.
Prerequisites:
- Your website must be able to send a webhook (an automatic message) to our system. The message must include all lead information in valid JSON format with the header Content-Type: application/json.
- Your websites JSON must fit the JSON schema outlined in this doc.
- Your website must dynamically add the Supermove Project Type and Job Type to the inbound payload.
How to Enable in Supermove:
- Go to Company Settings in Supermove
- Click Lead Providers (see screenshot above)
- Click the + Add Lead Provider button.
- Select Developer API Integration from the list of known lead providers.
- Add a Name and Description for this Website.
- Note: You can configure multiple developer API endpoints. The names and descriptions allow you tell them apart.
- Click Copy URL. This URL is unique to your company and to your account, all payloads sent to the endpoint will be associated with your Supermove account. No further API keys or organization identifiers are needed.
- Send Payloads to the URL. Please see below for an example payload and detailed information on each key and value.
How to Debug Lead Processing:
Please see Debugging Inbound Leads - Link
Overall Structure:
Warning: this doc is long and very technical. It is intended as a reference doc for developers working to integrate leads.
{
"project_type": "local-move",
"salesperson": {
"email": "office@supermove.test"
},
"coordinator": {
"email": "office@supermove.test"
},
"client": {
"name": "project client",
"notes": "project client notes",
"primary_contact": {
"full_name": "project client contact",
"email": "client@supermove.test",
"phone_number": "4152223333"
}
},
"billing_client": {
"name": "billing client",
"notes": "billing client notes",
"primary_contact": {
"full_name": "billing client contact",
"email": "billing@supermove.test",
"phone_number": "4155556666"
}
},
"jobs": [
{
"job_type": "local-move-move",
"locations": [
{
"address": "1 Market St.",
"city": "San Francisco",
"zip_code": "94105",
"unit": "A",
"floor_number": 3,
"notes": "Long walk",
"has_elevator": true,
"has_long_walk": true,
"stair_count": 2,
"stair_description": "Steep stairs",
"elevator_reservation_time": "10:00AM",
"state": "CA",
"country": "US"
},
{
"address": "1 Ferry Building",
"city": "San Francisco",
"zip_code": "94105",
"unit": "B",
"floor_number": 2,
"notes": "Short walk",
"has_elevator": false,
"has_long_walk": false,
"stair_count": 3,
"stair_description": "Big stairs",
"elevator_reservation_time": "12:00PM",
"state": "CA",
"country": "US"
}
],
"values": {
"JOB_NUMBER_OF_MOVERS_OVERRIDE": 9,
"JOB_NUMBER_OF_TRUCKS_OVERRIDE": 10,
"JOB_MIN_ESTIMATE_HOURS_OVERRIDE": 100,
"JOB_MAX_ESTIMATE_HOURS_OVERRIDE": 200,
"JOB_HOUR_MINIMUM": 9999
},
"tags": [
"HEAVY_LIFTING"
],
"name": "job 1 name",
"description": "job 1 description",
"date": "2025-01-01",
"start_time_1": "0900",
"start_time_2": "1900",
"additional_notes": "job 1 crew notes",
"dispatch_notes": "job 1 dispatch notes",
"office_notes": "job 1 office notes",
"note_to_customer": "job 1 note to customer",
"note_from_customer": "job 1 note from customer"
}
],
"values": {
"PROJECT_SIZE": "Studio"
},
"tags": [
"PREVIOUS_CLIENT"
],
"name": "project name",
"is_test": false,
"description": "project description",
"referral_source": "project referral source",
"referral_details": "project referral details",
"milestones": [
{
"kind": "LEAD_CREATED",
"timestamp": "2025-01-01T10:00:00Z",
"referrer_url": "https://google.com",
"utm_campaign": "moving-services",
"utm_medium": "cpc",
"utm_source": "google",
"utm_content": "ad1",
"utm_term": "local movers",
"ad_kind": "GOOGLE_ADS",
"ad_click_id": "gclid123456",
"ad_cost": 250
}
],
"survey": {...}, //Must conform to Survey Information outlined here.
}
Note: All fields are optional unless otherwise stated in the description.
| Property | Data Type | Description |
| "project_type" | string | Required - Must correspond to the projects types configured in your Supermove account. Please see Accessing Your Project And Job Type Identifiers for more information. |
| "salesperson" | object | Please see Salesperson and Coordinator Object section below. |
| "coordinator" | object | Please see Salesperson and Coordinator Object section below. |
| "client" | object | Required - Please see Client and Billing Client Object section below. |
| "billing_client" | object | Please see Client and Billing Client Object section below. |
| "jobs" | array of jobs objects | Please see Job Object section below. |
| "values" | object | Important - Values in the overall object must correspond to you project billing variables configured in your Supermove account. Payloads with un-configured values will be rejected. Please see Values Object section below for more information |
| "tags" | array of strings | Important - Must correspond to the project tags configured in your Supermove account. Payloads with un-configured tags will be rejected. |
| "name" | string | The name for the project. |
| "is_test" | boolean | Will default to false if omitted. Set to true for test data. |
| "description" | string | The description of the project. |
| "referral_source" | string | Populates the Internal Information -> How Did You Hear About Us? in the Supermove project. |
| "referral_details" | string | Populates the Internal Information -> Referral Details in the Supermove project. |
| "milestones" | array of objects | Array of milestone objects. Please see the below section Milestone Objects for more information. |
| "survey" | object | Important - Must conform Survey specifications found in the Developer API - Survey Information guide. |
Salesperson and Coordinator Object:
{
"email": "office@supermove.test"
}
Note: All fields are optional unless otherwise stated in the description.
| Property | Data Type | Description |
| string | Required - email of the coordinator or salesperson |
Client and Billing Client Object:
Note: client and billing client follow the same format. billing client is completely optional.
{
"name": "project client",
"notes": "project client notes",
"primary_contact": {
"full_name": "project client contact",
"email": "client@supermove.test",
"phone_number": "4152223333"
}
}
Note: All fields are optional unless otherwise stated in the description.
| Property | Data Type | Description |
| "name" | string | Required - email of the coordinator or salesperson |
| "notes" | string | Any notes about the specific client of billing client |
| "primary_contact" | object | Please see Primary Contact Object section below. |
Primary Contact Object:
{
"full_name": "project client contact",
"email": "client@supermove.test",
"phone_number": "4152223333"
}
Note: All fields are optional unless otherwise stated in the description.
| Property | Data Type | Description |
| "full_name" | string | Required - Please combine first and last name if collected separately. This often mirrors the name in the client and billing client objects. |
| "email" | string | email of client |
| "phone_number" | string | Important - must conform to US/Canadian phone format. Must have be a 10 digit number and must have a valid 3 digit area code. Payloads without these will be rejected. |
Job Object:
{
"job_type": "local-move-move",
"locations": [
{
"address": "1 Market St.",
"city": "San Francisco",
"zip_code": "94105",
"unit": "A",
"floor_number": 3,
"notes": "Long walk",
"has_elevator": true,
"has_long_walk": true,
"stair_count": 2,
"stair_description": "Steep stairs",
"elevator_reservation_time": "10:00AM",
"state": "CA",
"country": "US"
},
{
"address": "1 Ferry Building",
"city": "San Francisco",
"zip_code": "94105",
"unit": "B",
"floor_number": 2,
"notes": "Short walk",
"has_elevator": false,
"has_long_walk": false,
"stair_count": 3,
"stair_description": "Big stairs",
"elevator_reservation_time": "12:00PM",
"state": "CA",
"country": "US"
}
],
"values": {
"JOB_NUMBER_OF_MOVERS_OVERRIDE": 9,
"JOB_NUMBER_OF_TRUCKS_OVERRIDE": 10,
"JOB_MIN_ESTIMATE_HOURS_OVERRIDE": 100,
"JOB_MAX_ESTIMATE_HOURS_OVERRIDE": 200,
"JOB_HOUR_MINIMUM": 9999
},
"tags": [
"HEAVY_LIFTING"
],
"name": "job 1 name",
"description": "job 1 description",
"date": "2025-01-01",
"start_time_1": "0900",
"start_time_2": "1900",
"additional_notes": "job 1 crew notes",
"dispatch_notes": "job 1 dispatch notes",
"office_notes": "job 1 office notes",
"note_to_customer": "job 1 note to customer",
"note_from_customer": "job 1 note from customer"
}
Note: All fields are optional unless otherwise stated in the description.
| Property | Data Type | Description |
| "job_type" | string | Required - Must correspond to the job type identifier configured in your Supermove account. Please see Accessing Your Project And Job Type Identifiers for more information. |
| "locations" | Array of Objects | Required - Must have at least one location object in the array. Please see Location Object section below. |
| "values" | object | Important - Values in the job object must correspond to you job billing variables configured in your Supermove account. Payloads with un-configured values will be rejected. Please see Values Object section below for more information. |
| "tags" | array of strings | Important - Must correspond to the job tags configured in your Supermove account. Payloads with un-configured tags will be rejected. |
| "name" | string | The name of the job. |
| "description" | string | Free form description of the job. |
| "date" | string | Important - must be in YYYY-MM-DD format. |
| "start_time_1" | string | Must be in HHMM format. |
| "start_time_2" | string | Must be in HHMM format. |
| "additional_notes" | string | Free form string. These are translated into the Crew Notes within Supermove. |
| "dispatch_notes" | string | Free form notes for the dispatch. |
| "office_notes" | string | Free form notes, will populate in the Supermove project in the Job Details |
| "notes_to_customer" | string | Free form notes for the customer. |
| "notes_from_customer" | string | Free form notes from the customer. |
Location Object:
{
"address": "1 Ferry Building",
"city": "San Francisco",
"zip_code": "94105",
"unit": "B",
"floor_number": 2,
"notes": "Short walk",
"has_elevator": false,
"has_long_walk": false,
"stair_count": 3,
"state": "CA",
"country": "US"
}
Note: All fields are optional unless otherwise stated in the description.
| Property | Data Type | Description |
| "address" | string | Required - Address must be supplied for each location object. Can be the street address, full address including state and zip, or zip code alone. We use Google to validate the input address. Any location that is searchable in Google will work. |
| "city" | string | |
| "zip_code" | string | |
| "unit" | string | |
| "floor_number" | integer | |
| "notes" | string | Free form notes about the location |
| "has_elevator" | boolean | |
| "has_long_walk" | boolean | |
| "stair_count" | integer | |
| "state" | string | |
| "country" | string |
Values Object:
The value object is a a free form object of key/value pairs. Each Key must be a configured billing variable properly configured for your job or project. Each value must be what you want the values set to. This is an advanced feature. Please contact your implementation specialist or customer success manager for assistance if struggling to configure these appropriately.
Milestones Object:
{
"kind": "LEAD_CREATED",
"timestamp": "2025-01-01T10:00:00Z",
"referrer_url": "https://google.com",
"utm_campaign": "moving-services",
"utm_medium": "cpc",
"utm_source": "google",
"utm_content": "ad1",
"utm_term": "local movers",
"ad_kind": "GOOGLE_ADS",
"ad_click_id": "gclid123456",
"ad_cost": 250
}
Note: All fields are optional unless otherwise stated in the description.
| Property | Data Type | Description |
| "kind" | string | Required - Each milestone requires a type. "FIRST_TOUCH", "LAST_TOUCH", and "LEAD_CREATED" are currently supported. |
| "timestamp" | string | Important - must conform to UTC string formatting standards. Will be rejected if it does not conform. This is the current timestamp of when the lead is created. |
| "referrer_url" | string |
The url which referred this lead. |
| "utm_campaign" | string |
The UTM campaign name that this lead associated with. |
| "utm_source" | string |
The UTM source that this lead is associated with. |
| "utm_content" | string |
The UTM content that this lead is associated with. |
| "utm_term" | string |
The UTM term that this lead is associated with. |
| "ad_kind" | string |
Important - Must be either "GOOGLE_ADS" or "FACEBOOK". If not one of these two values, the lead will be rejected. |
| "ad_click_id" | string |
The click ID associated with this lead. |
| "ad_cost" | integer |
The cost of this lead/conversion. |
Comments
0 comments
Please sign in to leave a comment.