Making Invoke Service Requests

The Invoke Service operation enables you to trigger an existing MEP service for a specified end user. In the request you can include variables related to the end user or the service, letting you both add and update variables as required. Read this page to find out how to use the invoke service operation, retrieve a service ID, try out the operations using cURL, and understand how to include variables in the request.

You can use the invoke service operation for any kind of integration where you want an external system, such as a website or CRM system, to initiate a MEP service for a specific end user.

You can test your integration using the OpenMarket Customer Integration Environment (CIE). The primary purpose of testing is to ensure that your requests will validate. To test invocation of your MEP service, you will need to use your test mobile devices.

Note: The Invoke Service operation supports the same basic functionality as the Inject Message operation. The primary differences between the two are that Invoke Service provides enhanced security and high availability capabilities. If you are an existing customer using the Inject Message operation, contact your OpenMarket account manager to determine the migration effort. If you are a new customer, you may want to contact your account manager to determine which operation best fits your needs.

Before we begin

Before beginning, you'll need a MEP account provisioned. Once provisioned, log into MEP and make sure in the MEP user account that you have the following settings:

  • Main Roles
    • Either Services Manager, Service User or Service Viewer. We recommend setting the account as Service Manager, as service managers can access all service collections and services.
  • Other Roles
    • Invoke Service API role

OpenMarket rejects messages from accounts that are not provisioned with the above.

The account will also need access to the Service Collection that contains the triggered service. However, the API will accept requests with any correctly formatted service ID (and request header/body). It cannot validate whether the customer account you have used can access the specified service ID.

Retrieve a service ID

Invoke service requests must include an ID for a service. To obtain a service ID:

  1. Navigate to the Services tab.
  2. Expand the Service Collection that contains the desired service. The "ID" column shows the service ID of each service.

Services home page with Service IDs indicated

Invoke a service

(Operation: Invoke a Service)

This example request invokes a MEP service for a fictional US number, and sets both user and session variables.

1. Create a text file for the POST body

Create a text file called invoke-service.txt and copy in the example below. If desired, you can change the example US phone number "12515550130" to one that you can receive messages on; otherwise you can test the operation using the example, as the example is a fictional number and will not reach an end user. Make sure that you include the country code so that the number is in international format (e.g. 44 for the UK or 1 for the US). Don't add a "+" character.

   "endUser": {
      "phoneNumber": 12515550130,
      "mobileOperatorId": 383
   "variables": {
      "session": {
         "seatLocation": "aisle",
         "seatClass": "first",
         "flightNumber": 49,
         "flightAirline": "AwesomeAirways"
      "user": {
         "frequentFlyerAccountNumber": "MJHF787679"

2. Use cURL to send the message

Make a request using the following sample cURL. You'll need to:

  • Ensure you're in the same folder/directory as the text file
  • Replace the accountid:password with your OpenMarket account ID and password (note that this is sent using Basic authentication).
  • Change the example service ID F9E8D7C6B5A4 to your own service ID
curl -X POST -H "Content-Type: application/json" --user accountid:password --data-binary @invoke-service.txt   --dump-header response.txt

If your request is successful, OpenMarket will return a synchronous response, with an HTTP status code of 202. In this example, the response is found in the file response.txt.

HTTP/1.1 202 Accepted
Content-Length: 0
X-Request-Id: 7EYYG-EF3XM-5LSQ5-ILR73

The X-Request-ID uniquely identifies the request in OpenMarket reporting and with our support team.

Including variables in the request

When you invoke a service with this operation, you can set variables related to both the session and the end user. This enables you to create or update custom variables with each request.

This feature acts much the same as if you are creating or updating a variable at the beginning of the service using a Set Variable handler. The variables are set before the message is routed and are accessible immediately within the triggered service.

You can send an expression as part of the variable's value, as long as the expression doesn't require an initial value that hasn't been defined (for example, you can't set a self-referential expression). With variables, you can update only custom variables (not built-in variables) and you must avoid reserved words.

You can specify variables with the following scope:

  • Session scopes: request and session
  • User scopes: user, userservice, and userservicecoll

The Variables object

You can include variables in the request body using the variables object. The properties inside this object are scope, key and value.

This object is optional. If you do include the object, then you must include at least one variable (you cannot leave the object empty). You can specify each scope just once, but include multiple keys for the scope, for example:

"variables": {
   "session": {
      "seatLocation": "aisle",
      "seatClass": "first",
      "flightNumber": 49,
      "flightAirline": "AwesomeAirways"
   "user": {
      "frequentFlyerAccountNumber": "MJHF787679"

For full details on the request body, see Invoke a Service.

Identifier variables set with the API

The following identifiers may be automatically created or updated with each successful request:

  • user.identifiers.msisdn — the phoneNumber property in the request.
  • — this is an MEP generated ID that is unique to each end user (as identified by the phone number in this API).
  • — the mobileOperatorId property in the request. If the number is for a landline or is not provided in the request, and MEP does not know the mobile operator from previous interactions, then this is set to "UNKNOWN".

Note that you cannot set the variable in this request.

How variables are validated

The variable scope and key are both validated when using this API and you will receive an error if there is a problem. The scope and key are validated for the following issues:

  • A scope property is invalid (e.g. "userz").
  • The same scope is specified multiple times in the request.
  • A key property uses a character outside of the defined list of accepted characters, or the character length of the key is too long or too short.
  • A key property is a reserved word.
  • A key is specified multiple times within a scope.
  • A specified variable (scope.key) is a built-in variable.

With the variable value, this API checks for the following issues and will send an error if found:

  • A value property uses a character outside of the defined list of accepted characters.
  • The character length of a value is too long. If your value is an expression, then the API checks the character count of the expression, not the eventual evaluated expression. For example, if your value is a PIN you are generating using an EL function: ${af:generatePin(6,true)} then the value will be counted as 25 characters, rather than the evaluated expression (which is 6 character PIN).

When checking a value, this API cannot determine if there is an issue with how the value is processed in the service. For example, it cannot check whether any expressions in the value are self-referential or that an expression is formatted correctly.

Issues with the scope, key or value return a 400 HTTP response code with an OpenMarket error code of 12002.