Spec - Contacts

Table Of Contents

• Get Contacts
• Add Contacts
• Edit Contacts
• Delete Contacts
• Search Contacts
• Unsubscribe Contacts
• Get Contact Groups
• Get User Defined Fields
• Add User Defined Field
• Edit User Defined Field
• Delete User Defined Field

Get Contacts

This function allows the caller to retrieve contacts from the database. Search parameters should be specified inside the tag. Contacts can be retrieved by group, individual contacts can be searched for, or all contacts in the account can be returned.

Input

Specify search criteria within GetContactsRequest tag. Search criteria can be group_id (return all contacts belonging to group), contact_id, firstname, lastname, email. If no search criteria, return all contacts in account.

Specify get_all=“true” to return all contacts that the account has access to, including shared access. Note that when passing get_all=“true” and response=“json” arguments altogether, results are paginated by default and only the first 100 contacts will be returned. To fetch the next page, pass the ‘start_chunk_page’ parameter. To use a different result size other than the default 100, pass the ‘start_chunk_size’ parameter. Automatic pagination only applies when requesting JSON response, XML response is not paginated.

To return unsubscribes only, include Unsubscribed=“true” in the main tag. If a group is specified with the Unsubscribed tag, all unsubscribes from that group will be returned. If not, unsubscribes at the account level will be returned.

Specify Unsubscribed_startdate or Unsubscribed_enddate (YYYYMMDD) to filter unsubcribed contacts within a specific date range. Unsubscribed=“true” must be passed together to work.

To return bounced only, include Bounced=“true” in the main tag. If a group is specified with the Bounced tag, all bounced from that group will be returned. If not, bounced at the account level will be returned.

Specify Bounced_startdate or Bounced_enddate (YYYYMMDD) to filter bounced contacts within a specific date range. Bounced=“true” must be passed together to work.

To get contacts that were updated after a certain timestamp, pass the updated_timestamp parameter in “YYYY-MM-DD HH:mm:ss” format.

To get contacts within a last name range, specify start_lastname and/or end_lastname. Pass do_lead_scoring=“true” to have lead scoring information about each contact included in the output.

Use the ‘search’ parameter to widen the search scope which searches the contact’s firstname, lastname, company, title and email. The ‘search’ parameter does not work with the ‘get_all’ parameter.

Only account owner or power user has the permission to fetch contacts that are not in any groups.

Pagination

GetContactsRequest allows pagination. It can be done by passing the following parameters inside the GetContactsRequest tag:

• start_chunk_page (integer, first page starts from 0, eg. 0/1/2/…)
• start_chunk_size (integer, optional, defaults to 100 if empty)

Pagination can be used in conjunction with any search parameters like ‘get_all’, ‘group_id’, ‘firstname’, ‘search’ and etc.

Refer to example requests 11, 12, and 13 on how to use these parameters.

Output

Success or failure. Total number of contacts matching search. For each contact found: Contact id, first name, last name, title, company, address1, address2, city, state, zip, country, phone, mobile, fax, website, email, birthdate, gender, hometown, height, weight, skills and interests, bio, notes, created datetime, updated time stamp, account number, user-defined fields, groups. DemographicLeadScore and ActivityLeadScore if do_lead_scoring=“true” was passed.

The contacts are sorted in the order of AccountNumber, Lastname, Firstname, Email then Contact_id.

Example Request

<GetContactsRequest></GetContactsRequest>

Example Request

<GetContactsRequest group_id="9985"></GetContactsRequest>

Example Request

<GetContactsRequest firstname="samuel" lastname="Barthman" email="sbarthman@acmewidgetsllc.com"></GetContactsRequest>

Example Request

<GetContactsRequest updated_timestamp="2012-01-01 07:00:34"></GetContactsRequest>

Example Request

<GetContactsRequest start_lastname="D" end_lastname="Jzzzzzzzzzzzz"></GetContactsRequest>

Example Request

<GetContactsRequest search="john"></GetContactsRequest>

Example Request (unsubscribed contacts only)

<GetContactsRequest Unsubscribed="true"></GetContactsRequest>

Example Request (unsubscribed contacts within date range)

<GetContactsRequest Unsubscribed="true" Unsubscribed_startdate="20180101" Unsubscribed_enddate="20180131"></GetContactsRequest>

Example Request (bounced contacts only)

<GetContactsRequest Bounced="true"></GetContactsRequest>

Example Request (bounced contacts within date range)

<GetContactsRequest Bounced="true" Bounced_startdate="20180101" Bounced_enddate="20180131"></GetContactsRequest>

Example Request (shared access - single account)

<GetContactsRequest account_id="123456"></GetContactsRequest>

Example Request (all contacts from all accounts including shared access)

<GetContactsRequest get_all="true"></GetContactsRequest>

Example Request (when requesting JSON response with ‘get_all’, only the first page of 100 contacts from all accounts are returned)

<GetContactsRequest get_all="true" response="json"></GetContactsRequest>

Example Request (to fetch subsequent pages when requesting JSON response with ‘get_all’, pass ‘start_chunk_page’, first page starts at 0)

