Contents x
    Getting Started with Engage API
    • 3 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Getting Started with Engage API

    • 3 Minutes to read
    • Print
    • 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 don’t recommend this approach especially in production environments for security reasons. 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 which changes.

    For more information, please see New System User.

    2) Building and Making Calls

    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 authorization 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. 

    Required Headers

    The API requires 4 header values that should be present in each API call:

    • Host: Your Engage domain name hosting the API you are connecting to

    • Accept: application/json or application/xml

    • Content-Type: application/json or application/xml

    • Authorization: Basic

    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: subdomain.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.

    Accept and Content-Type headers

    The REST API supports JSON or XML.

    • Accept: denotes the format of data submitted to Engage by POST. This does not apply to query parameters sent in the URL.

    • Content-Type: denotes the format of any data returned by Engage in response to a query.

    Authorization header

    Both SOAP and REST APIs use HTTP basic authentication methods that don’t require cookies or session tokens. For this reason, there are no explicit login and logout methods.
    Instead, the authorization header must be included in each API request. You can create this yourself based on the username and password of a system user set up with either the API or Hybrid roles in your specific platform. This header contains the keyword Authorization and the value Basic and a credential string. The credential string is comprissed of your Engage API role system user email address and password, separated by a colon.

    Based on our previous example with the system user “j.mcexample@example.com“ and the corresponding password “ThisizAstr0ngPswrd!!_“ would make the following unencoded authorization string:

    j.mcexample@example.com:ThisizAstr0ngPswrd!!_

    Once base64 encoded we have:

    ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf

    Finally making the full header:

    Authorization: Basic ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf

    Example call

    Combining the call and headers will create something like this:

    GET https://subdomain.yourdomain.com/api/rest/v19/member/create?userId=1234569789&roupId=987654321 HTTP/1.1
Host: subdomain.yourdomain.com
Accept: application/json
Content-Type: application/json
Authorization: Basic ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf

    Response Codes

    The API uses HTTP response codes to identify success or failure. The exact codes depend on the type of call and specific definitions are given on individual call pages. You can find a complete list of codes in our Introduction page.

    Importantly, there are two different codes which denote success. The response depends on if your request returned data:

    • 200: Success, and data was returned in the HTTP body.

    • 204: Success, but no data or HTTP body was returned as this was not needed.

    Version & Backwards Compatibility

    The Engage API evolves over time, with updates and new methods being made available.

    To avoid compatibility issues, each new revision of the API is released with a new version prefix in the path. This ensures that updates to the newer versions of API methods will not affect the methods you currently use. However, we do recommend keeping up to date with the latest releases!

    Contact Mapp Technical Support to confirm if you have the latest version, or try checking out your system version with /system/getApiVersion. The current version 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?
    What's Next