AffinityLive provides a robust, extensible interface that can allow you to build forms on your website and when users submit them, the data is submitted directly into AffinityLive.

Endpoints

AffinityLive currently provides three Form API endpoints. More endpoints will be added in the future for areas like support issues, requests and leads. The current endpoints are:

• Company - https://yourdomain.affinitylive.com/forms/public/company - this endpoint creates everything you need to create a new account, including the company, contact, contact details (affiliation) and even address information. See the table below for available and required fields.
• Contact - https://yourdomain.affinitylive.com/forms/public/contact - this endpoint creates everything you need to create a new contact, including the contact, their details (affiliation) and even address information. See the table below for available and required fields.
• Prospect - https://yourdomain.affinitylive.com/forms/public/prospect - this endpoint creates everything you need to create a new prospect or sales opportunity, including the company/account, contact, contact details (affiliation) and even address information. See the table below for available and required fields.

Requirements

There are a few general requirements to all forms submitted to AffinityLive, which are detailed below.

reCAPTCHA

For security, all forms connecting to AffinityLive require a ReCaptcha field. For more information on how to add one of these fields to your form, read the documentation at http://www.google.com/recaptcha.

For AffinityLive forms, you need to use the following key so that AffinityLive can decode the response and confirm it is right.

AffinityLive reCAPTCHA Key: 6Lf4bMQSAAAAAJQNMg6QOB71CVCjM1OkAYkQ7d0_

If you don't enter a reCAPTCHA field, or the user submits the value incorrectly, AffinityLive will show an additional reCAPTCHA field, however, this will be branded as an AffinityLive page, rather than looking like your website.

Redirect

While submitting forms straight from your website to AffinityLive is convenient for both you and your users, we also appreciate that you want to have a professional presentation that makes it look like they never left your website. To achieve this, you need to provide a "redirect" value, which we will use to send the user to a thankyou/confirmation screen of your choice.

The syntax for the redirect is:

<input type="hidden" name="redirect" value="http://your.website.here.com/and/the/page.html"/>

Notifications

AffinityLive can optionally be configured to create a diary entry, sent by the person who entered the form, and sent to one or more users. With these hidden notification settings you can select who to send the notification to, what to set the subject as, and what to set the body as. 

Multiple notifications can be sent to different people containing different information; to multiple notifications, simply use different unique KEYWORD values.

An example of the fields follows:

<input type="hidden" name="diary_send_KEYWORD" value="contact"/> or <input type="hidden" name="diary_send_KEYWORD" value="prospect"/>

Note that the only two supported values are currently "contact" and "prospect".

<input type="hidden" name="diary_to_KEYWORD" value="staff_NUMBER"/> or <input type="hidden" name="diary_to_KEYWORD" value="group_NUMBER"/>

The value of the "to" fields is the internal ID of a staff member or group in AffinityLive. You can supply multiple values by duplicating the whole input string; you can NOT join the "to" values together with a comma separated list.

<input type="hidden" name="diary_cc_KEYWORD" value="person@acme.com"/>

The CC field can contain any valid email address, but take care not to send emails to people who aren't expecting to recieve them or your account will be suspended as per our Terms of Use. Note that if you want to include multiple email addresses, you will want to comma separate the list of addresses, such as "person1@acme.com,person2@acme.com" for the "value" of the hidden input.

<input type="hidden" name="diary_subject_KEYWORD" value="New website signup!"/>

The Subject keyword allows you to specify a subject for the notification email. If you don't provide a subject, the default subject will be "New web form submission via AffinityLive".

<input type="hidden" name="diary_body_KEYWORD" value="A new contact has signed up through the website! Pop the champagne!!!"/>

The Body keyword allows you to specify a subject for the notification email. If you don't provide a subject, the default subject will be "A new submission has been made via the web form".

Fields

The following table of fields is what you need to call your form inputs for them to appear in AffinityLive. All fields are optional unless designated as "Required" or "N/A" (for not applicable).

