Contacts records are stored within our system using the email address as the key. A single record per email address is stored per account. Email address and all standard contact fields are stored at the account level. This means that changes to the standard contact fields of an existing contact will be made globally wherever the contact is present. For more information: http://help.alchemer.com/help/article/link/global-vs-campaign-contact-fields.
The following API calls are currently available for the SurveyContact sub-object:
GET LIST - Get a list of all of your contacts for the specified survey and campaign.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/surveycontact
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
| page | page=3 | False |
| resultsperpage | resultsperpage=100 | False |
Response Example (.debug format):
Array
(
[result_ok] => 1
[total_count] => 2
[page] => 1
[total_pages] => 1
[results_per_page] => 50
[data] => Array
(
[0] => Array
(
[id] => 100039753
[email_address] => jon.doe@alchemer.com
[first_name] => Jon
[last_name] => Doe
[organization] =>
[division] =>
[department] =>
[team] =>
[group] =>
[role] =>
[home_phone] =>
[fax_phone] =>
[business_phone] =>
[mobilephone]=>
[mailing_address] =>
[mailing_address2] =>
[mailing_address_city] =>
[mailing_address_state] =>
[mailing_address_country] =>
[mailing_address_postal] =>
[title] => Vice President
[url] =>
[customfield1] => sales
[customfield2] =>
[customfield3] =>
[customfield4] =>
[customfield5] =>
[customfield6] =>
[customfield7] =>
[customfield8] =>
[customfield9] =>
[customfield10] =>
[test] => Success
[test2] =>
[test3] =>
[test4] =>
[test5] =>
[status] => Active
[subscriber_status] => Unsent
[date_last_sent] =>
)
[1] => Array
(
[id] => 100039769
[email_address] => jane.doe@alchemer.com
[first_name] => Jane
[last_name] => Doe
[organization] =>
[division] =>
[department] =>
[team] =>
[group] =>
[role] =>
[home_phone] =>
[fax_phone] =>
[business_phone] =>
[mobilephone]=>
[mailing_address] =>
[mailing_address2] =>
[mailing_address_city] =>
[mailing_address_state] =>
[mailing_address_country] =>
[mailing_address_postal] =>
[title] =>
[url] =>
[customfield1] =>
[customfield2] =>
[customfield3] =>
[customfield4] =>
[customfield5] =>
[customfield6] =>
[customfield7] =>
[customfield8] =>
[customfield9] =>
[customfield10] =>
[test] =>
[test2] =>
[test3] =>
[test4] =>
[test5] =>
[status] => Active
[subscriber_status] => Unsent
[date_last_sent] =>
)
)
)subscriber_status is a combination of status log response status and send status. It returns 1 of 5 values:
- Unsent
- Sent
- Bounced
- Unsubscribed
- Partial - Link clicked and at least one page submitted
- Complete - Link clicked and response completed
GET CONTACT - Get information about a specified contact.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/surveycontact/100039753
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
Response Example (.debug format):
Array
(
[result_ok] => 1
[data] => Array
(
[id] => 100039753
[email_address] => jon.doe@alchemer.com
[first_name] => Jon
[last_name] => Doe
[organization] =>
[division] =>
[department] =>
[team] =>
[group] =>
[role] =>
[home_phone] =>
[fax_phone] =>
[business_phone] =>
[mobilephone]=>
[mailing_address] =>
[mailing_address2] =>
[mailing_address_city] =>
[mailing_address_state] =>
[mailing_address_country] =>
[mailing_address_postal] =>
[title] => Manager
[url] =>
[customfield1] =>
[customfield2] =>
[customfield3] =>
[customfield4] =>
[customfield5] =>
[customfield6] =>
[customfield7] =>
[customfield8] =>
[customfield9] =>
[customfield10] =>
[test] => wow
[test2] =>
[test3] =>
[test4] =>
[test5] =>
[invitelink] => http://s-123-i.sgizmo.com/s3/abcdefg (unique respondent link)
[status] => Active
[subscriber_status] => Unsent
[date_last_sent] =>
)
)subscriber_status is a combination of status log response status and send status. It returns 1 of 5 values:
- Unsent
- Sent
- Bounced
- Partial - Link clicked and at least one page submitted
- Complete - Link clicked and response completed
CREATE CONTACT - Create a new contact.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/surveycontact/?_method=PUT&email_address=newexample@email.com
Note: The unique link associated with the contact will be returned in the results of the create contact call.
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
| email_address | example@email.com | True |
| first_name | Firstname | False |
| last_name | Lastname | False |
| organization | Organization | False |
| division | Division | False |
| department | Department | False |
| team | Team | False |
| group | Group | False |
| role | Role | False |
| home_phone | 123-456-7890 | False |
| fax_phone | 123-456-7890 | False |
| business_phone | 123-456-7890 | False |
| mobilephone | 123-456-7890 | False |
| mailing_address | 123 Main St | False |
| mailing_address2 | Suite 100 | False |
| mailing_address_city | Anycity | False |
| mailing_address_state | CO | False |
| mailing_address_country | US | False |
| mailing_address_postal | 12345 | False |
| title | Title | False |
| url | www.website.com | False |
| customfield1-10* | custom field data 1-10 | False |
| custom[fieldname]† | custom[customerid]=value | False |
| status‡ | Active, Inactive | False |
| allowdupe | true | False |
*These are the custom fields 1-10 that are available as part of the email campaign contact list.
†These are the custom fields that are available as part of the account email lists. Learn how to get the field name for custom fields.
‡Creating a contact with the status "Inactive" will unsubscribe the contact from the email campaign.
the mobilephone parameter is used when creating and updating contacts via an SMS campaign.
UPDATE CONTACT - Update a specified contact.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/surveycontact/100030864?_method=POST
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
| email_address | example@email.com | True |
| first_name | Firstname | False |
| last_name | Lastname | False |
| organization | Organization | False |
| division | Division | False |
| department | Department | False |
| team | Team | False |
| group | Group | False |
| role | Role | False |
| home_phone | 123-456-7890 | False |
| fax_phone | 123-456-7890 | False |
| business_phone | 123-456-7890 | False |
| mobilephone | 123-456-7890 | False |
| mailing_address | 123 Main St | False |
| mailing_address2 | Suite 100 | False |
| mailing_address_city | Anycity | False |
| mailing_address_state | CO | False |
| mailing_address_country | US | False |
| mailing_address_postal | 12345 | False |
| title | Title | False |
| url | www.website.com | False |
| customfield1-10* | custom field data 1-10 | False |
| custom[fieldname]† | custom[customerid]=value | False |
| status‡ | Active, Inactive | False |
*These are the custom fields 1-10 that are available as part of the email campaign contact list.
†These are the custom fields that are available as part of the account email lists. Learn how to get the field name for custom fields.
‡Updating the contact status to "Inactive" will unsubscribe the contact from the email campaign.
DELETE CONTACT - Delete a specified contact.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/surveycontact/100030864?_method=DELETE
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
Response Example (.debug format):
Array
(
[result_ok] => 1
)Getting Custom Field Name from Email Lists
Go to Account > Email Lists and click the link to Manage Custom Fields in the bottom right. The text that you see in the Custom Field Name column for each field is the text that you will use for either a PUT or a POST.