<GetContactsRequest get_all="true" response="json" start_chunk_page="1"></GetContactsRequest>

Example Request (to override the default 100 chunk size)

<GetContactsRequest get_all="true" response="json" start_chunk_page="0" start_chunk_size="200"></GetContactsRequest>

Example Request (shared access - all contacts with lead scoring)

<GetContactsRequest get_all="true" do_lead_scoring="true"></GetContactsRequest>

Example Request (pagination - get the first page results with default 100 contact size)

<GetContactsRequest start_chunk_page="0"></GetContactsRequest>

Example Request (pagination - get the third page results with default 100 contact size for contacts with firstname ‘John’)

<GetContactsRequest firstname="John" start_chunk_page="2"></GetContactsRequest>

Example Request (pagination - get the second page results with custom 50 contact size for contacts in group_id 4)

<GetContactsRequest group_id="4" start_chunk_page="1" start_chunk_size="50"></GetContactsRequest>

Example Request (power user - get contacts, including those not in any group)

<GetContactsRequest account_id="4" start_chunk_page="0" start_chunk_size="50"></GetContactsRequest>

Successful Response

<GetContactsResponse>
    <Result>Success</Result>
    <Contacts>
        <Contact>
            <Contact_id>8923</Contact_id>
            <Firstname>Jefferey</Firstname>
            <Lastname>Johnson</Lastname>
            <Title>CEO</Title>
            <Company>Acme Widgets, LLC</Company>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Unsubscribed>0</Unsubscribed>
            <CreatedDatetime>2012-07-01 12:34:56</CreatedDatetime>
            <UpdatedTimeStamp>2012-08-29 12:34:56</UpdatedTimeStamp>
            <Birthdate>19890302</Birthdate>
            <Gender>male</Gender>
            <Hometown>Peoria, IL</Hometown>
            <Height>73</Height>
            <Weight>185</Weight>
            <SkillsAndInterests>Pinochle, Basket Weaving</SkillsAndInterests>
            <Bio>(Biographical Information here)</Bio>
            <Notes>Notes from account owner</Notes>
            <AccountNumber>91234</AccountNumber>
            <UserDefinedFields>
                <UserDefinedField>
                    <UserFieldID>932</UserFieldID>
                    <FieldName>Favorite Animal</FieldName>
                    <FieldValue>Dog</FieldValue>
                </UserDefinedField>
                <UserDefinedField>
                    <UserFieldID>1023</UserFieldID>
                    <FieldName>Fruits</FieldName>
                    <FieldValue>Apple</FieldValue>
                </UserDefinedField>
                <UserDefinedField>
                    <UserFieldID>1024</UserFieldID>
                    <FieldName>Checkboxes Type Example</FieldName>
                    <FieldValue>Football,Basketball,Tennis</FieldValue>
                </UserDefinedField>
            </UserDefinedFields>
            <Groups>
                <Group>
                    <Group_id>9985</Group_id>
                    <GroupName>groupname1</GroupName>
                </Group>
                <Group
                    <Group_id>9986</Group_id>
                    <GroupName>groupname2</GroupName>
                </Group>
                <DemographicLeadScore>50</DemographicLeadScore>
                <ActivityLeadScore>329.9</ActivityLeadScore>
            </Groups>
            <Tags>
                <Tag>
                    <TagID>182746</TagID>
                    <TagName>Chief Operating Officer</TagName>
                    <Abbreviation>COO</Abbreviation>
                </Tag>
                <Tag>
                    <TagID>193802</TagID>
                    <TagName>Twitter User</TagName>
                    <Abbreviation>TW</Abbreviation>
                </Tag>
            </Tags>
            <SecondaryCompanies>
                <SecondaryCompany>
                    <CompanyID>1</CompanyID>
                    <CompanyName>Company ABC</CompanyName>
                </SecondaryCompany>
                <SecondaryCompany>
                    <CompanyID>2</CompanyID>
                    <CompanyName>Company DEF</CompanyName>
                </SecondaryCompany>
            </SecondaryCompanies>
        </Contact>
        <Contact>
            <Firstname>Sam</Firstname>
            <Lastname>Bartman</Lastname>
            <Title>CFO</Title>
            <Company>Acme Widgets, LLC</Company>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgets.com</Email>
            <Unsubscribed>1</Unsubscribed>
            <Birthdate>19720230</Birthdate>
            <Gender>male</Gender>
            <Hometown>Youngstown, OH</Hometown>
            <Height>70</Height>
            <Weight>170</Weight>
            <SkillsAndInterests>Piano, Finances</SkillsAndInterests>
            <Bio>(Biographical Information here)</Bio>
            <Notes>Notes from account owner</Notes>
            <CreatedDatetime>2012-07-01 12:34:56</CreatedDatetime>
            <UpdatedTimeStamp>2012-08-29 12:34:56</UpdatedTimeStamp>
            <AccountNumber>91234</AccountNumber>
            <UserDefinedFields>
                <UserDefinedField>
                    <UserFieldID>571</UserFieldID>
                    <FieldName>Favorite Animal</FieldName>
                    <FieldValue>Dog</FieldValue>
                </UserDefinedField>
                <UserDefinedField>
                    <UserFieldID>823</UserFieldID>
                    <FieldName>Fruits</FieldName>
                    <FieldValue>Apple</FieldValue>
                </UserDefinedField>
                <UserDefinedField>
                    <UserFieldID>824</UserFieldID>
                    <FieldName>Checkboxes Type Example</FieldName>
                    <FieldValue>Football,Basketball,Tennis</FieldValue>
                </UserDefinedField>
            </UserDefinedFields>
            <Groups>
                <Group>
                    <ID>9985</ID>
                    <Name>groupname1</Name>
                </Group>
                <Group
                    <ID>9986</ID>
                    <Name>groupname2</Name>
                </Group>
            </Groups>
            <Tags>
                <Tag>
                    <TagID>182746</TagID>
                    <TagName>Chief Executive Officer</TagName>
                    <Abbreviation>CEO</Abbreviation>
                </Tag>
                <Tag>
                    <TagID>193802</TagID>
                    <TagName>Facebook User</TagName>
                    <Abbreviation>FB</Abbreviation>
                </Tag>
            </Tags>
            <DemographicLeadScore>75</DemographicLeadScore>
            <ActivityLeadScore>422.2</ActivityLeadScore>
            <SecondaryCompanies>
                <SecondaryCompany>
                    <CompanyID>3</CompanyID>
                    <CompanyName>Company XYZ</CompanyName>
                </SecondaryCompany>
                <SecondaryCompany>
                    <CompanyID>2</CompanyID>
                    <CompanyName>Company DEF</CompanyName>
                </SecondaryCompany>
            </SecondaryCompanies>
        </Contact>
    </Contacts>
    <TotalMatchingContacts>2</TotalMatchingContacts>
