API documentation

HTTP POST API

Nutshell offers an alternative, minimal HTTP POST API for users that need to add entities to Nutshell using a simple form. It is much less powerful than the JSON-RPC API. The POST API can only add contacts, accounts, or leads to Nutshell and cannot retrieve, edit, or delete any data.

Every request sent to the POST API will generate one lead, and potentially one contact and one account.

Create a new API key (from the Setup tab, click "API") with Form submissions + Wufoo permission. Note that this API key has no privileges for the JSON-RPC APIs. You will receive a URL that accepts POSTs with the potential field names below. The only mandatory field is at least one subfield for either an account or contact, and the successUrl key.

This API is intended for clients hosting a simple form on a static server with no capability for a more powerful JSON-RPC. As such, the only possible response to a POST API request is a HTTP 301 redirect to the successUrl provided in your form.

If provided, source, product, competitor, and industry names must exactly match the name of an entity already present in Nutshell. Contacts, accounts, and leads are the only new entities that will be created from HTTP POSTs.

If invalid data is received in this request, it is saved as a note on the lead for manual review.

After a lead arrives in Nutshell via the POST API, it is subject to standard process and user assignment, as defined in Lead Distribution. Submissions with the isPending parameter set to a true value will be created in a pending state.

Available Fields

The following fields are available for use in the HTTP POST API:

account[name]
account[industryName]
account[email]
account[phone]
account[url]
account[tags]
account[address][address_1]
account[address][address_2]
account[address][address_3]
account[address][city]
account[address][state]
account[address][postal_code]
account[address][country]

contact[name]
contact[title] (requires an account to be submitted simultaneously)
contact[email]
contact[phone]
contact[url]
contact[tags]
contact[address][address_1]
contact[address][address_2]
contact[address][address_3]
contact[address][city]
contact[address][state]
contact[address][postal_code]
contact[address][country]

source[name]

market[name]

product[name]
product[quantity]

competitor[name]

confidence
note
isPending
tags

successUrl

The tags, contact[tags], and account[tags] fields should consist of a comma-seperated list of tag names, e.g. "tag #1,tag #2".

Custom fields

The POST API will also populate custom fields, if the fields are named the same.

Custom fields are available for leads, contacts, and accounts. Given a custom field called "flavor" in each of those fields, the syntax is

contact[flavor]
account[flavor]
flavor

The latter entry will go into the leads field named "flavor".

Sample form

This form will create a new lead, with an account (using information from Company name & Company email fields) and contact (using the Your name field). If the submitter doesn't include their name, no contact will be created. If the comments box is filled out, it will be attached to the lead as a note.

In this example, a product and source will be attached to the new lead. Note that the product and source must have been created in advance. A favorite flavor will be given to the contact; note that the custom field must have been created in advance.

<form action="https://app01.nutshell.com/YOUR_URL_HERE" method="post">

<!-- these URLs are where the submitter will be redirected upon completion -->
<input name="successUrl" value="http://EXAMPLE.COM/thanks.html" type="hidden">

Company name: 
<input name="account[name]" type="text"> <br>

Company email: 
<input name="account[email]" type="text"> <br>

Your name:
<input name="contact[name]" type="text"> <br>

<!-- This custom lead field must already exist in Nutshell -->
Your favorite flavor:
<!-- <input name="contact[flavor]" type="text"> <br> -->

<textarea name="note" placeholder="Comments"></textarea>

<input name="ok" value="Submit" type="submit">

<!-- This product must already exist in Nutshell -->
<!-- <input name="product[name]" value="Widget" type="hidden">  uncomment when you've configured this product -->

<!-- This source must already exist in Nutshell -->
<!-- <input name="source[name]" value="Web form" type="hidden"> uncomment when you've configured this source -->

<!-- This market must already exist in Nutshell -->
<!-- <input name="market[name]" value="U.K." type="hidden"> uncomment when you've configured this market -->

</form>