Getting Started with Engage API
  • 2 Minutes to read
  • Dark
    Light

Getting Started with Engage API

  • Dark
    Light

Article summary

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

Please note, that while hybrid users can be used for API accounts, we do not recommend this approach. The separation of API and User Interface users and their activities in your company's account makes it much easier to see who exactly made the changes. 

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

Only API and Hybrid user credentials can be used to build this Basic Auth Header to be used in the API call. 

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. 

 Click here to expand...

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:

SoapUI

An open-source web service testing tool

Download and install

Postman

Download and install

Postman Collection

See our Use Cases for sample Postman Collections

To setup REST project

Example REST project


Was this article helpful?