© 2015 X2Engine Inc.
Difference between revisions of "Web API Reference (Legacy)"
(→Managing relationships betweeen records) |
(→Miscellaneous API actions) |
||
| Line 161: | Line 161: | ||
|} | |} | ||
| + | == Inbound VoIP call notifications == | ||
| + | PBX systems that are connected to the internet, especially if they are based on [[wiki:Asterisk_(PBX)|Asterisk]], will have the ability to run scripts within their call flow. This opens the possibility of integrating phone systems with X2CRM. 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 <tt>data</tt> parameter is a unique part of a phone number, it won't match the incorrect contact record. | ||
| − | [[x2propdoc:ApiController.html#_actionVoip|actionVoip()]] | + | More information on this method: [[x2propdoc:ApiController.html#_actionVoip|actionVoip()]]. |
| − | + | == Get a list of all users in the app == | |
| − | + | The method [[x2propdoc:ApiController.html#_actionListUsers|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 <tt>x2_users</tt> table. The <tt>password</tt> and <tt>userKey</tt> fields, however, are ommitted from the attributes of all users. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Specifying Model == | == Specifying Model == | ||
Revision as of 00:50, 7 September 2013
X2CRM features a remote API for inserting, updating, querying and deleting records via ApiController, which (with few exceptions) responds in JSON format. The API can perform these operations with any subclass of X2Model. URLs (after the domain name and relative path to the document root) for web requests to the API begin with index.php/api/.
Contents
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. A user's API key can be set by the administrator in the User module by 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.
| Use | Method | URL | Authentication | Request type/data expected | Code | Response properties |
|---|---|---|---|---|---|---|
| Create a new record | actionCreate() | /create/model/Contacts | With post data | POST; authentication & model attributes together in a flat list as URL-encoded form data |
|
|
| Search for the first record matching one or more fields | actionLookup() | /lookup/model/Contacts | With post data | POST; Same as with the create action |
|
If successful: attributes of the model as a flat key-value pair list (indexed by attribute name). Otherwise:
|
| Retrieve a record by primary key | actionView() | /view/Contacts/id/5 | As additional query parameters appended to the URL | GET |
|
Attributes of the model as a flat list indexed by attribute name, if successful. Otherwise:
|
| Update a preexisting record | actionUpdate() | /update/model/Contacts/id/5 | With post data | POST; same as with create method |
|
Same as with create action |
| Delete a record | actionDelete() | /delete/model/Contacts/id/5 | With post data | POST; authentication data |
|
|
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 X2CRM 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: /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:
| Use | Request type/data expected | Codes | Response |
|---|---|---|---|
| Create a relationship | POST with url-encoded form data: secondType (model class of target), firstId (id of the first model), and secondId (id of the target model), in addition to authentication parameters. |
|
|
| Get relationships between two models | GET, with query parameters same as those in creating relationships, and authentication. However, parameters may be omitted to make the query more inclusive, i.e. omitting secondId but setting firstId to 5, model to "Accounts" and secondType to "Contacts" will show all relationships between the Account record with id=5 and contact records. |
|
A list (JSON-encoded, of course) of relationship records (each itself an attribute -> value pair list) |
| Delete a relationship | DELETE<tt>, with everything defined in the query parameters. Behavior is similar to the <tt>GET method; in fact, it can delete multiple relationships at the same time, similarly omitting parameters to make the query more inclusive. |
|
|
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 X2CRM. 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.
Specifying Model
The API requires specifying the model for which the transaction will be performed as a GET parameter with key "model", with actionVoip being the only current exception. Per the URL format rule of X2CRM, which is "path" (see CUrlManager for more information), the full URL of the request will be: index.php/api/[method]/model/[model name]. So, for example, an API call to create a new contact record should use index.php/api/create/model/Contacts
Usage Example
The file leadCapture.php in the web root of the codebase contains a few noteworthy examples of API calls. Of particular significance is the necessity of creating a contact first and then using lookup to obtain its numeric ID in order to create an action associated with that contact.
(section in progress)