</GetContactsResponse>

Add Contacts

This function allows the caller to add one or more contacts. For shared access, specify the account number to be added to within the contact tag. The caller must have contacts access permissions to an account in order to add a contact.

Input

• account_id (required for shared access users)
• request_id (optional)
• Firstname
• Lastname
• Title
• Company (or CompanyID)
• Address1
• Address2
• City
• State
• Zip
• Country
• Phone
• Mobile
• Fax
• Website
• Email
• Birthdate (YYYYMMDD)
• Gender
• Hometown
• Height
• Weight
• SkillsAndInterests
• Bio
• Notes
• UserDefinedFields (fieldnum/fieldname) (YYYYMMDD format for Date type user fields)
• Groups
• Tags (tag name, not tag abbreviation), only appends new tags if not already assigned to contact. To remove tags from contact, use DeleteTagsFromContactRequest from Spec - Tags.
• SecondaryCompanies (primary Company/CompanyID is required before secondary companies can be added)
• WorkflowID

Pass update=“true” as a request parameter to make use of the add-or-update function. If a contact already exists (matched by email or firstname-lastname), AddContactsRequest will update the existing contact with the newly submitted data instead of adding a new contact.

AddContactsRequest will add the contact into the ‘Groups’ specified in the request data if the contact is currently NOT inside them.

To activate a workflow when adding a new contact, pass a valid WorkflowID tag.

Output

For each Contact ID, success or failure

Example Request 1

<AddContactsRequest>
    <Contacts>
        <Contact request_id="a1b2c3">
            <Firstname>Jefferey</Firstname>
            <Lastname>Johnson</Lastname>
            <Title>CEO</Title>
            <Company>Acme Widgets, LLC</Company>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Birthdate>19690823</Birthdate>
            <Gender>male</Gender>
            <Hometown>Abbotsville</Hometown>
            <Height>73</Height>
            <Weight>220</Weight>
            <SkillsAndInterests>Stock car racing, football</SkillsAndInterests>
            <Bio>Some biographical information</Bio>
            <Notes>Some notes</Notes>
            <UserDefinedFields>
                <UserDefinedField fieldnum="123">Dog</UserDefinedField>
                <UserDefinedField fieldname="Fruits">Apple</UserDefinedField>
                <UserDefinedField fieldname="Checkboxes Type Example">Football,Basketball,Tennis</UserDefinedField>
                <UserDefinedField fieldname="Date Type Example">20231023</UserDefinedField>
            </UserDefinedFields>
            <Groups>
                <Group>groupname1</Group>
                <Group>groupname2</Group>
            </Groups>
            <Tags>
                <Tag>Tag Name</Tag>
                <Tag>Long Tag Name</Tag>
            </Tags>
            <SecondaryCompanies>
                <SecondaryCompany>
                    <CompanyID>3</CompanyID>
                </SecondaryCompany>
                <SecondaryCompany>
                    <CompanyName>Company DEF</CompanyName>
                </SecondaryCompany>
            </SecondaryCompanies>
        </Contact>
        <Contact request_id="d4e5f6">
            <Firstname>Sam</Firstname>
            <Lastname>Bartman</Lastname>
            <Title>CFO</Title>
            <CompanyID>1</CompanyID>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Birthdate>19830623</Birthdate>
            <Gender>male</Gender>
            <Hometown>Flint, MI</Hometown>
            <Height>70</Height>
            <Weight>182</Weight>
            <SkillsAndInterests>Accounting, taxes</SkillsAndInterests>
            <Bio>Some more biographical information</Bio>
            <Notes>Some more notes</Notes>
            <UserDefinedFields>
                <UserDefinedField fieldnum="123">Dog</UserDefinedField>
                <UserDefinedField fieldname="Fruits">Apple</UserDefinedField>
                <UserDefinedField fieldname="Checkboxes Type Example">Football,Basketball,Tennis</UserDefinedField>
                <UserDefinedField fieldname="Date Type Example">20231023</UserDefinedField>
            </UserDefinedFields>
            <Groups>
                <Group>groupname3</Group>
                <Group>groupname4</Group>
            </Groups>
            <Tags>
                <Tag>Tag Name</Tag>
                <Tag>Long Tag Name</Tag>
            </Tags>
            <SecondaryCompanies>
                <SecondaryCompany>
                    <CompanyID>3</CompanyID>
                </SecondaryCompany>
                <SecondaryCompany>
                    <CompanyName>Company DEF</CompanyName>
                </SecondaryCompany>
            </SecondaryCompanies>
            <WorkflowID>4</WorkflowID>
        </Contact>
    </Contacts>
