Despite the name, Premium/Sync isn't a premium add-on — it's Epesi's built-in HTTP+XML API for reading and writing Epesi data from outside PHP: another script, an external system, or a plain web form. Nothing else on this site calls it an "API," which makes it easy to miss, but the four scripts documented below (authenticate.php, get_records.php, get_record.php, save_record.php) are the closest thing Epesi has to one.
Premium/Sync lets you access and manipulate any record stored in RecordBrowser, Epesi's CRUD engine. Every script responds in XML. You can retrieve all records in a recordset, a single record with all its fields, or every record changed since a given timestamp — and you can add new records or edit existing ones, with a dirty-read safeguard against overwriting concurrent changes.
Two scenarios come up most:
The Premium/Sync module must be installed in Epesi for any of this to work — every script checks for that and blocks access entirely if it isn't.
If you're using Premium/Sync for system integration, every external-system user should have a matching Epesi user, and every action should be attributed to that user's login and password. For a simple web interface instead, we recommend creating one dedicated Epesi user whose credentials the interface uses for all requests.
Which fields you sync is entirely up to you — every field is available through Premium/Sync, including custom fields added after the fact.
All scripts read parameters from $_REQUEST, so both POST and GET work. This page uses GET in its examples.
Scripts live under modules/Premium/Sync. If Epesi is served from http://<epesi>/, you'd call a script at http://<epesi>/modules/Premium/Sync/script_name.php. From here on, this page refers to scripts by name only — adjust the URL accordingly.
Every Premium/Sync request requires authentication: your username, plus the MD5 hash of your password, sent with every call. To get that hash:
<?php print(md5('your password here')); ?>Check that your credentials work with authenticate.php:
authenticate.php?login=yourlogin&password=md5passwordA successful response looks like:
<response>OK</response>On failure:
<response>ERROR</response>The error code tells you what went wrong:
login or password missing (check for typos)Basics
Use get_records.php to retrieve multiple records. It requires login, password, and module_id — module_id is the recordset's name in Epesi (contact, company, crm_meeting, etc.).
A response looks like this (example from contact):
<records>
<record>
<module>contact</module>
<id>1</id>
<primarylabel>Smith</primarylabel>
</record>
<record>
<module>contact</module>
<id>2</id>
<primarylabel>Doe</primarylabel>
</record>
...
</records>The part that matters is id. primarylabel is a text label RecordBrowser generates automatically — to get the rest of a record's data, retrieve it individually (see below).
Changes since a timestamp
get_records.php also accepts an optional last_sync_date parameter, formatted as Y-m-d H:i:s (e.g. 1970-01-01 00:00:00). With it, Premium/Sync returns only records created or modified at or after that timestamp — including deleted ones, which get an extra tag:
<action>DELETED</action>last_sync_date is what makes incremental sync possible, instead of pulling the full recordset every time.
Use get_record.php, with login, password, module_id, and record_id (an integer — the record's internal Epesi ID). A successful response looks like:
<record>
<field>
<id>last_name</id>
<label>Last Name</label>
<value>Bisaga</value>
<rawvalue>Bisaga</rawvalue>
<permission>full</permission>
<type>text</type>
<required>1</required>
<param>
<maxlength>64</maxlength>
</param>
</field>
<field>
<id>first_name</id>
<label>First Name</label>
<value>Arkadiusz</value>
<rawvalue>Arkadiusz</rawvalue>
<permission>full</permission>
<type>text</type>
<required>1</required>
<param>
<maxlength>64</maxlength>
</param>
</field>
...
</record>Each field gets its own <field> section:
full or read-only1 if the field must have a value when editing in Epesi (this doesn't affect sync), 0 otherwisevalue and rawvalue diverge for select-type fields and similar: rawvalue holds the ID (or IDs) of the linked record(s), while value holds the label of whatever's referenced.
An invalid record_id returns:
<response>RECORD_NOT_FOUND</response>Basics
Use save_record.php to create or update a record — it requires login, password, module_id, and record_id. The two cases are nearly identical: to create a new record, set record_id=NEW (case-sensitive); to update an existing one, set record_id to that record's ID and also supply last_sync_date (formatted Y-m-d H:i:s), which guards against overwriting changes made since you last read the record. To force a full overwrite regardless, set last_sync_date to the current timestamp.
Add any fields you want to set as f_<field_name> parameters. For example, to change contact 15's first name:
save_record.php?login=yourlogin&password=md5password&module_id=contact&record_id=15&last_sync_date=2012-02-08+12:00:00&f_first_name=ThomasThis changes contact 15's first name to Thomas, leaving every other field untouched.
On success, the response depends on whether this was a new record or an update. For an update:
<response>OK</response>For a new record:
<response>ID</response>where ID is the newly created record's ID.
Using save_record.php in a web form
You can point a plain HTML form's action straight at save_record.php, but we don't recommend it. First, the user's login and MD5 password would have to live in the form itself, exposing those credentials. Second, the user gets no real feedback — just a bare
<response>OK</response>Instead, point the form at your own script. Have that script parse the submission, attach the login, MD5 password, and module_id, and forward the request to save_record.php — then show the user something meaningful based on the response. In PHP, file_get_contents('(...)/save_record.php?' . http_build_query($params)) works, provided allow_url_fopen is enabled in php.ini; otherwise, use curl.
This keeps the sensitive credentials out of the user's hands, and gives you control over what they see after submitting the form.