Home

Search the wiki

»

API Documentation


Mobile Payment

LINK Engage REST API

RSS
The Link Engage API provides a simple yet powerful interface to the central features of the PSWinCom Link Engage product. It can be used to automate tasks like synchronizing contacts, facilitate custom SMS services, or even implement alternative user interfaces.

The API is a REST-interface. It's “firewall-friendly” since it's running over the standard HTTP protocol and port number 80 is used for client connections. For data transfer it supports both XML and json.

The old version of the API can be found at http://intouchapi.pswin.com/1/

Usage

TODO: How to perform requests, bad results (status code 406) etc. Better exceptions to come. Unicode/UTF-8.

Status codes

HTTP status codes are used to give callers information about the result of API requests. In particular the following codes should be expected:

  • 200 OK
    This is the standard response given on successful requests, reguardless of HTTML method used.
  • 204 OK, but No Content
    The server successfully processed the request, but is not returning any content. In our API this is typically used in PUT and DELETE requests, when we don't see a need for returning any updated data.
  • 400 Bad Request
    This will usually be returned if the request does not make sense to us, and we are unable to perform the action. Typically it's used when the data sent in a POST or PUT is invalid.
  • 404 Not Found
    The requested resource could not be found. Typically you have requested an element by id, but that element either does not exist or is not accessible to your user. Or you have simply requested an endpoint that does not exist.
  • 405 Method Not Allowed
    Could be a result of accessing an endpoint like /contacs/{id}, but using a string (text) as the id instead of a number (integer).
  • 406 Not Acceptable
    This status will be returned if authentication or authorization fails. It can also be returned for some undefined exceptions. For exmaple if the parameters are wrong, or in wrong case (parameters are Case-Sensitive).
  • 500 Internal Server Error
    Some unforeseen error happened on the server.

Resources

The API can be divided into several top-level resources, which are:

  • User - read-only data about the current user, including organization information and settings.
  • Contacts - complete administration of contacts, including search.
  • Groups - complete administration of groups, and the contacts therein.
  • Messages - get, delete and send SMS messages.
  • Folders - read-only access to folder tree and messages in folder.

Authentication and access control

Use of the API is always through an existing Intouch user account. There’s no special API user. You get to see and work with what the user you are logging in to the API is allowed to. To use the API you’re required to add user credentials via HTTP Basic Access Authentication. In addition your user account or organization must have the API feature enabled. If it's not you will have to contact PSWinCom Support by email to enable it.

Using plain HTTP should be done with caution when dealing with information. All data are sent as clear text over the Internet and may be intercepted by a third-party. To increase security, the SSL secured transport layer (HTTPS) can be used. See SSL certificates for details.

When authenticating through Basic Authentication the username should be constructed from your Intouch username and your Intouch domain. Here's an example

Intouch user: MrJohnson
Intouch domain: acme.com
Intouch password: abc123

Username to be used in authentication: MrJohnson@acme.com
Complete authentication token before encoding: MrJohnson@acme.com:abc123

The base-64 encoded value of the token is used in the request header. See the example clients for more details on how to implement the authentication.

Versioning

When introducing breaking changes to the API PSWinCom will if possible provide a new URL for the new version, leaving the existing one in place. This documentation will always reflect the features of the latest version.

Support for limited clients

Clients implemented in technologies unable to use REST methods like PUT and DELETE (e.g. FLASH) can still utilize the full Intouch API. To do so the client has to use the POST method while adding the special X-HTTP-Method-Override header to the requests. For a PUT operation the header should be:

X-HTTP-Method-Override:PUT

API Throttle

To ensure continuous quality of service, API usage can be subject to throttling. The throttle will be applied once an API consumer reaches a certain threshold in terms of a maximum of requests per minute. Most clients will never hit this threshold, but those that do, will get met by a HTTP 503 response code and a text body of “Number of allowed API requests per minute exceeded”

We encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).

Example clients

We have implemented some sample clients to give you an idea of how to use the API. Unless otherwise noted, all source code referenced below is public domain, and may be freely distributed, modified, and used for any purpose. IT COMES WITH ABSOLUTELY NO WARRANTY OF ANY KIND.


External resources

Gateway interfaces: | XML | HTTP | SMTP | SOAP | SFTP BatchLoader
Intouch interfaces: REST | Syncopy

© Copyright Link Mobility ASA.





GuestLogin