API overview

 

This document describes the Symplify public API and how to get started trying it out. Readers are assumed to have some familiarity with Symplify's graphical interface.

The API uses the REST methodology. A brief overview of RESTful web services can be found here:
http://net.tutsplus.com/tutorials/other/a-beginners-introduction-to-http-and-rest/

 

While you're looking into integration options, please also take a moment to read about our Event Hub, which is our prefered method for real time data updates.

 

API documentation

Symplify uses a third-party library called Swagger to document the REST API. This documentation is built based on the actual code and this should ensure that the documentation will always be up to date. There will be no printed version of the API; the version that is accessible via the link is the latest and current version.

Online Resources

You will find the online version of the API at:

https://<server>/mail/swagger

If you have user credentials for Symplify you can actually access and update your data using the methods described on the swagger page.

In order to do this you must use the swagger page on the server your account is on, log in to Symplify and find your server in the main menu bottom.
Example, replace <server> in the URL above with e.g www2.carmamail.com (if this is your server):

https://www2.carmamail.com/mail/swagger

For North America use:

https://nam-proxy.symplifymail.com/mail/swagger

Please note that this is your live data so any updates you make will alter settings for other users of your account so use POST/PUT and DELETE with care.

Evolution of the API

We will strive to keep the API backward compatible. This applies to all API calls that are not explicitly marked as draft or FOR INTERNAL USE ONLY in the Swagger documentation. This means that:

  1. Resource URIs not will not change
  2. Names of data fields in message body requests and responses will not change
  3. Data fields in message body requests and responses will not be removed
  4. New optional fields in message body requests and responses may be added in the future. Integrating systems should take this account, particularly when consuming responses from the REST API.
  5. New resources will be added as new functionality is made publicly available
  6. If incompatible changes are required in existing resources, the old ones will still be left available, unless the conditions under 7 apply.
  7. In some very unusual cases, internal changes in the system may render existing resources obsolete or insufficient for the task they were originally intended. In these cases the original resource will be left in place, but will be modified to return the HTTP response code 410 (Gone), with a response body including information on the reason.


Customer ID

You must always include your customerId when calling a Symplify resource. Log in to Symplify and find your customer ID in the main menu bottom


Syntax

For most resources there are five methods you can call; get all, get one, create one, update one and delete one The syntax is mostly the same for all resources so you should be able to pick up the general idea pretty quick.

The URI structure generally looks like this:

<server>/rest/{customerid}/<resource>/[{id}]

server: https://www<x>.carmamail.com where X is the number of your server

customerId: your customer ID.

resource: the resource you want to use

id: the ID (if any) of the item you want to add/update/get/delete. 

Example:

 <server>/rest/{customerid}/reports/campaigns/{id}

Media Type

All data supplied to and received from the REST API uses the application/json media type. To ensure full compatibility, please make sure that:​

All GET requests include the header:

Accept: application/json

All PUT and POST request include the following headers:

Accept: application/json
Content-Type: application/json

All data sent to the API is expected to be in the standard application/json charset UTF-8, unless explicitly stated otherwise as a charset parameter in the Content-Type header. All data sent as responses from the API will be in the UTF-8 charset.

Types of Requests


Get All

To get all data you issue a GET request without id, e.g.

GET https://www<server>.carmamail.com/rest/<customerId>/projects
Accept: application/json

Get One

To get one data you issue a GET reqest with an id, e.g.​

GET https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>
​Accept: application/json

Create One

To create a new data you will issue a POST request without id. Usually creation of a new entity will require data for the entity to be included in the message body, e.g.:

POST https://www<server>.carmamail.com/rest/<customerId>/projects
Accept: application/json
Content-Type: application/json
Content-Length: …
<entity to create as JSON>

Update One

To update one data you issue a PUT request with id and the data required to be used for updating the entity:

PUT https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>
Accept: application/json
Content-Type: application/json
Content-Length: …
<entity to update as JSON>

Delete one

To delete you issue a DELETE request with an id, i.e.

DELETE https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>

api-1.png

 

Testing Requests

You can test a request directly in the Swagger interface by entering your credentials, customer id and other data needed for the method.

Credentials

For testing you can use the same credentials that you use to log into Symplify. For security reasons we recommend not using your own credentials in production. The recommendation for production is to get a special API user for your account and use these credentials. You can request an API user by sending an email to support@symplify.com.

GET Requests

GET requests are used to retrieve data from the system.

If you, for instance, want to retrieve all your projects you will first need to expand the projects:

api-2.png
You then click on the last entry to expand it, it will show you the following view:

api-3.pngIf you enter your customer id and click on Try it out you will be asked for you credentials. Enter them and click ok, and you will get back a JSON formatted response with the information about your projects.

api-4.png

POST Requests

POST requests are used to create data in the system.

When issuing a POST you often have to supply a JSON formatted message body containing the data for the entity you are creating. You can see the syntax of the model that will be returned by clicking Model Schema for the POST method.

api-5.png

To issue a POST you can get the input schema by clicking Model schema for the resource.

api-6.png

Copy the schema to the input field, by clicking on the text under the yellow box and fill in the required information.

Note! You should not include the “id”, “dateCreated”or “dateModified” fields as they are created automatically by the server. You can safely remove fields that you do not have data for, e.g. if you do not have data for Contact.MiddleName, that field can be removed from the input Json struct. You will get a validation error if you remove amandatory field.

PUT Requests

PUT requests are used for updating data in the database. The message body should include data required for updating the entity. For some resources you only need to specify the fields that you are changing, but usually you should make sure to include all fields as received from a previous GET request (once again, the id, dateCreated and dateModified fields are not required. The Id field this is specified in the URI and the other are created/updated automatically).

api-7.png

DELETE Requests

To delete an entry you supply the customer id and the id of the data to be deleted.

api-8.png

Domain description

​All methods in Symplify are a part of a domain, below the domains are listed with a brief description of the methods and a link to the swagger documentation of the domain.
The link points out server 3, but you can easily replace the first part of the domain name in order to get to your server.

Was this article helpful?
0 out of 0 found this helpful