The Relenta API is implemented as XML over HTTP. We use HTTP Basic Authentication. When you use the API, you access the system with the same permissions as the user who was authenticated.

The Relenta API is implemented as REST, a simple HTTP GET or POST action. The REST Endpoint URL is:

http://[account-id].relenta.com/api/rest/

By default, REST requests will send a REST response, or a simple XML block. To return the response in REST format, send a parameter “format” in the request with a value of “rest”. When using the REST request method, the response defaults to REST.

A method call returns this:

<?xml version="1.0" encoding="utf-8" ?>
<response stat="ok">
      [xml-payload-here]
</response>

If an error occurs, the following is returned:

<?xml version="1.0" encoding="utf-8" ?>
<response stat="fail" code=”[error-code]”>
    <message>[error-message]</message>
</response>
GLOBAL ERROR CODES

101, 'Bad account ID'
102, 'Authorization method not allowed'
103, 'Not authorized'
104, 'Request signature required'
105, 'Bad request signature'
112, 'Function not found'

API FUNCTIONS
relenta.Contact.getList

Get a list of contacts

Authentication
This method requires authentication.

Arguments
dp_key (Required) The department key
page (Optional) Page number to return, default is 0
per_page (Optional) Number of results per page, default is 500, maximum value is 500

Error Codes
500, 'Bad department key'

Example Response

<contacts>
    <contact>
        <id>22038732</id>
        <first-name>James</first-name>
        <last-name>Bond</last-name>
        <title>Agent</title>
        <company>British Secret Intelligence Service</company>
        <comment>007 on an island populated exclusively by women? We won't see him till dawn!</comment>
        <created-at>2008-08-31T13:55:04.000Z</created-at>
        <updated-at>2008-12-29T15:48:01.000Z</updated-at>
        <contact-emails>
            <email>james.bond@mi6.gov.uk</email>
        </contact-emails>
        <contact-info>
            <info-block label="Default">
                <info type="phone" label="Cell">+44 43593434534</info>
                <info type="fax">+44 43593434534</info>
                <info type="url" label="Work">www.mi6.uk.gov</info>
                <info type="messenger" label="YIM">james.bond</info>
                <info type="free_form_address">PO Box 1300 London SE1 1BD England
                </info>
                <info type="text">Just text field</info>
            </info-block>
            <info-block label="Work">
                <info type="free_form_address" label="HQ">PO Box 1300 London SE1 1BD England
                </info>
            </info-block>
        </contact-info>
        <contact-custom-fields>
            <field type="set" name="Type of Business">
                <value>Groomer</value>
                <value>Rescue</value>
            </field>
            <field type="set" name="Paid or Not Paid">
                <value>Paid</value>
            </field>
            <field type="string" name="Waiting for Brochures?">Yes</field>
            <field type="enum" name="AccountLevel">Level 3</field>
            <field type="date" name="Date Added">2007-03-14T05:00:00.000Z</field>
            <field type="number" name="Invoice #">12381-2893-2964</field>
        </contact-custom-fields>
        <contact-groups>
            <group id="686" name="First" category="Level of interest" />
            <group id="687" name="Second" category="Level of interest" />
            <group id="22014799" name="Sixth" category="Level of interest" />
            <group id="692" name="Cold calling" category="Source" />
            <group id="1615" name="Email" category="Preferred contact" />
        </contact-groups>
        <tags>
            <tag>Blofeld</tag>
            <tag>Dr. No</tag>
            <tag>Scaramanga</tag>
            <tag>goldfinger</tag>
        </tags>
    </contact>
</contacts>
relenta.Contact.getListByGroupId

Get a list of contacts for given contact group ID

Authentication
This method requires authentication.

Arguments
dp_key (Required) The department key
cn_group_id (Required) The contact group ID
page (Optional) Page number to return, default is 0
per_page (Optional) Number of results per page, default is 500, maximum value is 500

Error Codes
500, 'Bad department key'
501, 'Bad contact group id'

Example Response