</AddContactsRequest>

Example Request 2 (shared access)

<AddContactsRequest>
    <Contacts>
        <Contact account_id="123456">
            <Firstname>Jefferey</Firstname>
            <Lastname>Johnson</Lastname>
            <Title>CEO</Title>
            <Company>Acme Widgets, LLC</Company>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Birthdate>19891119</Birthdate>
            <Gender>male</Gender>
            <Hometown>Mobile, AL</Hometown>
            <Height>72</Height>
            <Weight>195</Weight>
            <SkillsAndInterests>Race car driving, manufacturing</SkillsAndInterests>
            <Bio>Some biographical information</Bio>
            <Notes>Some notes</Notes>
            <UserDefinedFields>
                <UserDefinedField fieldnum="123">Dog</UserDefinedField>
                <UserDefinedField fieldname="Fruits">Apple</UserDefinedField>
                <UserDefinedField fieldname="Checkboxes Type Example">Football,Basketball,Tennis</UserDefinedField>
                <UserDefinedField fieldname="Date Type Example">20231023</UserDefinedField>
            </UserDefinedFields>
            <Groups>
                <Group>groupname1</Group>
                <Group>groupname2</Group>
            </Groups>
            <Tags>
                <Tag>Tag Name</Tag>
                <Tag>Long Tag Name</Tag>
            </Tags>
        </Contact>
    </Contacts>
</AddContactsRequest>

Example Request 3

<AddContactsRequest update="true">
    <Contacts>
        <Contact>
            <Firstname>Jefferey</Firstname>
            <Lastname>Johnson</Lastname>
            <Title>CEO</Title>
            <CompanyID>1</CompanyID>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Birthdate>19891119</Birthdate>
            <Gender>male</Gender>
            <Hometown>Mobile, AL</Hometown>
            <Height>72</Height>
            <Weight>195</Weight>
            <SkillsAndInterests>Race car driving, manufacturing</SkillsAndInterests>
            <Bio>Some biographical information</Bio>
            <Notes>Some notes</Notes>
            <UserDefinedFields>
                <UserDefinedField fieldnum="123">Dog</UserDefinedField>
                <UserDefinedField fieldname="Fruits">Apple</UserDefinedField>
                <UserDefinedField fieldname="Checkboxes Type Example">Football,Basketball,Tennis</UserDefinedField>
                <UserDefinedField fieldname="Date Type Example">20231023</UserDefinedField>
            </UserDefinedFields>
            <Groups replace="true">
                <Group>groupname1</Group>
                <Group>groupname2</Group>
            </Groups>
            <Tags>
                <Tag>Tag Name</Tag>
                <Tag>Long Tag Name</Tag>
            </Tags>
        </Contact>
    </Contacts>
</AddContactsRequest>

Successful Response

<AddContactsResponse>
    <Contacts>
        <Contact request_id="a1b2c3">
            <Result>Success</Result>
            <AccountNumber>91234</AccountNumber>
            <Contact_id>8984</Contact_id>
            <UpdatedTimeStamp>2012-08-29 12:34:34</UpdatedTimeStamp>
        </Contact>
        <Contact request_id="d4e5f6">
            <Result>Success</Result>
            <AccountNumber>91234</AccountNumber>
            <Contact_id>8985</Contact_id>
            <UpdatedTimeStamp>2012-08-29 12:36:00</UpdatedTimeStamp>
        </Contact>
    </Contacts>
</AddContactsResponse>

Edit Contacts

This function allows the caller to modify one or more contacts already in the database. Search parameters should be specified inside the tag, while parameters to change to would be specified individually.

Input

Specify search criteria within each Contact tag. Search criteria can be:

• account_id (required for shared access users)
• contact_id
• firstname
• lastname
• email
• request_id (optional)

Each contact’s search criteria must return a single unique contact to modify.

Parameters to change can include:

• Firstname
• Lastname
• Title
• Company (or CompanyID)
• Address1
• Address2
• City
• State
• Zip
• Country
• Phone
• Mobile
• Fax
• Website
• Email
• Birthdate (YYYYMMDD)
• Gender
• Hometown
• Height
• Weight
• SkillsAndInterests
• Bio
• Notes
• Groups
• Tags (tag name, not tag abbreviation), only appends new tags if not already assigned to contact. To remove tags from contact, use DeleteTagsFromContactRequest from Spec - Tags.
• UserDefinedFields (fieldnum/fieldname, only the variables that are being changed need to be passed) (YYYYMMDD format for Date type user fields)
• SecondaryCompanies (primary Company/CompanyID is required before secondary companies can be added. To remove the secondary company from contact, pass the 'remove' argument)

Pass ‘replace=“true”’ parameter to the Groups tag to replace the contact’s group entirely. Default case will always append new group into existing groups if ‘replace’ parameter is not specified. (See Example Request 3)

For shared access, include account number within the contact tag. Caller must have contacts permissions in the account to edit contacts.

Pass Updated Time Stamp in order to have comparison with timestamp on server before making change. If server timestamp is later, change will be rejected. If timestamp is not included in the request, change is always made.

Output

For each Contact ID, success or failure

Example Request 1

<EditContactsRequest>
    <Contacts>
        <Contact contact_id="8984" request_id="a1b2c3">
            <Firstname>Jefferey</Firstname>
            <Lastname>Johnson</Lastname>
            <Title>CEO</Title>
            <Company>Acme Widgets, LLC</Company>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Birthdate>19870501</Birthdate>
            <Gender>male</Gender>
            <Hometown>Mobile, AL</Hometown>
            <Height>72</Height>
            <Weight>195</Weight>
            <SkillsAndInterests>Race car driving, manufacturing</SkillsAndInterests>
            <Bio>Some biographical information</Bio>
            <Notes>Some notes</Notes>
            <UserDefinedFields>
                <UserDefinedField fieldnum="123">Dog</UserDefinedField>
                <UserDefinedField fieldname="Fruits">Apple</UserDefinedField>
                <UserDefinedField fieldname="Checkboxes Type Example">Football,Basketball,Tennis</UserDefinedField>
                <UserDefinedField fieldname="Date Type Example">20231023</UserDefinedField>
            </UserDefinedFields>
            <Tags>
                <Tag>Tag Name</Tag>
                <Tag>Long Tag Name</Tag>
            </Tags>
            <SecondaryCompanies>
                <SecondaryCompany remove="true">
                    <CompanyID>3</CompanyID>
                </SecondaryCompany>
                <SecondaryCompany>
                    <CompanyName>Company DEF</CompanyName>
                </SecondaryCompany>
            </SecondaryCompanies>
        </Contact>
        <Contact firstname="samuel" lastname="Barthman" email="sbarthman@acmewidgetsllc.com" request_id="d4e5f6">
            <Firstname>Sam</Firstname>
            <Lastname>Bartman</Lastname>
            <Title>CFO</Title>
            <CompanyID>1</CompanyID>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>sbartman@acmewidgetsllc.com</Email>
            <Birthdate>19910323</Birthdate>
            <Gender>male</Gender>
            <Hometown>Mobile, AL</Hometown>
            <Height>72</Height>
            <Weight>195</Weight>
            <SkillsAndInterests>Race car driving, manufacturing</SkillsAndInterests>
            <Bio>Some biographical information</Bio>
            <Notes>Some notes</Notes>
            <UserDefinedFields>
                <UserDefinedField fieldnum="123">Dog</UserDefinedField>
                <UserDefinedField fieldname="Fruits">Apple</UserDefinedField>
                <UserDefinedField fieldname="Checkboxes Type Example">Football,Basketball,Tennis</UserDefinedField>
                <UserDefinedField fieldname="Date Type Example">20231023</UserDefinedField>
            </UserDefinedFields>
            <Tags>
                <Tag>Tag Name</Tag>
                <Tag>Long Tag Name</Tag>
            </Tags>
            <SecondaryCompanies>
                <SecondaryCompany remove="true">
                    <CompanyID>3</CompanyID>
                </SecondaryCompany>
                <SecondaryCompany>
                    <CompanyName>Company DEF</CompanyName>
                </SecondaryCompany>
            </SecondaryCompanies>
        </Contact>
    </Contacts>
</EditContactsRequest>

Example Request 2 (Shared access, timestamp checking)