Field Name	Description	Contact	Company	Prospect
company_name	A string value, the name of the company		Required
company_website	A string value, the web address of the company. Include http:// as part of your string
company_status_id	The internal ID of the company status
contact_firstname	The firstname of this contact	Required	Required	Required
contact.surname	The surname of this contact	Required	Required	Required
contact_status_id	The internal ID of the contact status.
contact_title	A string value, such as Mr or Mrs.
contact_dob	The date of birth for the contact, in the format of 1980-01-01
affiliation_phone	The phone number of this contact
affiliation_fax	The fax number of this contact
affiliation_email	The email address of this contact
affiliation_mobile	The mobile or cell phone number of this contact
affiliation_title	A string value, such as "CEO" or "HR Manager"
country_name	The full name of the country, or its ISO 3166-1 abbreviation (eg, US, AU)
state_name	The full name of the state or provence, or its ISO 3166-2 abbreviation (eg, CA, NSW)
country_id	The internal ID of the country object in your AffinityLive location database
state_id	The internal ID of the state object in your AffinityLive location database
address_street1	A string for the first street address field
address_street2	A string for the second street address field
address_city	A string for the city value
address_postcode	A string for the postal code or zipcode
prospect_title	A string for the title of the prospect/opportunity in AffinityLive	N/A	N/A
prospect_type_id	A string for the prospect/opportunity type.	N/A	N/A	Required
prospect_status_id	A string for the status to set the prospect/opportunity to be on creation.	N/A	N/A	Required
prospect_due	A date value in the format of YYYY-MM-DD HH:MM:SS (time optional) for when the prospect is due	N/A	N/A
prospect_weighting	An integer value between 0 and 5 for how hot the deal is	N/A	N/A
prospect_value	A decimal value for the prospect/opportunity	N/A	N/A
prospect_comments	A text field for comments on the opportunity.	N/A	N/A

Custom Fields

One of the powerful features of AffinityLive is the ability to extend the structure of records through profile and extension fields as well as segmentations (for company, contact & affiliations).

To save these values into AffinityLive, you need to follow one of the following formats.

Profile Fields

Storing profile fields requires you to build a form input with a name in three parts, joined by an underscore. The three parts are:

 

1. The profile keyword. This tells the Forms API that you're passing in a profile field.
2. The type of object, being contact, affiliation, company or prospect.
3. The ID or title of the profile field. You can see this by putting your mouse over the hyperlink where you'd edit the profile field, or if the profile field is a single word, you can use the title of the profile field.

 

<input type="text" name="profile_OBJECT_ID" value="" />

OR

<select type="text" name="profile_OBJECT_ID"><option value="male">Male</option><option value="female">Female</option></select>

Note that in the second example, you'll need to make sure your <option> values match the values you have in your AffinityLive profile fields (for select types). 

Extensions

Storing extension fields requires you to build a form input with a name in three parts, joined by an underscore. The three parts are:

1. The extension keyword. This tells the Forms API that you're passing in an extension field.
2. The type of object, being prospect.
3. The ID or title of the extension field. You can see this by putting your mouse over the hyperlink where you'd edit the extension field, or if the extension field is a single word, you can use the title of the extension field.

<input type="text" name="extension_OBJECT_ID" value="" />

OR

<select type="text" name="extension_OBJECT_ID"><option value="male">Male</option><option value="female">Female</option></select>

Note that in the second example, you'll need to make sure your <option> values match the values you have in your AffinityLive extension fields (for select types).

Segmentations

Linking a company, contact or affiliation to a particular segmentation category requires you to build a form input with a name in three parts, joined by an underscore. The three parts are:

1. The segmentation keyword. This tells the Forms API that you're passing in an extension field.
2. The type of object, being contact, affiliation or company.
3. The ID or title of the segmentation value. You can see this by putting your mouse over the hyperlink where you'd edit the segmentation field, or if the segmentation field is a single word, you can use the title of the segmentation field.

<input type="text" name="segmentation_OBJECT_ID" value="" />

OR

<select type="text" name="segmentation_OBJECT_ID"><option value="male">Male</option><option value="female">Female</option></select>

Note that in the second example, you'll need to make sure your <option> values match the values you have in your AffinityLive extension fields (for select types).

File Attachments

You can also upload files through your form. To successfully upload the file, make sure you're using the enctype on the <form> tag, as defined below.

<form action="https://yourdomain.affinitylive.com" method="POST" enctype="multipart/form-data">

You can have multiple file uploads in a single form. The format for file uploads is as follows:

<input type="file" name="attachment_FOLDERNAME">

When a file is uploaded, it will be put into the folder called FOLDERNAME.

Note that files will be attached to the following objects, in order of priority:

 

• Prospect - if a prospect is created, the attachment will go against the prospect object.
• Company - if there is no prospect created, the attachment will go against the company object.
• Contact - if there is no contact created, the attachment will go against the contact object.