<contacts>
    <contact>
        <id>22038732</id>
        <first-name>James</first-name>
        <last-name>Bond</last-name>
        <title>Agent</title>
        <company>British Secret Intelligence Service</company>
        <comment>007 on an island populated exclusively by women? We won't see him till dawn!</comment>
        <created-at>2008-08-31T13:55:04.000Z</created-at>
        <updated-at>2008-12-29T15:48:01.000Z</updated-at>
        <contact-emails>
            <email>james.bond@mi6.gov.uk</email>
        </contact-emails>
        <contact-info>
            <info-block label="Default">
                <info type="phone" label="Cell">+44 43593434534</info>
                <info type="fax">+44 43593434534</info>
                <info type="url" label="Work">www.mi6.uk.gov</info>
                <info type="messenger" label="YIM">james.bond</info>
                <info type="free_form_address">PO Box 1300 London SE1 1BD England
                </info>
                <info type="text">Just text field</info>
            </info-block>
            <info-block label="Work">
                <info type="free_form_address" label="HQ">PO Box 1300 London SE1 1BD England
                </info>
            </info-block>
        </contact-info>
        <contact-custom-fields>
            <field type="set" name="Type of Business">
                <value>Groomer</value>
                <value>Rescue</value>
            </field>
            <field type="set" name="Paid or Not Paid">
                <value>Paid</value>
            </field>
            <field type="string" name="Waiting for Brochures?">Yes</field>
            <field type="enum" name="AccountLevel">Level 3</field>
            <field type="date" name="Date Added">2007-03-14T05:00:00.000Z</field>
            <field type="number" name="Invoice #">12381-2893-2964</field>
        </contact-custom-fields>
        <contact-groups>
            <group id="686" name="First" category="Level of interest" />
            <group id="687" name="Second" category="Level of interest" />
            <group id="22014799" name="Sixth" category="Level of interest" />
            <group id="692" name="Cold calling" category="Source" />
            <group id="1615" name="Email" category="Preferred contact" />
        </contact-groups>
        <tags>
            <tag>Blofeld</tag>
            <tag>Dr. No</tag>
            <tag>Scaramanga</tag>
            <tag>goldfinger</tag>
        </tags>
    </contact>
</contacts>
relenta.Contact.CreateOrUpdate

Create or update matched contact

Authentication
This method requires authentication.

Arguments
dp_key (Required) The department key
xml (Required) Xml file content with contact data

Error Codes
500, 'Bad department key'

Example Request (XML)

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8" ?>
<contact>
    <id>22038732</id>
    <first-name>James</first-name>
    <last-name>Bond</last-name>
    <title>Agent</title>
    <company>British Secret Intelligence Service</company>
    <comment>
        007 on an island populated exclusively by women? We won't see him till dawn!
    </comment>
    <created-at>2008-08-31T13:55:04.000Z</created-at>
    <updated-at>2008-12-29T15:48:01.000Z</updated-at>
    <contact-emails>
        <email>james.bond@mi6.gov.uk</email>
    </contact-emails>
    <contact-info>
        <info-block label="Default">
            <info type="phone" label="Cell">+44 43593434534</info>
            <info type="fax">+44 43593434534</info>
            <info type="url" label="Work">www.mi6.uk.gov</info>
            <info type="messenger" label="YIM">james.bond</info>
            <info type="free_form_address">
                PO Box 1300 London SE1 1BD England
            </info>
            <info type="text">Just text field</info>
        </info-block>
        <info-block label="Work">
            <info type="free_form_address" label="HQ">
                PO Box 1300 London SE1 1BD England
            </info>
        </info-block>
    </contact-info>
    <contact-custom-fields>
        <field type="set" name="Type of Business">
            <value>Groomer</value>
            <value>Rescue</value>
        </field>
        <field type="set" name="Paid or Not Paid">
            <value>Paid</value>
        </field>
        <field type="string" name="Waiting for Brochures?">
            Yes
        </field>
        <field type="enum" name="AccountLevel">Level 3</field>
        <field type="date" name="Date Added">
            2007-03-14T05:00:00.000Z
        </field>
        <field type="number" name="Invoice #">
            12381-2893-2964
        </field>
    </contact-custom-fields>
    <contact-groups>
        <group id="686" name="First" category="Level of interest" />
        <group id="687" name="Second" category="Level of interest" unsubscribed="yes" />
        <group id="22014799" name="Sixth" category="Level of interest" unsubscribed="yes" />
        <group id="692" name="Cold calling" category="Source" />
        <group id="1615" name="Email" category="Preferred contact" />
    </contact-groups>
    <tags>
        <tag>Blofeld</tag>
        <tag>Dr. No</tag>
        <tag>Scaramanga</tag>
        <tag>goldfinger</tag>
    </tags>
</contact>

Example Console Commands

Create contact::

curl -u user:password -d 'api_function=relenta.contact.createOrUpdate&dp_key=DP_KEY&xml=<?xml version="1.0" encoding="UTF-8"?><contact><first-name>James</first-name><last- name>Bond</last-name><title>Agent</title><company>British Secret Intelligence Service</company></contact>' http://[account-id].relenta.com/api/rest

Update contact (add fields Phone +44 43593434534 (cell) and URL www.mi6.uk.gov (work)):