<EditContactsRequest>
    <Contacts>
        <Contact account_id="12345" contact_id="8984">
            <UpdatedTimeStamp>2012-08-30 12:12:33</UpdatedTimeStamp>
            <Firstname>Jefferey</Firstname>
            <Lastname>Johnson</Lastname>
            <Title>CEO</Title>
            <Company>Acme Widgets, LLC</Company>
            <Address1>101 First Street</Address1>
            <Address2>Suite 234</Address2>
            <City>Naperville</City>
            <State>IL</State>
            <Zip>60565</Zip>
            <Country>USA</Country>
            <Phone>630-305-9999</Phone>
            <Mobile>708-555-6565</Mobile>
            <Fax>630-305-9988</Fax>
            <Website>http://www.acmewidgetsllc.com</Website>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Birthdate>19840823</Birthdate>
            <Gender>male</Gender>
            <Hometown>Mobile, AL</Hometown>
            <Height>72</Height>
            <Weight>195</Weight>
            <SkillsAndInterests>Race car driving, manufacturing</SkillsAndInterests>
            <Bio>Some biographical information</Bio>
            <Notes>Some notes</Notes>
            <UserDefinedFields>
                <UserDefinedField fieldnum="123">Dog</UserDefinedField>
                <UserDefinedField fieldname="Fruits">Apple</UserDefinedField>
                <UserDefinedField fieldname="Checkboxes Type Example">Football,Basketball,Tennis</UserDefinedField>
                <UserDefinedField fieldname="Date Type Example">20231023</UserDefinedField>
            </UserDefinedFields>
            <Tags>
                <Tag>Tag Name</Tag>
                <Tag>Long Tag Name</Tag>
            </Tags>
        </Contact>
    </Contacts>
</EditContactsRequest>

Example Request 3 (Groups replace)

<EditContactsRequest>
    <Contacts>
        <Contact contact_id="817">
            <Firstname>Jefferey</Firstname>
            <Lastname>Johnson</Lastname>
            <Email>jjohnson@acmewidgetsllc.com</Email>
            <Groups replace="true">
                <Group>Group A</Group>
                <Group>Group B</Group>
            </Groups>
        </Contact>
        <Contact contact_id="818">
            <Firstname>Sam</Firstname>
            <Lastname>Bartman</Lastname>
            <Email>sbartman@acmewidgetsllc.com</Email>
            <Groups>
                <Group>Group A</Group>
            </Groups>
        </Contact>
    </Contacts>
</EditContactsRequest>

Successful Response

<EditContactsResponse>
    <Contacts>
        <Contact request_id="a1b2c3">
            <Result>Success</Result>
            <AccountNumber>91234</AccountNumber>
            <Contact_id>8984</Contact_id>
            <UpdatedTimeStamp>2012-08-30 14:23:03</UpdatedTimeStamp>
        </Contact>
        <Contact request_id="d4e5f6">
            <Result>Success</Result>
            <AccountNumber>91234</AccountNumber>
            <Contact_id>8985</Contact_id>
            <UpdatedTimeStamp>2012-08-30 14:24:09</UpdatedTimeStamp>
        </Contact>
    </Contacts>
</EditContactsResponse>

Delete Contacts

This function allows the caller to delete one or more contacts from the database.

Input

Specify search criteria within each Contact tag. Search criteria can be:

• account_id (required for shared access users)
• contact_id
• firstname
• lastname
• email
• request_id (optional)

Each contact’s search criteria must return a single unique contact to delete. For shared access, include account number within the contact tag. Caller must have contacts permissions in the account to delete contacts.

Output

For each Contact ID, success or failure.

Example Request 1

<DeleteContactsRequest>
    <Contacts>
        <Contact contact_id="8984" request_id="a1b2c3" />
        <Contact contact_id="8983" request_id="d4e5f6" />
    </Contacts>
</DeleteContactsRequest>

Example Request 2 (shared access)

<DeleteContactsRequest>
    <Contacts>
        <Contact account_id="12345" contact_id="8984" />
        <Contact account_id="12346" contact_id="8983" />
    </Contacts>
</DeleteContactsRequest>

Successful Response

<DeleteContactsResponse>
    <Contacts>
        <Contact request_id="a1b2c3">
            <AccountNumber>91234</AccountNumber>
            <Contact_id>8984</Contact_id>
            <Result>Success</Result>
        </Contact>
        <Contact request_id="d4e5f6">
            <AccountNumber>91236</AccountNumber>
            <Contact_id>8983</Contact_id>
            <Result>Success</Result>
        </Contact>
    </Contacts>
</DeleteContactsResponse>

Search Contacts

This function allows the caller to search for contacts from the database. Search parameters should be specified inside the tag.

Input

• group_id
• From (all, single, multiple) groups
• Groups (group IDs)
• Filter (none, any, all)
• Rules
  • Field (ID, Email, Firstname, Lastname, Title, Company, Address1, Address2, City, State, Zip, Country, Phone, Mobile, Fax, Website, Gender, Birthdate, Hometown, DefaultJerseyNum, Height, Weight, ParentsName, ParentsEmail, ParentsMobile, ParentsName2, ParentsEmail2, ParentsMobile2, Bio, SkillsInterests, ForumModerator, Notes, Picture, CompanyID)
  • Operator (contains, notcontains, is, isnt, gt, lt)
  • Value
• Rules (for datetime filters)
  • Field (ContactCreated, LastModified)
  • Range (on, before, after, between)
  • Date (YYYY/MM/DD)
  • Date2 (required if Range value is ‘between’)
