Project Forms API

APIs

Project Forms API

The Project 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 Project (or Job) of the defined Type and the defined Status against the Company/Contact.

Endpoint

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

Fields

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

Field Name	Example/Default	Notes
job_type_id*	1	The ID of the Project Type. You can see the ID in the address bar in your browser when you are editing the Project Type in the Accelo configuration area. This needs to be a valid integer and the request type needs to be active for the Project Forms API to work.
job_status_id*	1	The ID of the Project Status to use on creation. You can see the ID of Status in the far right column listing all of the Statuses visible from the bottom of the Project "Progressions & Fields" section.
job_title*	Important Project for Acme	This is the title of the Project.
company_name* OR company_id OR affiliation_id	Acme Inc	The name of the company. An alternative to providing the name is to provide an existing company_id or affiliation_id (see note on existing IDs below for details).
contact_firstname* OR contact_id OR affiliation_id	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* OR contact_id OR affiliation_id	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).
job_description		This is an arbitrary length string (with support for newlines) which describes the project.
job_manager_id	2	The ID of the Accelo user who is assigned as the project owner. If you don't pass anything in the Project will remain unassigned.
job_rate_charged	150.00	The rate per hour that the project should use as its default charge-out rate. Can be overridden on a per-milestone basis.
job_rate_id	1	The internal ID of the charge out rate that the project should use as its default charge-out rate. Can be overridden on a per-milestone basis. Passing in -1 (ie, negative 1) will use staff rates.
job_is_billable	yes/no	Whether the project is designed to be billable (and have a financial value) or not (just hours).
job_template_id	1	The ID of the project template object you want to apply to this job. Note that using a template with a lot of milestones and tasks will result in a longer "save" time when the form is submitted.
job_fixed_price or job_budget_defined_price_subtotal	5000.00	A decimal for the fixed price of the project. IGNORED IF A job_template_id IS PROVIDED.
job_budget_service_time	36000	The number of seconds that the project has for its budget in time. For 10 hours of project budget, multiply by 3600 to get the number of seconds. IGNORED IF A job_template_id IS PROVIDED.
job_budget_include_material	yes/no	A yes or no string value for whether any fixed price budget for the project should include the value of any materials added later, or whether these materials are billed on-top of the fixed price budget. IGNORED IF A job_template_id IS PROVIDED.
job_budget_include_expense	yes/no	A yes or no string value for whether any fixed price budget for the project should include the value of any expenses added later, or whether these expenses are billed on-top of the fixed price budget. IGNORED IF A job_template_id IS PROVIDED.
milestone_N_title	First Milestone	The title of a milestone. The N value is an integer, starting with 1. Note that only top-level milestones are supported at this time. NB: if you don't provide a title for a milestone, all milestone information will be ignored.
milestone_N_status_id	1 - Pending 2 - Active 3 - Paused 4 - Complete 5 - Inactive	The ID for the status of the milestone (defaults to 1). Note that you should only pass the number value, not the word.
milestone_N_manager_id	2	The built-in ID of the staff member who is the manager for the milestone. If you don't provide a value the milestone will remain unassigned.
milestone_N_rate_id	6	The internal ID of the charge out rate that the project should use as its default charge-out rate. Can be overridden on a per-milestone basis. Passing in -1 (ie, negative 1) will use staff rates.
milestone_N_rate_charged	150	The rate per hour that the milestone should use as its charge-out rate.
milestone_N_is_billable	yes/no	A yes or no string value for whether this milestone is billable or not.
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.
extension_job_IDENTIFIER	Server	See our Categories & Custom Fields page for details about using Extension Form Fields.
Activities	See our Creating & Sending Activities page for details.
Attachments	See our Uploading Attachments page for details.

A note on company_id, 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.

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 Ticket comes in from the same contact with the same title as an existing open Ticket 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.