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:
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.
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.
You will find the online version of the API at:
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):
For North America use:
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:
- Resource URIs not will not change
- Names of data fields in message body requests and responses will not change
- Data fields in message body requests and responses will not be removed
- 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.
- New resources will be added as new functionality is made publicly available
- If incompatible changes are required in existing resources, the old ones will still be left available, unless the conditions under 7 apply.
- 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.
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
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: 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.
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:
All PUT and POST request include the following headers:
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
To get all data you issue a GET request without id, e.g.
To get one data you issue a GET reqest with an id, e.g.
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.:
<entity to create as JSON>
To update one data you issue a PUT request with id and the data required to be used for updating the entity:
<entity to update as JSON>
To delete you issue a DELETE request with an id, i.e.
You can test a request directly in the Swagger interface by entering your credentials, customer id and other data needed for the method.
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 firstname.lastname@example.org.
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:
You then click on the last entry to expand it, it will show you the following view:
If 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.
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.
To issue a POST you can get the input schema by clicking Model schema for the resource.
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 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).
To delete an entry you supply the customer id and the id of the data to be deleted.
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.