The Contact Forms API allows you to create a form which, when submitted, will result in Accelo creating a Contact record and an Affiliation (which stored details like email address and phone number) record.
Endpoint
To use this endpoint, your form needs to POST the form fields to https://yourdomain.accelo.com/forms/public/contact.
Fields
The fields supported by this endpoint are listed below; note that those designated with a * are required fields:
|
Field Name |
Example/Default |
Notes |
|
contact_firstname* |
Steve |
The firstname of the contact. An alternative to providing the name is to provide an existing contact_id or affiliation_id (see note on existing IDs below for details). |
|
contact_surname* |
Jones |
The lastname (known as surname in places where color is spelled colour). An alternative to providing the name is to provide an existing contact_id or affiliation_id (see note on existing IDs below for details). |
|
contact_status |
active |
Options include active (default), interested, prospect and inactive. If inactive is selected, they will be hidden by search and list screens unless the user chooses "show inactive". |
|
contact_status_id |
(integer) |
The status_id (which is the custom status you're able to create/give a contact in Accelo); if you don't pass it we'll set it to be the first custom status (by ordering) that has start=yes set on it. |
|
contact_title |
Mr |
This is the personal title of the contact, also known as Salutation or Prefix of their name. |
|
contact_username |
steve_jones |
This is a string; if you don't provide it, we will randomly assign them a unique username. If you assign one that has been taken by another contact, we will append random digits to it to ensure it is unique. |
|
contact_password |
secretword |
This is a string, which we will then encrypt with a one-way cypher and store. |
|
contact_comments or contact_notes |
First Web Contact |
This is a string which will appear in the "Comments" section on the left of the Contact view screen. |
|
affiliation_email |
sjones@acme.com |
The email address of the person filling in the form; while optional, this field is highly recommended. |
|
affiliation_phone |
(415) 555-1234 |
The phone number of the contact as linked to the company. |
|
affiliation_fax |
(415) 555-1234 |
The fax number of the contact as linked to the company. |
|
affiliation_mobile |
(415) 555-1234 |
The mobile/cell phone number of the contact as linked to the company. |
|
affiliation_title |
CEO |
The position title of the person filling in the form. |
|
address_street1 |
530 Howard St |
The street address of the contact. |
|
address_street2 |
Suite 200 |
The secondary street address of the contact. |
|
address_city |
San Francisco |
The city for the address to create on the affiliation/contact. The address_city field is required if you want to save any address details. |
|
address_postcode |
94105 |
The postcode (also known as a zipcode) of the address you want to create. |
|
address_state_id or address_state_name |
California |
The ID of the state in your Accelo deployment, the abbreviation of the state in your account (eg CA for California) or the full name of the state. If we do not find a match in your Accelo account, we will not create the state (we don't want random website users who can't spell their state name making your important lookup fields dirty). |
|
address_country_id or address_country_name |
US |
If you do not want to rely on guessing the location of the submitted by IP address (see below), you can specify the state as a field. The ID of the country in your Accelo deployment, the ISO 3166 country code or the full name of the countrty. If we do not find a match in your Accelo account, we will not create the country (we don't want random website users who can't spell their country name making your important lookup fields dirty). |
|
category_contact_IDENTIFIER |
Male |
See our Categories & Custom Fields page for details about using Category Form Fields. |
|
category_affiliation_IDENTIFIER |
Executive/VP |
See our Categories & Custom Fields page for details about using Category Form Fields. |
|
profile_contact_IDENTIFIER |
Football |
See our Categories & Custom Fields page for details about using Profile Form Fields. |
|
profile_affiliation_IDENTIFIER |
Red |
See our Categories & Custom Fields page for details about using Profile Form Fields. |
|
Activities |
See our Creating & Sending Activities page for details. |
|
|
Attachments |
See our Uploading Attachments page for details. |
|
A note on contact_id or affiliation_id
If you already know the identity of the company, contact or affiliation in your Accelo account, you can bypass the required name fields by providing the ID only if the ID actually matches a object in the Accelo account. For security reasons, any value provided through the Forms API will only update an existing record if the value of the record in the Accelo account is empty/not set - the Forms API will not overwrite existing records.
A note on guessing the Country
Guessing the Country information based on a person's IP address is normally fairly reliable, and is better in many ways than having to ask users for this information in long drop down lists or requiring them to spell things properly. If you provide an address_city value in your form (which is what we use to decide if you want to save an address, since a city value is compulsory for an address), and if you do not provide state and country information that matches the values already in your Accelo account, we will use the IP address of the person submitting the form to guess their Country.
Example
The best way to see an example is to use View Source on our Example forms page: https://www.accelo.com/_resources/app/dev/forms.html. The source code has plenty of comments and advice, and you can enter your own deployment name and actually test pushing form values into your own deployment.
Data Integrity
If Accelo does find an existing record, the system will not overwrite any data that exists on the record (eg, contact data you already have stored) with the inputs from the Forms API - this is to ensure that a malicious external user doesn't go around wiping out or corrupting your data.
Note also that the Forms API will not provide any feedback to the submitter that an existing record was found - this is so we don't disclose any information about who is already in your database.