Contact Sub-Object

Note: 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 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 Contact sub-object:

GET LIST - Get a list of all of your contacts for the specified survey and campaign.

https://api.alchemer.com/v4/survey/123456/surveycampaign/100000/contact
ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True
pagepage=3False
resultsperpageresultsperpage=100False

Response Example (.debug format):

Array
(
    [result_ok] => 1
    [total_count] => 55000
    [page] => 1
    [total_pages] => 1100
    [results_per_page] => 50
    [data] => Array
        (
            [0] => Array
                (
                    [id] => 100030864
                    [semailaddress] => example@email.com
                    [sfirstname] => First
                    [slastname] => Last
                    [sorganization] => Organization
                    [sdepartment] => Department
                    [shomephone] => 123-456-7891
                    [sfaxphone] => 
                    [sbusinessphone] => 
                    [smailingaddress] => 123 Main St
                    [smailingaddress2] => 
                    [smailingaddresscity] => Anycity
                    [smailingaddressstate] => CO
                    [smailingaddresscountry] => US
                    [smailingaddresspostal] => 12345
                    [stitle] => 
                    [surl] => 
                    [scustomfield1] => 
                    [scustomfield2] => 
                    [scustomfield3] => 
                    [scustomfield4] => 
                    [scustomfield5] => 
                    [scustomfield6] => 
                    [scustomfield7] => 
                    [scustomfield8] => 
                    [scustomfield9] => 
                    [scustomfield10] => 
                    [estatus] => Active
                    [esubscriberstatus*] => Unsent
                )
               .
               .
               .
               .
            [49] => Array
                (
                   [id] => 100030864
                    [semailaddress] => example@email.com
                    [sfirstname] => First
                    [slastname] => Last
                    [sorganization] => Organization
                    [sdepartment] => Department
                    [shomephone] => 123-456-7891
                    [sfaxphone] => 
                    [sbusinessphone] => 
                    [smailingaddress] => 123 Main St
                    [smailingaddress2] => 
                    [smailingaddresscity] => Anycity
                    [smailingaddressstate] => CO
                    [smailingaddresscountry] => US
                    [smailingaddresspostal] => 12345
                    [stitle] => 
                    [surl] => 
                    [scustomfield1] => 
                    [scustomfield2] => 
                    [scustomfield3] => 
                    [scustomfield4] => 
                    [scustomfield5] => 
                    [scustomfield6] => 
                    [scustomfield7] => 
                    [scustomfield8] => 
                    [scustomfield9] => 
                    [scustomfield10] => 
                    [estatus] => Active
                    [esubscriberstatus] => Unsent
                )

        )

)

esubscriberstatus 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

Back to the Top

GET CONTACT - Get a information about a specified contact.

https://api.alchemer.com/v4/survey/123456/surveycampaign/100000/contact/100030864
ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True

Response Example (.debug format):

Array
(
    [result_ok] => 1
    [data] => Array
        (
            [id] => 100030864
            [semailaddress] => fakegizmo777+0@gmail.com
            [sfirstname] => 
            [slastname] => 
            [sorganization] => 
            [sdepartment] => 
            [shomephone] => 
            [sfaxphone] => 
            [sbusinessphone] => 
            [smailingaddress] => 
            [smailingaddress2] => 
            [smailingaddresscity] => 
            [smailingaddressstate] => 
            [smailingaddresscountry] => 
            [smailingaddresspostal] => 
            [stitle] => 
            [surl] => 
            [scustomfield1] => 
            [scustomfield2] => 
            [scustomfield3] => 
            [scustomfield4] => 
            [scustomfield5] => 
            [scustomfield6] => 
            [scustomfield7] => 
            [scustomfield8] => 
            [scustomfield9] => 
            [scustomfield10] => 
            [estatus] => Active
            [esubscriberstatus*] => Unsent
        )

)

*esubscriberstatus 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

Back to the Top

CREATE CONTACT - Create a new contact.

https://api.alchemer.com/v4/survey/123456/surveycampaign/100000/contact/?_method=PUT&semailaddress=newexample@email.com
ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True
semailaddressexample@email.comTrue
sfirstnameFirstnameFalse
slastnameLastnameFalse
sorganizationOrganizationFalse
sdivisionDivisionFalse
sdepartmentDepartmentFalse
steamTeamFalse
sgroupGroupFalse
sroleRoleFalse
shomephone123-456-7890False
sfaxphone123-456-7890False
sbusinessphone123-456-7890False
smailingaddress123 Main StFalse
smailingaddress2Suite 100False
smailingaddresscityAnycityFalse
smailingaddressstateCOFalse
smailingaddresscountryUSFalse
smailingaddresspostal12345False
stitleTitleFalse
surlwww.website.comFalse
scustomfield1-10*custom field data 1-10False
custom[ID]†custom[15]=valueFalse
estatusActive, InactiveFalse
allowdupetrueFalse

*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 ID number for custom fields.

Back to the Top

UPDATE CONTACT - Update a specified contact.

https://api.alchemer.com/v4/survey/123456/surveycampaign/100000/contact/100030864?_method=POST
ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True
semailaddressexample@email.comFalse
sfirstnameFirstnameFalse
slastnameLastnameFalse
sorganizationOrganizationFalse
sdivisionDivisionFalse
sdepartmentDepartmentFalse
steamTeamFalse
sgroupGroupFalse
sroleRoleFalse
shomephone123-456-7890False
sfaxphone123-456-7890False
sbusinessphone123-456-7890False
smailingaddress123 Main StFalse
smailingaddress2Suite 100False
smailingaddresscityAnycityFalse
smailingaddressstateCOFalse
smailingaddresscountryUSFalse
smailingaddresspostal12345False
stitleTitleFalse
surlwww.website.comFalse
scustomfield1-10*custom field data 1-10False
custom[ID]†custom[15]=valueFalse
estatus‡Active, InactiveFalse

*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 ID number 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/v4/survey/123456/surveycampaign/100000/contact/100030864?_method=DELETE
ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True

Response Example (.debug format):

Array
(
    [result_ok] => 1
)

Getting Custom Field ID from Email Lists

Go to Account > Email Lists and click the link to Manage Custom Fields in the bottom left. With a web-developer tool installed on your browser right click on the desired field and click Inspect Element. This will give you the details for this field. What you are looking for is the name field. It will look like the below. The number is all you need for either a PUT or a POST.

Back to the Top