• Includes (Unsubscribers, BouncedContacts, SpamComplaints, DuplicateEmails, ActiveMembers, ProspectMembers, InactiveMembers)
• OrderBy (Email, Lastname, Firstname, Title, Company, Address1, Address2, City, State, Zip, Country, Phone, Mobile, Fax, Website, Gender, Birthdate, Hometown, DefaultJerseyNum, Height, Weight, ParentsName, ParentsEmail, ParentsMobile, ParentsName2, ParentsEmail2, ParentsMobile2, Bio, SkillsInterests, ForumModerator, Notes, ContactCreated, LastModified)
• OrderDirection (asc, desc)
• Page (1, 2, 3…)

Output

Success or failure. Total number of contacts matching search. For each contact found: Contact ID, firstname, lastname, email, phone and mobile.

Example Request 1

<SearchContactsRequest group_id='4'>
    <From>single</From>
    <Groups>
        <Group>4</Group>
    </Groups>
    <Filter>any</Filter>
    <Rules>
        <Rule>
            <Field>ID</Field>
            <Operator>contains</Operator>
            <Value>123</Value>
        </Rule>
        <Rule>
            <Field>ID</Field>
            <Operator>contains</Operator>
            <Value>124</Value>
        </Rule>
        <Rule>
            <Field>LastModified</Field>
            <Range>after</Range>
            <Date>2017/08/20</Date>
        </Rule>
        <Rule>
            <Field>ContactCreated</Field>
            <Range>between</Range>
            <Date>2017/08/20</Date>
            <Date2>2017/08/25</Date2>
        </Rule>
    </Rules>
    <Includes>
        <Unsubscribers>Y</Unsubscribers>
        <BouncedContacts>Y</BouncedContacts>
        <SpamComplaints>Y</SpamComplaints>
        <DuplicateEmails>Y</DuplicateEmails>
        <ActiveMembers>Y</ActiveMembers>
        <ProspectMembers>Y</ProspectMembers>
        <InactiveMembers>Y</InactiveMembers>
    </Includes>
    <OrderBy>ID</OrderBy>
    <OrderDirection>desc</OrderDirection>
    <Page>1</Page>
</SearchContactsRequest>

Successful Response

<SearchContactsResponse>
    <Result>Success</Result>
    <TotalMatchingContacts>2</TotalMatchingContacts>
    <Contacts>
        <Contact>
            <ID>124</ID>
            <Firstname>Testfirst2</Firstname>
            <Lastname>Test2</Lastname>
            <Phone>012-111-111</Phone>
            <Mobile>11111</Mobile>
            <Email>customer+test2@gmail.com</Email>
        </Contact>
        <Contact>
            <ID>123</ID>
            <Firstname>Testfirst1 &amp; and " ' P</Firstname>
            <Lastname>Test1 &amp; 2</Lastname>
            <Phone>(012) 111-111</Phone>
            <Mobile>1111-1</Mobile>
            <Email>customer+test1@gmail.com</Email>
        </Contact>
    </Contacts>
</SearchContactsResponse>

Unsubscribe Contacts

This function allows the caller to unsubscribe one or more contacts from the database.

Input

Specify search criteria within each Contact tag. Search criteria can be:

• account_id (required for shared access users)
• contact_id
• firstname
• lastname
• email
• request_id (optional)

Each contact’s search criteria must return a single unique contact to unsubscribe. For shared access, include account number within the contact tag. Caller must have contacts permissions in the account to unsubscribe contacts.

Output

For each Contact ID, success or failure.

Example Request 1

<UnsubscribeContactsRequest>
    <Contacts>
        <Contact contact_id="8984" request_id="a1b2c3" />
        <Contact contact_id="8983" request_id="d4e5f6" />
    </Contacts>
</UnsubscribeContactsRequest>

Example Request 2 (shared access)

<UnsubscribeContactsRequest>
    <Contacts>
        <Contact account_id="12345" contact_id="8984" />
        <Contact account_id="12346" contact_id="8983" />
    </Contacts>
</UnsubscribeContactsRequest>

Successful Response

<UnsubscribeContactsResponse>
    <Contacts>
        <Contact request_id="a1b2c3">
            <Contact_id>8984</Contact_id>
            <Result>Success</Result>
        </Contact>
        <Contact request_id="d4e5f6">
            <Contact_id>8983</Contact_id>
            <Result>Success</Result>
        </Contact>
    </Contacts>
</UnsubscribeContactsResponse>

Get Contact Groups

This function allows the caller to get all of the groups that a contact belongs or to get all of the groups available in the account.

Input

Contact search criteria. Search criteria can be contact_id, firstname, lastname, email. If omitted, return all groups in the account

Output

List of group IDs and names the contact belongs to or all the groups in the account

Example Request

<GetContactGroupsRequest contact_id="8984"></GetContactGroupsRequest>

Successful Response

<GetContactGroupsResponse>
    <Result>Success</Result>
    <ContactGroups>
        <ContactGroup>
            <Group_id>9902</Group_id>
            <GroupName>My Mailing List 2</GroupName>
        </ContactGroup>
        <ContactGroup>
            <Group_id>9903</Group_id>
            <GroupName>My Mailing List 3</GroupName>
        </ContactGroup>
    </ContactGroups>
</GetContactGroupsResponse>

