Authentication
A contact person can be logged in using the following request.
curl http://hostname/webservice/contacts/authenticate \ -u webservice:apikey \ -X POST \ --form-string authentication[login]=login \ --form-string authentication[password]=password
If the login credentials are valid, the OMC returns the data of the contact person. The data is returned in the same format as with queries by ID (see below).
In case of errors, the OMC returns the status code 422 and the following message in the body of the response:
<?xml version="1.0" encoding="UTF-8"?> <errors> <error>Authentication failed.</error> </errors>
Retrieving Lists of Contact Persons
You can have the OMC return the list of all contact persons, or of all the persons associated with a particular account:
curl http://hostname/webservice/contacts \ -u webservice:apikey \ -G curl http://hostname/webservice/contacts \ -u webservice:apikey \ -G \ -d filter[account_id]=4
The OMC returns the contact persons as contact elements enclosed in a contacts element. Example:
<?xml version="1.0" encoding="UTF-8"?> <contacts type="array"> <contact> <job_title>Einkäufer</job_title> <title>Dr.</title> <updated_at type="datetime">2010-11-29T19:12:34+01:00</updated_at> <salutation>Sehr geehrte Frau Doktor Beck</salutation> <language>de</language> <want_email type="boolean">true</want_email> <account_id type="integer">4</account_id> <letter_address>Frau Dr. Katrin Beck</letter_address> <gender>F</gender> <id type="integer">282</id> <greeting>Frau Doktor Beck</greeting> <fax>+49 6659 3839575</fax> <phone>+49 6659 7103442</phone> <location_id type="integer">54</location_id> <last_name>Beck</last_name> <want_snailmail type="boolean">true</want_snailmail> <roles type="array"/> <login>Katrin.Beck@oezs-spielkiste.com</login> <want_phonecall type="boolean">true</want_phonecall> <email>Katrin.Beck@oezs-spielkiste.com</email> <mobile_phone>+49 166 8371439</mobile_phone> <first_name>Katrin</first_name> <active type="boolean">true</active> </contact> <contact> ... </contact> </contacts>
By means of the following parameters you can have additional data included in the result:
include[]="location" includes for every contact person their respective location.include[]="account" includes for every contact person the data of the account they belong to.filter[]="include_inactive" includes inactive contact persons.Retrieving Contact Person Data
You can retrieve the data of a particular contact person by means of her ID or user name:
curl http://hostname/webservice/contacts/id \ -u webservice:apikey curl http://hostname/webservice/contacts/validate_login \ -u webservice:apikey \ -G \ -d login=login
If the contact referred to exists, the OMC returns an XML document that contains the contact’s data in the contact element. Example:
<?xml version="1.0" encoding="UTF-8"?> <contact> <job_title>Einkäufer</job_title> <title>Dr.</title> <updated_at type="datetime">2010-11-29T19:12:35+01:00</updated_at> <salutation>Dear Doctor Heinen</salutation> <language>en</language> <want_email type="boolean">true</want_email> <account_id type="integer">55</account_id> <letter_address>Mr. Dr. Bernd Heinen</letter_address> <gender>M</gender> <id type="integer">288</id> <greeting>Doctor Heinen</greeting> <fax>+49 6659 9831004</fax> <phone>+49 6659 2863019</phone> <location_id type="integer">55</location_id> <last_name>Heinen</last_name> <want_snailmail type="boolean">true</want_snailmail> <roles type="array"/> <login>Bernd.Heinen@babystaet.com</login> <want_phonecall type="boolean">true</want_phonecall> <email>Bernd.Heinen@babystaet.com</email> <mobile_phone>+49 169 8412311</mobile_phone> <first_name>Bernd</first_name> <active type="boolean">true</active> </contact>
If the value of the contact_want_webservice_roles_from_subscription_names key in the General Configuration of the OMC is true, an additional field, roles, is returned. The value of this field is the list of the named collections the person is part of.
As with contact person lists, you can use the parameters -d include[]="location" and -d include[]="account" to have the person’s location and account data included.
Creating a Contact Person
A contact can be created and assigned to an account using a POST request in which the relevant parameters are given.
Next to the account ID, the pieces of information mandatory for creating a contact person are: the person's last name (last_name), gender (gender: F, M, or N), and language (language). The languages available are part of the general configuration settings.
curl http://hostname/webservice/contacts \ -u webservice:apikey \ -X POST \ --form-string contact[account_id]=4 \ --form-string contact[last_name]=Hans \ --form-string contact[first_name]=Muster \ --form-string contact[gender]=M \ --form-string contact[location_id]=true \ --form-string contact[want_email]=true \ --form-string contact[want_phonecall]=true \ --form-string contact[want_snailmail]=true \ --form-string contact[language]=de \ --form-string contact[active]=true
As the result, the contact person’s data is returned.
When creating a contact person, an account and a location can be created simultaneously, i.e. with the same query. For this, the account_id parameter must be omitted, and the following parameters need to be added:
--form-string contact[account_attributes][name]='Account Name' \ --form-string contact[location_attributes][city]='City Name' \ --form-string contact[location_attributes][want_assign_geoloc]='false'
Modifying a Contact Person’s Data
To modify the data of a contact person, use a PUT request and specify the contact’s ID in the URL and the fields to be modified in the body of the request.
curl http://hostname/webservice/contacts/id \ -u webservice:apikey \ -X PUT \ --form-string contact[last_name]="Smith" \ --form-string contact[login]=example4352 \ --form-string contact[email]="smith@example.com" \ --form-string contact[first_name]="Mary"
The return value is the same as for queries for the contact person’s data.
Find Newsletter Subscribers
curl http://hostname/webservice/contacts \ -u webservice:apikey \ -G \ -d filter[collection_name]=tips_tricks
The result is the list of the persons who are contained in the contact person collection specified.
Retrieving a Contact Person’s Newsletter Subscriptions
curl http://hostname/webservice/contacts/id/subscriptions \ -u webservice:apikey
The OMC returns a subscriptions element that contains the subscriptions as subscription elements.
<?xml version="1.0" encoding="UTF-8"?> <subscriptions type="array"> <subscription> <title>News</title> <name>News</name> </subscription> </subscriptions>
Determining the Available Newsletters
curl http://hostname/webservice/contacts/all_subscriptions \ -u webservice:apikey
Again, the result is a subscriptions element with subscription subelements. Each of them contains the name of a newsletter to which contact persons may potentially subscribe or are already subscribed to.
<?xml version="1.0" encoding="UTF-8"?> <subscriptions type="array"> <subscription> <name>News</name> </subscription> <subscription> <name>Latest_News</name> </subscription> <subscription> <name>vorstellung</name> </subscription> </subscriptions>
Setting a Contact Person’s Newsletter Subscriptions
A contact person’s newsletter subscriptions can be set with one webservice call. Existing subscriptions will be automatically removed before the specified subscriptions are stored.
curl http://hostname/webservice/contacts/id/update_subscriptions \ -u webservice:apikey \ -X PUT \ --form-string subscriptions[][name]=News \ --form-string subscriptions[][name]=Latest_News
The result is the same as for queries for a contact person’s subscriptions.
The individual diary entries of contact persons can only be accessed by means of the web interface of the OMC. However, using a webservice call, a diary entry can be added to a contact person.
Adding a Diary Entry for a Contact Person
curl http://hostname/webservice/diaries \ -u webservice:apikey \ -X POST \ --form-string diary[type]=web \ --form-string diary[title]="Kommentar abgegeben" \ --form-string diary[notes]="Super Seite!" \ --form-string diary[internal]=false \ --form-string diary[contact_id]=id
This returns the new diary entry:
<?xml version="1.0" encoding="UTF-8"?> <diary> <account_id type="integer">1</account_id> <contact_id type="integer">4</contact_id> <created_at type="datetime">2010-07-13T15:18:41+02:00</created_at> <created_by>webservice</created_by> <diary_type>web</diary_type> <id type="integer">11</id> <internal type="boolean">false</internal> <notes>Super Seite!</notes> <send_email type="boolean">false</send_email> <summary>Kommentar abgegeben</summary> <updated_at type="datetime">2010-07-13T15:18:41+02:00</updated_at> <updated_by>webservice</updated_by> </diary>
Creating and Storing a Password for a Contact Person
Please note that the new password is sent to the contact via e-mail if her e-mail address was defined before and the system is configured to send e-mail.
curl http://hostname/webservice/contacts/id/generate_password \ -u webservice:apikey \ -X POST \ --form-string password[email_options][option1]=Option 1 \ --form-string password[email_options][option2]=Option 2
Setting a Contact Person’s Password
curl http://hostname/webservice/contacts/id/update_password \ -u webservice:apikey \ -X PUT \ --form-string password[old]=old_password \ --form-string password[new]=new_password
Retrieving Settings
By means of the following request, settings such as the available newsletters, salutations, and languages can be retrieved:
curl http://hostname/webservice/contacts/lookup_options \ -u webservice:apikey
This call returns an XML document that contains these settings in the lookup_options element. Example:
<?xml version="1.0" encoding="UTF-8"?> <lookup_options> <languages type="array"> <language> <name>de</name> </language> <language> <name>en</name> </language> </languages> <subscriptions type="array"> <subscription> <name>News</name> </subscription> <subscription> <name>Latest_News</name> </subscription> </subscriptions> <titles type="array"> <title> <name></name> </title> <title> <name>Dr.</name> </title> <title> <name>Prof.</name> </title> </titles> </lookup_options>