curl -u user:password -d 'api_function=relenta.contact.createOrUpdate&dp_key=DP_KEY&xml=<?xml version="1.0" encoding="UTF-8"?><contact><first-name>James</first-name><last- name>Bond</last-name><contact-info><info-block label="Default"><info type="phone" label="Cell">+44 43593434534</info><info type="url" label="Work">www.mi6.uk.gov</info></info-block></contact-info></contact>' http://[account-id].relenta.com/api/rest

Update contact (replace fields Company, Phone (cell) and URL (work)):

curl -u user:password -d 'api_function=relenta.contact.createOrUpdate&dp_key=DP_KEY&xml=<?xml version="1.0" encoding="UTF-8"?><contact><first-name>James</first-name><last- name>Bond</last-name><company>MI6</company><contact-info><info-block label="Default"><info type="phone" label="Cell">+44 (495) 224-22- 22</info><info type="url" label="Work">www.fsb.ru</info></info- block></contact-info></contact>' http://[account-id].relenta.com/api/rest
relenta.Contact.deleteContactsByEmail

Delete contacts matched by email

Authentication
This method requires authentication.

Arguments
dp_key (Required) The department key
email (Required) Email address

Error Codes
500, 'Bad department key'
506, 'No contacts matched this email'
507, 'Error while deleting contacts'

Example Response

<?xml version="1.0" encoding="utf-8" ?>
<response stat="ok">
    <contacts-deleted>1</contacts-deleted>
</response>
relenta.contact.assignGroupsForMatchedContacts

Assign/remove groups for matched contacts

Authentication
This method requires authentication.

Arguments
dp_key (Required) The department key
xml (Required) Xml file content with contact data

Error Codes
500, 'Bad department key'

Example Request

<?xml version="1.0" encoding="UTF-8"?>
<contact>
	<id>22038732</id>
	<first-name>James</first-name>
	<last-name>Bond</last-name>
	<title>Agent</title>
	<company>British Secret Intelligence Service</company>
	<comment>
		007 on an island populated exclusively by women? We won't
		see him till dawn!
	</comment>
	<created-at>2008-08-31T13:55:04.000Z</created-at>
	<updated-at>2008-12-29T15:48:01.000Z</updated-at>
	<contact-emails>
		<email>james.bond@mi6.gov.uk</email>
	</contact-emails>
	<contact-info>
		<info-block label="Default">
			<info type="phone" label="Cell">+44 43593434534</info>
			<info type="fax">+44 43593434534</info>
			<info type="url" label="Work">www.mi6.uk.gov</info>
			<info type="messenger" label="YIM">james.bond</info>
			<info type="free_form_address">
				PO Box 1300 London SE1 1BD England
			</info>
			<info type="text">Just text field</info>
		</info-block>
		<info-block label="Work">
			<info type="free_form_address" label="HQ">
				PO Box 1300 London SE1 1BD England
			</info>
		</info-block>
	</contact-info>
	<contact-custom-fields>
		<field type="set" name="Type of Business">
			<value>Groomer</value>
			<value>Rescue</value>
		</field>
		<field type="set" name="Paid or Not Paid">
			<value>Paid</value>
		</field>
		<field type="string" name="Waiting for Brochures?">
			Yes
		</field>
		<field type="enum" name="AccountLevel">Level 3</field>
		<field type="date" name="Date Added">
			2007-03-14T05:00:00.000Z
		</field>
		<field type="number" name="Invoice #">
			12381-2893-2964
		</field>
	</contact-custom-fields>
	<contact-groups>
		<group id="686" name="First" category="Level of interest" />
		<group id="687" name="Second" category="Level of interest" unsubscribed="yes"/>
		<group id="22014799" name="Sixth" category="Level of interest" unsubscribed="yes"/>
		<group id="692" name="Cold calling" category="Source" />
		<group id="1615" name="Email" category="Preferred contact" />
	</contact-groups>
	<tags>
		<tag>Blofeld</tag>
		<tag>Dr. No</tag>
		<tag>Scaramanga</tag>
		<tag>goldfinger</tag>
	</tags>
</contact>

Example Console Commands

Adding matched contacts to selected contact group(s):

curl -u user:password -d 'api_function=relenta.contact.assignGroupsForMatchedContacts&dp_key=DP_KEY&xml=<?xml version="1.0" encoding="UTF-8"?><contact><contact-emails><email>james@bond.com</email></contact-emails><contact-groups><group id="159436451"/></contact-groups></contact>' http://[account-id].relenta.com/api/rest

Removal of matched contacts from selected contact group(s):

curl -u user:password -d 'api_function=relenta.contact.assignGroupsForMatchedContacts&dp_key=DP_KEY&xml=<?xml version="1.0" encoding="UTF-8"?><contact><contact-emails><email>james@bond.com</email></contact-emails><contact-groups><group id="159436451" remove="yes"/></contact-groups></contact>' http://[account-id].relenta.com/api/rest