Skip to content

Your website

Form integration

How a Gravity Forms, WPForms or Contact Form 7 submission on your WordPress site becomes a HaulHQ lead, which field labels the plugin recognises, and the REST endpoint for any other form builder.

This applies to both workflows

What are the two workflows?

There is no setting to turn on

Once the plugin is connected with your API key, every submission from a Gravity Forms, WPForms or Contact Form 7 form on the site is sent to HaulHQ as a lead. Nothing to enable, no form to pick. What you control is the labels on your fields, because that is how the plugin knows which answer is the phone number.

What a submission becomes

The plugin reads each field's label (for Contact Form 7, the form-tag name), matches it against the list below, and posts a lead with the source detail set to the form that sent it (gravity-forms-7, wpforms-3, cf7-42). Matching ignores case, spacing, hyphens, underscores, a trailing * or :, and "(required)", so Full Name, full-name and full_name * are all the same label.

BecomesLabels the plugin recognisesNotes
Contact namename, full name, your name, your-name, contact name, customer nameA single whole-name field wins over first + last.
Contact name (first half)first name, firstJoined with the last name when there is no whole-name field.
Contact name (second half)last name, surname, lastEither half alone still names the lead.
Phonephone, your phone, your-phone, contact phone, tel, telephone, phone number, your phone number, mobile, mobile number, cell, cell phone, best number, best phone number, contact numberA phone or an email is required, or the submission is not sent.
Emailemail, e-mail, your email, your-email, contact email, email address, your email addressA phone or an email is required, or the submission is not sent.
Addressaddress, your address, your-address, street address, service address, job address, pickup address, property address, locationGeocoded for the dispatch map when present.
Zip codezip, zip code, zipcode, postal code, your zipThe first five-digit run is used; "85701-1234" works.
Items / descriptionmessage, your message, your-message, description, details, items, comments, notes, job details, project details, what do you need removed, what needs to go, tell us about the job, how can we help, additional detailsShown as the job description on the lead.

A phone or an email is required

A submission that maps to neither a phone nor an email is not sent, because nobody could act on it. The plugin writes one line to the PHP error log naming the labels it received, so a developer can see which label did not match. A submission with one of the two is always sent.

Fields the plugin does not recognise are not thrown away. They are added to the lead's notes under an "Other form fields" heading, each with its own label, so a form that asks for a "Gate code" or a "Preferred day" still delivers the answer to the person doing the job.

Gravity Forms

  1. 1Open the form in Forms > Edit and check each field's Field Label against the table above. "Phone Number", "Email Address" and "Full Name" all work.
  2. 2The advanced Name field (first and last boxes) works as one name. A Paragraph Text field labelled "What do you need removed?" becomes the item description.
  3. 3Submit a test from the live page with your own phone number. In HaulHQ, open Leads: the new row shows the source gravity-forms- followed by the form ID.

WPForms

  1. 1Open the form in WPForms > All Forms and check each field's Label. Required markers are fine; "Phone Number *" matches.
  2. 2Use separate First Name and Last Name fields, or one Name field. Either way the lead gets a full name.
  3. 3Submit a test and look for wpforms- followed by the form ID under Leads in HaulHQ.

Contact Form 7

  1. 1Contact Form 7 has no labels the plugin can see; it uses the name inside each form tag, such as [tel* your-phone]. The stock form's your-name, your-email and your-message already match.
  2. 2For a phone field, add [tel your-phone] (or name it phone). For an address, [text your-address]. Any name from the table works.
  3. 3Submit a test and look for cf7- followed by the form ID under Leads in HaulHQ. Other tags, such as your-subject, arrive in the lead's notes.

Any other form builder: the REST endpoint

The plugin registers POST /wp-json/haulhq/v1/lead on your site. It takes a JSON body whose keys are field labels, matched with the same table, and it needs no authentication: it is meant to be called from a page on the same site. Your developer's form posts to it and the plugin forwards the lead using your API key, which never leaves the server.

fetch('/wp-json/haulhq/v1/lead', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ 'Full Name': 'Dana Ortiz', 'Phone Number': '520-555-0100', 'Service Address': '12 Camino Real, Tucson', 'What do you need removed': 'Old couch and a fridge', haulhq_hp: '' // honeypot: leave empty }) })

A minimal call from a page on the site

  • Honeypot. Include a field named haulhq_hp (or website_url, or hp_field) and keep it empty and hidden. A filled honeypot gets a success-shaped reply and no lead is created, so bots move on.
  • Rate limit. 10 submissions per IP address per 10 minutes; the next one gets HTTP 429. A request carrying a valid WordPress REST nonce (X-WP-Nonce header, action wp_rest) is exempt. Absent or stale nonces are tolerated on purpose, because page caches hand stale nonces to anonymous visitors.
  • Replies. HTTP 201 with the new lead's id; 400 with an error when the email is malformed or when no phone or email was found (the reply lists the labels it received); 500 when HaulHQ itself could not be reached.

Common mistakes

"The lead arrived but the phone number is blank."

The phone field's label is not one the plugin knows. Look in the lead's notes under "Other form fields": the number is there, with the label you used. Rename the field to one from the table (or have a developer add yours through the haulhq_field_mapping filter) and it fills the phone field from then on.

"Test submissions never show up in HaulHQ."

First check the form has a phone or an email field the plugin recognises; a submission with neither is not sent, and the reason is one line in the site's PHP error log. Then check Settings > HaulHQ shows a green Connection Status; a plugin that is not connected cannot send anything.

"Why does a lead from my contact form have no price tier?"

Because a contact form is a plain lead, not a quote. Load size, instant pricing and photos come from the HaulHQ quote form ([haulhq_form]), which knows your pricing. A Gravity Forms or WPForms submission gives you a name, a way to reach them, and whatever they typed; you quote from there.

"HaulHQ has bot protection, so my WordPress form is protected too."

It is not, and today HaulHQ's Turnstile gate is switched off. If it is switched on later, a WordPress form that renders no Turnstile challenge would be refused by it; the plugin forwards a token when the page posts one (cf-turnstile-response), which is how a form would pass. Until then, the plugin's own honeypot and rate limit are what stand between the REST endpoint and spam, and Gravity Forms, WPForms and Contact Form 7 bring their own anti-spam.