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
