APIs » Form APIs » Request Forms API

Request Forms API

The Request Forms API allows you to create a form which, when submitted, will result in Accelo creating a Company record, a Contact record and an Affiliation (which stored details like email address and phone number) record and then creating a Request of the defined Type against the Company/Contact.

The Request Forms API will also send notification emails and autoreplies based on the rules defined for that particular Request Type.

Endpoint

To use this endpoint, your form needs to POST the form fields to https://yourdomain.accelo.com/forms/public/request.

Fields

The fields supported by this endpoint are listed below; note that those designated with a * are required fields:

Field Name

Example/Default

Notes

request_type_id*

1

The ID of the Request Type. You can see the ID in the address bar in your browser when you are editing the Request Type in the Accelo configuration area. This needs to be a valid integer and the request type needs to be active for the Request Forms API to work.

request_title*

Computer Offline

This is the title of the request, treated similarly to the way the subject in an email is treated. If a request comes in from the same contact with the same title as an existing open request we'll adjust the title by adding the current timestamp (in UTC) to it so the titles remain unique.

company_name*

Acme Inc

The name of the company

contact_firstname*

Steve

The firstname of the contact

contact_surname*

Jones

The lastname (known as surname in places where color is spelled colour)

request_body

Something is wrong with my computer!

This is a string (with support for newlines) of arbitrary length which acts like the body for requests that are created via email.

request_status

pending (default)

While we'll default to creating a request as "pending", you could (if you really wanted) set the status to be "open" or "closed".

owner_table

affiliation (default) or
staff

This allows you to specify who is actually filling in the form. By default, Accelo assumes the affiliation (contact) is the one filling in the form, but if you want to have an intranet style system where staff members are filling in a form on behalf of a client, you can set the owner_table to be staff and specify the ID of the staff member (in owner_id below) to make it clear the request was written by a staff user.

owner_id

(integer)

Only used in conjunction with the owner_table field above to designate that the request (and any activities that are being sent) are coming from a staff member.

company_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".

company_status_id

(integer)

The status_id (which is the custom status you're able to create/give a company 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.

company_website

www.acme.com

The domain of the company website.

company_comments or company_notes

Website Signup

This is the "comments" field under a company, and can be an arbitrary string of your choice. We respect newlines, so it can be quite long and involved if you want it to.

company_phone

(415) 555-1234

For accounts that have "Show Company Phone" enabled, this will store the phone number for the company overall.

company_fax

(415) 555-1234

For accounts that have "Show Company Phone" enabled, this will store the fax number for the company overall.

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_company_IDENTIFIER

Accounting

See our Categories & Custom Fields page for details about using Category Form Fields.

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_company_IDENTIFIER

Western Region

See our Categories & Custom Fields page for details about using Profile 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 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: www.accelo.com/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.

De-Duplication & Data Integrity

Our API will attempt to find (ie, not create) an existing Company, Contact and Affiliation if the combination of Company Name, Contact Firstname, Contact Lastname and Affiliation Email address all match an existing record in your Accelo account at the time the form is processed. This means that Steve Jones from Acme with an email address sjones@acme.com will be found if the inputs all match, but if Steve enter's his company name as "Acme Inc" we will create a whole new Company, Contact and Affiliation.

If a request comes in from the same contact with the same title as an existing open request we'll adjust the title by adding the current timestamp (in UTC) to it so the titles remain unique.

If Accelo does find an existing record, the system will not overwrite any data that exists on the record (eg, company or 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.

Accelo uses cookies to give you the best possible experience - by clicking 'Continue' you agree to our use of cookies. Refer to our Privacy Policy for details. Continue