This guide will show you how to integrate a new or existing HTML form or third-party lead source with your SmartMoving account. Once complete, new submissions will be added as new leads automatically.
Format
Leads may be submitted to the SmartMoving Lead API in JSON format. The exact format is shown in the example below.
The JSON payload should be submitted via HTTP POST to the following endpoint:
Note that the HTTP POST request must have a “Content-type: application/json” header.
in the end point provided above you will need to enter the provider key for your company. Your Provider key can be found by navigating to Settings -> Sales -> Lead Providers -> Your Website. Once at the Your Website option select, View Instructions.
A popup window will present allowing you to copy the provider key for your company.
Supported Fields
SmartMoving supports the following fields. Only the name fields are required. You can submit either “FirstName” and “LastName,” or submit a single “FullName,” but not both.
Customer Information
Note: Only those with marked with an * are required
FirstName * - Required only if FullName is not specified.
LastName * - Required only if FullName is not specified.
FullName * - Required only if FirstName and LastName are not specified.
PhoneNumber - The contact phone number
UserOptIn - Recommended if collecting phone numbers for texting purposes.
Extension - The contact phone extension
PhoneType - Optional, but if specified, must be one of these values: Mobile, Home, Office, Other
Email
Move Information
MoveDate The expected date of the move in YYYYMMDD format, such as “20190501” for May 1st, 2019.
Bedrooms - String describing the number of bedrooms.
MoveSize - The size of the move. This should match a value from your SmartMoving Move Size settings. If a MoveSize is specified that does not match an existing value, a new Move Size will be automatically added.
Notes - This can be any other string value.
ReferralSource - See below for more information
BranchId - This can be the SmartMoving ID for a branch. Branch IDs can be retrieved in your SmartMoving settings.
ServiceType - The type of service requested. Valid values are: Moving; Packing; MovingAndPacking; LoadOnly; UnloadOnly; Commercial; StorageInBound; StorageOutBound; InnerHouse; JunkRemoval; LaborOnly
Origin
** Pass either the individual components OR the Full Address but not both
OriginStreet - The Street portion of the origin address
OriginCity - The City portion of the origin address
OriginState - The State portion of the origin address
OriginZip - The Postal Code portion of the origin address
OR
OriginAddressFull - Only pass this value if you are not passing in the other origin components.
Destination
** Pass either the individual components OR the Full Address but not both
DestinationStreet - The Street portion of the destination address
DestinationCity - The City portion of the destination address
DestinationState - The State portion of the destination address
DestinationZip - The Postal Code portion of the destination address
OR
DestinationAddressFull - Only pass this value if you are not passing in the other destination components.
JSON Sample
The data should look like the following:
{
"firstName": "John Smith",
"lastName": "Dummy",
"fullName": null,
"phoneNumber": "555-555-5555",
"extension": "",
"userOptIn": "true",
"email": "[email protected]",
"moveDate": "7/25/2020",
"leadCost": 12.50,
"originStreet": "123 Main Street",
"originCity": "Dallas",
"originState": "TX",
"originZip": "75208",
"destinationStreet": "",
"destinationCity": "",
"destinationState": "",
"destinationZip": "",
"bedrooms": "5 rooms",
"notes": "We need moving and packing",
"customField": "This is a custom field"
}
Note that each property is at the "root" of the object in the JSON payload.
Custom Fields
You may also pass fields to SmartMoving that are not defined in the list above. These custom fields will be added to the “Notes” section of the lead that is created.
For example, if you wish to pass in the number of floors for the origin, you could add “OriginNumberOfFloors” with a field value of “2,” and SmartMoving will automatically capture this information as part of the note.
Referral Source
You may optionally pass in a referral source. For example, if your form allows the user to select a referral source, such as “Google” or “Word of Mouth,” you may pass this value in the “ReferralSource” field.
Note that the value passed should exactly match the description of a referral source in your SmartMoving settings. If it does not, a new referral source record will be added in SmartMoving automatically. Referral sources can be configured in your SmartMoving Settings -> Sales -> Referral Sources
We strongly recommend restricting the values users may select from. If you allow them to specify a referral source as “free-text,” you will end up with a large number of referral sources in SmartMoving.
If you do not specify the “ReferralSource” field, the new lead in SmartMoving will show “Your Website” as its referral source.
UTM Fields
If your company wants to track more from your paid ads, you can optionally include UTM fields in your form. We support the following UTM fields:
UtmAdGroup: Identifies the ad group within a campaign for more granular performance analysis.
UtmCampaign: Specifies the marketing campaign name to track the overall performance of that campaign.
UtmContent: Helps differentiate ads or links that point to the same URL but have different content.
UtmCustom Tracking: Allows for tracking custom parameters specific to your marketing needs, not covered by standard UTM parameters.
UtmKeyword: Indicates the keywords for this ad or content, used mainly in paid search campaigns.
UtmMedium: Describes the marketing medium used, such as email, social, cpc, etc., to identify how visitors are getting to your site.
UtmSource: Specifies the source of the traffic, such as a search engine, newsletter, or other referral.
Sending Leads to a Specific Branch
If you wish for a particular form's leads to always be associated to a specific branch in SmartMoving, you can append that branch's ID to the endpoint URL. Example:
https://api.smartmoving.com/api/leads/from-provider/v2?providerKey={provider_key}&branchId={branchId}
For more information about retrieving your branch IDs, please refer to this article on categorizing leads by branch ID.
Best Practice: Email Copies of Submissions
We strongly recommend that you have your form sent to you via Email in addition to posting to the SmartMoving API. This ensures that you will still receive a copy of any leads even if there is a communication problem between your website and SmartMoving.
In the event that you suspect there is a communication problem, please contact SmartMoving support immediately.
Handling Errors
The lead provider submission API may return an error. Your form should handle errors and allow the user to resubmit the form. We also strongly recommend that you have some sort of notification sent to you so that you’ll know there was an issue submitting the form.
There is one common error you should handle: duplicate submissions. SmartMoving will automatically reject duplicate submissions by returning an HTTP 400 response with the following error message: "This lead has already been submitted. Please contact SmartMoving support". We recommend informing the user that their information has already been received should the API return this error.
Sample Form with jQuery
A sample implementation can be found here: https://codepen.io/anon/pen/NoXdwj