Get User Defined Fields

This function allows the caller to fetch contact user-defined fields for an account.

Input

AccountID (optional - required for shared access. If missing, will be account owned by the user). To get events after a timestamp obtained eariler, pass updated_timestamp = (“timestampvalue”).

Output

Success or failure. For each user-defined field, Group (a group ID or “All”), UserFieldID, FieldName, FieldType, PossibleValues (a comma-delimited list), ContactEditable, UpdatedTimeStamp.

Example Request 1

<GetUserDefinedFieldsRequest></GetUserDefinedFieldsRequest>

Example Request 2 (shared access)

<GetUserDefinedFieldsRequest account_id="1392"></GetUserDefinedFieldsRequest>

Example Request 3

<GetUserDefinedFieldsRequest updated_timestamp="2012-08-01 12:00:00"></GetUserDefinedFieldsRequest>

Successful Response

<GetUserDefinedFieldsResponse>
    <Result>Success</Result>
    <UserDefinedFields>
        <UserDefinedField>
            <Group>2</Group>
            <UserFieldID>93</UserFieldID>
            <FieldName>Favorite Animal</FieldName>
            <FieldType>Checkbox</FieldType>
            <PossibleValues>Dog,Cat,Monkey</PossibleValues>
            <ContactEditable>Editable</ContactEditable>
            <UpdatedTimeStamp>2012-12-06 10:52:17</UpdatedTimeStamp>
        </UserDefinedField>
        <UserDefinedField>
            <Group>5</Group>
            <UserFieldID>154</UserFieldID>
            <FieldName>Fruits</FieldName>
            <FieldType>Select</FieldType>
            <PossibleValues>Apple,Orange,Banana</PossibleValues>
            <ContactEditable>Visible</ContactEditable>
            <UpdatedTimeStamp>2012-12-06 14:59:29</UpdatedTimeStamp>
        </UserDefinedField>
    </UserDefinedFields>
</GetUserDefinedFieldsResponse>

Add User Defined Field

This function allows the caller to add a user-defined field for contacts belonging to a group, or universally for all groups in the account.

Input

Group ID to add to. Use 0 for Group ID to make the user-defined field available to all groups. Field name. Field type (Select, Checkbox, Text, or ShortText) (optional - defaults to Text). Possible values (should be separated by commas) (optional). Contact editable (Hidden, Visible, or Editable)(optional - defaults to Hidden).

Output

Success or failure. If successful, UserFieldID, AccountNumber, UpdatedTimeStamp.

Example Request 1

<AddUserDefinedFieldRequest group_id="9902">
    <FieldName>Fruits</FieldName>
    <FieldType>Select</FieldType>
    <PossibleValues>Orange,Apple,Banana</PossibleValues>
    <ContactEditable>Visible</ContactEditable>
</AddUserDefinedFieldRequest >

Example Request 2

<AddUserDefinedFieldRequest group_id="0">
    <FieldName>MyUserDefinedField2</FieldName>
</AddUserDefinedFieldRequest >

Successful Response

<AddUserDefinedFieldResponse>
    <Result>Success</Result>
    <UserFieldID>8</UserFieldID>
    <AccountNumber>19821</AccountNumber>
    <UpdatedTimeStamp>2012-12-09 13:23:52</UpdatedTimeStamp>
</AddUserDefinedFieldResponse>

Edit User Defined Field

This function allows the caller to edit a user-defined field.

Input

Group ID to assign the user id to. Use 0 for Group ID to make the user-defined field available to all groups. Field name. Field type (Select, Checkbox, Text, or ShortText). Possible values (should be separated by commas). Contact editable (Hidden, Visible, or Editable). Field name is required to identify the field. All other parameters are optional and only need to be passed if they are going to be changed.

Output

Success or failure. If successful, UserFieldID, AccountNumber, UpdatedTimeStamp.

Example Request 1

<EditUserDefinedFieldRequest group_id="9902">
    <FieldName>Favorite Animal</FieldName>
    <FieldType>Checkbox</FieldType>
    <PossibleValues>Dog,Cat,Monkey</PossibleValues>
    <ContactEditable>Editable</ContactEditable>
</EditUserDefinedFieldRequest>

Example Request 2

<EditUserDefinedFieldRequest group_id="0">
    <FieldName>MyUserDefinedField2</FieldName>
</EditUserDefinedFieldRequest>

Successful Response

<EditUserDefinedFieldResponse>
    <Result>Success</Result>
    <UserFieldID>8</UserFieldID>
    <AccountNumber>19821</AccountNumber>
    <UpdatedTimeStamp>2012-12-09 13:23:52</UpdatedTimeStamp>
</EditUserDefinedFieldResponse>

Delete User Defined Field

This function allows the caller to delete a user-defined field.

Input

Field name to delete.

Output

Success or failure.

Example Request

<DeleteUserDefinedFieldRequest>
    <FieldName>Favorite Animal</FieldName>
</DeleteUserDefinedFieldRequest>

Successful Response

<DeleteUserDefinedFieldResponse>
    <Result>Success</Result>
</DeleteUserDefinedFieldResponse>