Getting Started with Engage API

1) User Creation

If you do not have an API (Or hybrid) User account, one must be created. Any user who has user creation permission can create an API user account. 

1. In Mapp Engage, select User Management > System User > System User

2. In the System Users Screen, Select Create

3. Under the Type drop-down, select API User

4. Enter your API user's contact details, and make sure the Role is set to Client Administrator. 

5. Select Save

For more information on this, please see New System User.

2) Sending A Request

Authorization & Permissions

Both SOAP and REST APIs use HTTP basic authentication methods that does not require cookies or session tokens. For this reason, there are no explicit login and logout methods.
Instead, the authorization header (encoded in Base64) must be included in each API request. You can create this yourself based on the username and password of the API User in your specific platform.

The example header for 'j.mcexample@example.com' user and 'ThisizAstr0ngPswrd!!_' password is the following:

Authorization: Basic ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf

Host header

Users connecting to the Mapp Engage API should ensure that their web service clients correctly add or include the Host header in the HTTP header. The domain name sent in the HTTP header must be identical to the web service URL you are connecting to. Our web services require that the host header value be set as this will be used along and in parallel with the requested URL when connecting to our servers.

Host: yourdomain.com

Without this host header, there could be issues when connecting to the correct service and server, and it could also trip our anti-intrusion systems.

In the example below, not only is the HTTP REST request being requested by GET to the domain cook.shortest-route.com but in the HTTP header, the corresponding virtual host is also specified in the "Host" field.

GET https://yourdomain.com/api/rest/v9/contact/anonymize?contactId=12345678901¬ificationRecipient=system.user@example.tld HTTP/1.1

Host: yousdomain.com.com

User-Agent: Rest Webservice Test Client 1.0

Accept: application/json

Accept-Language: en-US,en;q=0.5

Accept-Encoding: gzip, deflate, br

Content-Type: application/json

Authorization: Basic QXNJZklXb3VsZFB1dEFSZWFsVXNlcm5hbWVIZXJlOlRoaXNJc05vdEFQYXNzd29yZA==

Connection: keep-alive

Pragma: no-cache

Cache-Control: no-cache

Domains

API calls are grouped within functional test domains. A full list of domains and calls can be found in our Swagger documentation. You can also find the domains below. 

Versioning

Contact Mapp Technical Support to confirm if you have the latest version. At the moment this is v19.

3) Testing

Here are some outside tools which may help you get started using API: