Last Update: 2019-10-02

Introduction

The following is a guideline to the standard eyepin interface. This interface gives you the opportunity to handle data in booth directions - import and export data records from your CMS/CRM to eyepin and vice versa.

It's reasonable that most customers prefer to use their own CMS/CRM to track their company related content (e.g. addresses, articles).

The data transfer takes place via XML-Records (Extended Markup Language). Depending on what you intend to do, there are special commands for altering (edit, remove, add) data records, which will be explained in this document later.

The idea is very simple, a URL is called which pass the data/request to eyepin and you get a response back (Response XML).

Further more there are so called event-handlers, which can perform actions (e.g. calling a url with passing data) when something happens to the eyepin user database (e.g. someone changing his personal information).

Request

Send a XML as POST-parameter via HTTP-Request.

  • The XML specifies the API-Command and it's parameters or data.
  • The name of the POST-parameter does not matter, the first POST-parameter is always taken.
  • The name of the XML root-element specifies the API-Command.

URL

https://apiv3.eyepin.com/interface3.php

Security

  • Login via basic-authentication
  • The username and password used in the interface authentication is different from your normal eyepin username and password.

Info: If you don't have access to the interface username and password, eyepin Support can reset your password and send username and the new password to you.

Specify customer (only with suite-manager access-data)

You can specify the customer for each request within the root-element
e.g.: <addressinsert customerid="">...</addressinsert>

Example Request

A simple example in PHP and the cURL extension that shows how to subscribe a contact.

$url = 'https://apiv3.eyepin.com/interface3.php';
$username = 'USERNAME';
$password = 'PASSWORD';

$request = '
  <?xml version="1.0" encoding="utf-8"?>
  <addressinsert>
    <email>max.mustermann@eyepin.com</email>
    <salutation>male</salutation>
    <firstname>Max</firstname>
    <lastname>Mustermann</lastname>
    <status>1</status>
  </addressinsert>
';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: text/xml'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);
$ErrNum = curl_errno($ch);
$ErrMsg = curl_error($ch);
curl_close($ch);

if ($ErrNum != 0) {
  die('Error cURL: ' . $ErrMsg);
}

$xml = simplexml_load_string($response, null, LIBXML_NOCDATA);
if (!$xml) {
  die('Error: Cannot parse response-XML');
}

if ((string)$xml->code !== '2000') {
  die((string)$xml->description);
}

echo 'Success! Contact with id=' . (string)$xml->data . ' created.';

Response

Each request returns a XML in the following form:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <code></code>
  <description></description>
  <data></data>
  <paging>
    <page></page>
    <pagesize></pagesize>
    <prev></prev>
    <next></next>
    <last></last>
    <numrecords></numrecords>
  </paging>
</response>
Element Format Description
response->code 4-digits Success- or Error-Code
response->description varchar(255) description of the returned code
response->data string or xml Optional; Depending on the request a single value or a xml-structure is returned
response->paging   Optional; Some requests return big results which will be splitted in pages
response->paging->page Number of current page
response->paging->pagesize Number of records per page
response->paging->prev Number of previous page (empty if there's no previous page)
response->paging->next Number of next page (empty if there's no next page)
response->paging->last Number of last page
response->paging->numrecords int(10) Total number of all records

Common Response-Codes

Code Description
2000 OK
3001 Database error
3002 Error: Access from this IP denied
3004 Error: Request-XML missing
3005 Error: Username and/or password wrong
3006 Error: Command needs authentification
3007 Error: Cannot parse XML
3008 Error: Unknown request
3009 Error: Command is not available any more
3010 Error: Command needs admin privileges
3011 Error: Paramater missing
3012 Error: Paramater invalid
Für Rückfragen stehen wir Ihnen jederzeit gerne unter support@eyepin.com zur Verfügung.