developers API Documentation

PipelineDeals provides a very easy way of creating leads from a web site form. PipelineDeals will process a form that sits on your website and redirect the user to a thank you page that you provide when they hit the submit button.

Setting up the form

Setting up your form requires you to simply ensure that you are using the correct field names that PipelineDeals is looking for.

PipelineDeals will process the form, then redirect the user back to a thank you page of your choosing.

To ensure that PipelineDeals processes your form correctly, you'll need to set your <form> tag correctly.

<form method="post" action="https://app.pipelinedeals.com/web_lead">
...
</form>

Inside your form, please follow the naming conventions supplied in the table below.

Developer Mode

For Web-to-Leads, you can turn on developer mode to ensure that your web form will work correctly and is free of errors.

To enable developer mode, insert the following code inside your form:

<input type="hidden" name="developer_mode" value="true">

PipelineDeals Naming Conventions

Name Required? Default Description
developer_mode No false developer_mode is useful to turn on when you are creating your form. When you submit the form, it will take you to a special page that will list information, like whether the lead is valid, your w2lid, etc.
thank_you_page No the referring URL thank_you_page is the full URL of your thank you page after the user submits the form. It is not necessarily required, but definitely recommended. If you do not fill out a thank_you_page (and developer_mode is off, PipelineDeals will redirect the user back to the referring URL.
prevent_duplicates No false prevent_duplicates can be used to prevent creation of duplicated leads in the system. Duplicates are matched on email fields, so if any lead is found with email matching any emails provided through the form, the lead will not be created. Instead, a new note containing data from form will be created for duplicate lead found and owner will be notified by email about the situation.
w2lid YES None This is your w2lid that you can find in Admin -> Web to Leads. It is used to uniquely identify the user to use when using Web-to-Leads.

Important Note: The w2lid is required. If you do not provide a w2lid and developer_mode is turned off, we will refer you back with ?invalid_w2lid=true. Otherwise you will see the error if developer mode is on.

assign_to_id No the user who owns the w2lid, or round-robin between team members Assign this lead to a specific user in your account. You can find user ids here. Note: If using a manager's w2lid, leads will be round-robined among members of that manager's team unless assign_to_id is set. Using assign_to_id will override round-robin functionality and ensure lead is directly assigned to owner of the assign_to_id.
todo_template No the name of a todo template to apply Apply this lead template to the new lead. If the template does not match any of your todo templates, it is ignored.
merge_multi_select No false Merge custom fields of 'multi_select' or 'Picklist' field type with existing data.
notify No Not defined Whether to notify the person assigned to the new lead. 'none' will disable the notification. 'link-only' will send only the link.
notification_ignore No Not defined A comma separated list of fields to ignore when sending the notification.
lead[lead_source] No "Web to Lead" The lead source name of this lead. If not set, it will default to "Web to Lead".
lead[lead_status] No None The lead status name of this lead. If not set, it will default to None. The lead status names can be viewed or set in Admin -> Lead Statuses.
lead[last_name] No "None provided" The last name of the incoming lead.
lead[full_name] No None If you set this, PipelineDeals will try to parse the user's full name (firstname lastname)
lead[first_name] No None The first name of the incoming lead.
lead[position] No None The position (job title) of the incoming lead.
lead[phone] No None The primary phone number of the incoming lead.
lead[fax] No None The fax number of the incoming lead.
lead[email] No None The primary email address of the incoming lead.
lead[home_address_1] No None
lead[home_address_2] No None
lead[home_city] No None
lead[home_state] No None
lead[home_postal_code] No None
lead[home_country] No None
lead[home_email] No None
lead[home_phone] No None
lead[summary] No None
lead[work_address_1] No None
lead[work_address_2] No None
lead[work_city] No None
lead[work_state] No None
lead[work_postal_code] No None
lead[work_country] No None
lead[mobile] No None The mobile phone # of the lead.
lead[company_name] No None The company name of the lead.
lead[website] No None The lead's website
lead[custom_fields] No None Store a custom field value on the lead. See below for details on using custom fields.
lead[linked_in_url] No None The Lead's LinkedIn URL.

Using custom fields

To store custom field values with incoming leads, you will need the custom_field_label_id for the person custom field. If you log into your account, all the ids you will need can be found on the person_custom_field_labels page.

You will also need to have the correct format for each custom field type you are storing. The supported custom field label types include:

  • text
  • numeric
  • currency
  • date
  • dropdown
  • multi_select

The details of the format for storing each of these can be found below. In each example, the id value of the custom field is 1234. The general form for storing a custom field value is:

<input name="lead[custom_fields][1234]" type="text">value</input>

Storing "text" custom fields

Storing a "text" custom field is simple. The custom_field_label_id is 1234. Don't confuse the type="text" with the custom field type. This is the HTML input type for a text field.

<input type="text" name="lead[custom_fields][1234]" >Default Value</input>

Storing "numeric" custom fields

To store a "numeric" custom field, the value must be numeric or the web_lead form will fail. If using an HTML input field for a numeric or currency custom field, then you should add a form validation to ensure the value is numeric before allowing submission. This example uses a default value of 500

<input type="text" name="lead[custom_fields][1234]" >500</input>

Storing "currency" custom fields

To store a "currecny" custom field, the value must be numeric or the web_lead form will fail. This example uses a default value of $500 (assuming the currency type is USD). Note the $ is excluded.

<input type="text" name="lead[custom_fields][1234]" >500</input>

Storing "date" custom fields

To store a "date" custom field, the value must be formatted as a date that will parse correctly. We suggest YYYY-MM-DD to avoid date format confusion.

<input type="text" name="lead[custom_fields][1234]" >2013-03-25</input>

Storing "dropdown" custom fields

To store a "dropdown" custom field, the value must be a custom_field_label_dropdown_entry_id that is valid for the dropdown custom field. The valid ids for both "dropdown" and "multi_select" custom fields can also be found from on the person_custom_field_labels page (if you're logged into your account as an admin). Note also that the example below uses a select field instead of text. It would not make sense to have a user type in the id of the value.

<select name="lead[custom_fields][1234]" >
  <option value="54321">Product 1</option>
  <option value="54322">Product 2</option>
</input>

Storing "multi_select" custom fields

To store a "multi_select" custom field, the value must be a custom_field_label_dropdown_entry_id that is valid for the dropdown custom field. The format to store a "multi_select" is slightly different than any of the other field types becasue there can be multiple values. To indicate to PipelineDeals to accept multiple values, an extra "[]" is needed in the "name".

<select name="lead[custom_fields][1234][]" >
  <option value="54321">Product 1</option>
  <option value="54322">Product 2</option>
</input>

Using tags

You can also use tags with the incoming leads to further slice and dice them. You may use up to 10 tags in the form.

Ensure your tags match up with amdin predefined tags. If a tag has been added that is not part of the admin predefined tags, it will be created as an admin predefined tag. Because of this, ensure that you do not leave tags open to any user input.

Simply name the input field tag_<n>, where n is the tag number.

An example of using a tag would be to allow the lead to select a potential product they are interested in.

<select name="tag_1">
  <option value="product1">Product 1</option>
  <option value="product2">Product 2</option>
</select>

Or you can simply add a static tag all the time.

<input type="hidden" name="tag_2" value="Auto Parts"/>

Using notes

You can have up to 10 text areas that will be appended to the lead as notes.

you can set the title of each note by having a hidden field that denotes the note title

<input type="hidden" name="note_title_1" value="How did you hear about us?" />
<textarea name="note_1"></textarea>

Notifications

You can configure the notification that is sent to the person assigned to the new lead.

The following will disable the notification

  <input type="hidden" name="notify" value="none" />

The following will ignore particular fields from being included in the notification.

  <input type="hidden" name="notification_ignore" value="custom_fields_1,custom_label_1,last_name,note_title_1" />

SSL

Although you can call app.pipelinedeals.com/web_lead in non-SSL mode (using http:// instead of https://), it is recommended that you always call the https:// version of the site.

If your form is SSL-enabled and you call the non-SSL version of the site, the user will see a warning when they submit the form.

Form Validation

PipelineDeals does not do any type of form validation. It is up to you to make sure the user fills out all the fields you wish to require.

Lead Assignment

PipelineDeals will automatically assign leads to your teammates using a round-robin method. The w2lid is user-based, so be sure to use the w2lid of a manager if you want to have the leads round robin to the manager's team. If the user provided does not have a team, the leads will be assigned to that user.

A Simple Example:

<html>
  <form method="post" action="https://app.pipelinedeals.com/web_lead">

    <input type="hidden" name="w2lid" value="334lkn43kn5" />
    <input type="hidden" name="thank_you_page" value="http://website.com/thankyou.html" />

    <!-- Basic Demographic Fields -->
    <p><label>Name</label><br/>
    <input type="text" name="lead[full_name]"></p>
    <p><label>Company</label><br/>
    <input type="text" name="lead[company_name]"></p>
    <p><label>Phone</label><br/>
    <input type="text" name="lead[phone]"></p>
    <input type="text" name="lead[fax]"></p>
    <p><label>Email Address</label><br/>
    <input type="text" name="lead[email]"></p>

    <!-- Comments Field -->
    <input type="hidden" name="note_title_1" value="User Comments" />
    <textarea name="note_1"></textarea>

    <input type="submit" value="save" />
  </form>
</html>

A More Complex Example:

<html>
  <form method="post" action="https://app.pipelinedeals.com/web_lead">

    <!-- Required Hidden Fields -->
    <input type="hidden" name="w2lid" value="334lkn43kn5" />
    <input type="hidden" name="thank_you_page" value="http://website.com/thankyou.html" />

    <!-- Basic Demographic Fields -->
    <p><label>Name</label><br/>
    <input type="text" name="lead[full_name]"></p>
    <p><label>Company</label><br/>
    <input type="text" name="lead[company_name]"></p>
    <p><label>Phone</label><br/>
    <input type="text" name="lead[phone]"></p>
    <input type="text" name="lead[fax]"></p>
    <p><label>Email Address</label><br/>
    <input type="text" name="lead[email]"></p>

    <!-- Tags -->
    <p><label>Product</label><br />

    <select name="tag_1">
      <option value="Widget A">Widget A</option>
      <option value="Widget B">Widget B</option>
    </select>

    <!-- Comments Field -->
    <input type="hidden" name="note_title_1" value="User Comments" />
    <textarea name="note_1"></textarea>

    <input type="submit" value="save" />
  </form>
</html>