Authenticating

In most calls to the API, authentication is required in the form of GET or POST parameters user and userKey, which are the username and API key (respectively) of a user in the CRM. In versions earlier than 2.9.1, these parameters are named authUser and authPassword, and authPassword is the password hash.

Getting and Setting API Keys

A user's API key can be set (or looked up) by the administrator, by (in the Users module) visiting the Update page for the given user.

CRUD (Create, Read, Update & Delete) API Methods

The following API actions can be used with any subclass of X2Model (i.e. Contacts, Accounts, Opportunity, etc.) In the following reference table, the model class to be used for display purposes is Contacts, and the id (primary key) value is 5.

Attribute Input Format

The input to the API will be processed in the same way that it is within the application, that is to say, using the method X2Model.setX2Fields(). In particular, the method Fields.parseValue() is used for processing and transforming the data before it is recorded in the database. The case statement in that method shows how each type of field is processed (see X2Model and Dynamic Fields for more information on field types and how fields are dynamically managed)

Miscellaneous API actions

Managing relationships betweeen records

One can create, get lists of and delete relationships between records in X2Engine by using the actionRelationship() method. Of all the API methods, this is one of the most recently-created; creation, retrieval and deletion of relationships all happen through the same URL: index.php/api/relationship/model/Contacts (for relating to models of class Contacts). This is an effort to shift in the direction of an ultimately more REST-ful and clean API. The following table describes its uses and responses:

Tagging Records

Child classes of X2Model can be tagged, and tagging can be done through the API action actionTags() at the URL index.php/api/tags/model/Contacts/id/5 (to add tags to contact #5, for instance). The following describes how to use the action:

Example: add tag "customer" to the contact with ID equal to 71:

• Make the request to index.php/api/tags/model/Contacts/id/71
• Request type POST
• Send with post data "user","userKey" (authentication parameters) and "tag" set to "customer".

Or, with two tags, "customer" and "active":

• Request to index.php/api/tags/model/Contacts/id/71
• Request type POST
• Post data includes the usual authentication parameters, and "tags", which should be the JSON-encoded list of tags:

  ["customer","active"]
  

Inbound VoIP call notifications

PBX systems that are connected to the internet, especially if they are based on Asterisk, will have the ability to run scripts within their call flow. This opens the possibility of integrating phone systems with X2Engine. The action api/voip, which does not require authentication, is the most basic way of doing so where all that is necessary is to notify sales reps when a contact is calling. This gives the rep a window of few seconds (depending on the dialplan, and if the caller is typing in someone's extension directly) to get ready to receive the call when it finally reaches them. It creates notifications for all users (if assigned to "Anyone"), an activity feed event, and if the contact is assigned to someone, it opens a new window with the record on screen in that rep's web browser.

To use it, make a GET request to index.php/api/voip/data/{phone number}, where {phone number} is the caller ID (without spaces, parentheses or dashes) calling in. Note, it may yield better results if the country code is ommitted; the search for contacts is based on serialized phone numbers but also returns the first partial match. So, as long as the data parameter is a unique part of a phone number, it won't match the incorrect contact record.

More information on this method: actionVoip().

Get a list of all users in the app

The method actionListUsers() (accessed via GET at /api/listUsers) requires authentication (as query parameters) and will return with HTTP code 403 if the user used for authenticating does not have permission to the UsersIndex RBAC action. It returns, upon success, a JSON-encoded list of users, each user a list of attribute name to attribute value key/value pairs (according to the columns of the x2_users table. The password and userKey fields, however, are ommitted from the attributes of all users.

Security Considerations

It is in general considered a best practice to securely encrypt web traffic to your web server with HTTP over SSL(a.k.a Transport Layer Security) a method of connecting to a remote network host that encrypts traffic on any given network protocol that uses it. (HTTPS). Without this, API authentication credentials will be sent directly to the server in plain text, and thus vulnerable to exposure via man-in-the-middle (MITM) attacks and packet sniffing. Note, however, that if HTTPS is not used on the server, normal web-browser authentication would also be vulnerable to this kind of attack anyway, because the session ID stored in the cookie can similarly be stolen and used to access the system as any given user.

If SSL(a.k.a Transport Layer Security) a method of connecting to a remote network host that encrypts traffic on any given network protocol that uses it.-protected HTTP is not an option due to the cost, it is thus recommended that you keep all of your API requests within the same server or intranet and/or behind a firewall, as that would mean that both the origin and target of the API web request would be within a protected network area, and thus would more difficult to access.