API Reference

Invoke a Service

Use this operation to trigger an existing MEP service for an end user.

When you inject a message into MEP, 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. For information, see Including variables in the request.

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.

Quick facts

Method

POST

Returns

Rejected response only: JSON

Available

All regions

Prerequisites

You must have MEP provisioned with OpenMarket, and the following roles set in the user account:

  • Main Roles: Service Manager/User/Viewer
  • Other Roles: Invoke Service API

The account will need access to the Service Collection that contains the triggered service.

More information

See Overview of MEP Operations and Making Invoke Service Requests.

Try It Out

If you'd like to try out this call using cURL, see Making Invoke Service Requests, which will take you through how to invoke a service.

Making a Request

Definition

POST https://servicemanager.openmarket.com/service/v1/invokeService/<serviceId> 

URL example

https://servicemanager.openmarket.com/service/v1/invokeService/F9E8D7C6B5A4

Query parameters

Parameters must be URL encoded.

Parameter

Description

serviceId

The unique identifier of an existing MEP service.

You can find the ID in the properties pop-up for a service in the MEP UI. For steps to do this, see Retrieve a service ID.

Required: yes

Type: string

Header fields

You must provide your authentication details using Basic authentication in the header. You should also specify that the content-type is JSON. For example:

POST /service/v1/invokeService/mms/v2/send/F9E8D7C6B5A4 HTTP/1.1
Host: servicemanager.openmarket.com
Content-Type: application/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Field

Description

Authorization

Your account ID and password, separated by a colon, and then base-64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Basic authentication.

Content-Type

Specify application/json for these requests.

Request body

The request body must be well-formatted JSON that includes the end user's contact details and, optionally, any variables you wish to set. The request body should not exceed 8,000 bytes.

The variables object

The variables object lets you set one or more variables at the same time as the service is invoked. Variables are defined in this operation using scope, key and value properties.

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 (see example below).

Note that when creating a variable:

  • You can specify variables with the following scope:
    • Session scopes: request, session
    • User scopes: user, userservice, userservicecoll
  • You can only specify custom variables in the request. Built-in variables cannot be altered.
  • There is a set of reserved words that you cannot use as variable keys.
  • Keys can only use a specific set of characters.

Issues with the variable scope, key and value are validated when using this operation, and you will receive an error if there is a problem. For further details, see Including variables in the request.

JSON schema

{
"endUser": {
   "phoneNumber": <number>,
   "mobileOperatorId": <Id>
   },
"variables": {
   "<scope>": {
      "<key>": "<value>",
      "<key>": "<value>"
      },
   "<scope>": {
      "<key>": "<value>",
      "<key>": "<value>"
      }
   }
}

Example

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

Properties in the endUser object

Property

Description

phoneNumber

The mobile or landline phone number of the end user. This must be in international format but without a leading + symbol.For example, 447700900765 (UK) or 12515550100 (US).

You can only specify one phone number in this request.

Type: integer between 6 to 16 characters

Required: Always

mobileOperatorId

 

A numeric ID representing the mobile operator as known by OpenMarket; for example 383 for AT&T in the US.

If you do not include this property then this is set to "UNKNOWN".

For a list of mobile operator IDs see Mobile Operator IDs.

Type: integer

Required: no

Properties/values in the variables object

Property or value

Description

<scope>

The scope for one or more variables. You can only specify each scope once in the request body. Variable scopes are not case-sensitive. Options are: request, session, user, userservice, userservicecoll.

Required: At least one scope is required if the request includes the variables object

<key>

 

A variable key. Each key must be unique within a scope, and cannot be a reserved word. Variable keys are not case-sensitive. Keys can be between 1-255 characters.

Type: UTF-8 string limited to the following characters:

  • A-Z
  • underscore _
  • hyphen -
  • period .

Required: At least one key is required for each scope specified in the request

<value>

The value you are setting for the variable. This can be up to 4096 characters in UTF-8 (restricted to characters in the Basic Multilingual Plane).

Type: string

Required: no

Response from OpenMarket

Accepted requests

OpenMarket responds to a successful request with a status code of 202.

Note: The API will accept requests with any correctly formatted service ID (and request header/body). The API does not validate whether the customer account you have used can access the specified service ID. Services that the account cannot access are not triggered.

The response header contains an X-Request-Id. This uniquely identifies the request in OpenMarket reporting and with our support team. Please include this ID in any request to OpenMarket Support where referencing an issue with a specific invoke service request.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:14:43 GMT
Server: Apache-Coyote/1.1
X-Request-Id: 7EYYG-EF3XM-5LSQ5-ILR73
Transfer-Encoding: chunked

Rejected requests

If your request is rejected then the body of the response will contain a JSON that identifies the issue. It will also include an X-Request-Id in the header.

HTTP/1.1 400 Bad Request
Date: Tue, 15 Mar 2016 11:48:56 GMT
Server: Apache-Coyote/1.1
Connection: close
Transfer-Encoding: chunked
X-Request-Id: 7EYYG-EF3XM-5LSQ5-ILR73
Content-Type: application/json

{ 
"error" : {
   "code":12002, 
   "description":"Invalid JSON in the payload. Value for '<variable>' is an invalid length. Values must be less than 4096 characters"
   } 
}

The response will include following data.

Field

Description

X-Request-Id

A unique ID that identifies the specific request in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Type: A string of 1 to 30 characters in length.

Returned: Always

code

Code defining the reason for the outcome of the request. For a list of the codes, see Response error codes below.

Returned: Always

description

Natural language description of the error.

Returned: Always

Testing your integration

You can use the OpenMarket Customer Integration Environment (CIE) to test your integration. See Testing Your Invoke Service Integration.

Troubleshooting

My request was accepted, but my service wasn't invoked

The API will accept requests with any correctly formatted service ID (and request header/body). The API cannot validate whether the customer account you have used can access the specified service ID. Services that the account cannot access are not triggered. This includes service IDs for services that are disabled or don't exist.

You may wish to set the account as a Services Manager, as service managers can access all service collections associated with the customer account, including any new services. We would also recommend testing that each service is correctly triggered.

Response error codes

These error messages are returned in the response body when there was a problem with receiving the request.

OpenMarket code

Description

1000

"An error occurred while processing the request. Please contact OpenMarket Support."

This response is returned for permanent issues only, so do not retry this request.

1010

"An error occurred while processing the request. Please retry. If retries continue to fail, contact OpenMarket Support."

You can retry your request as this response is returned for temporary issues. Our suggested retry strategy is every 15 minutes, for up to 24 hours.

12001

"Account is not authorized to use this API. Correct your account or contact OpenMarket Support."

12002

"Invalid JSON in the payload. <Specific error condition>"

The JSON being sent is malformed or has invalid content. The rest of the error message will describe the error. For example, you will get this response when:

  • The endUser object is missing or malformed
  • The phoneNumber property is missing or malformed
  • The value of the mobileOperatorId property is malformed.
  • The variable object is specified but is empty.
  • A scope property is invalid (e.g. "userz") or a 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 specified variable (scope.key) is a built-in variable.
  • A value property uses a character outside of the defined list of accepted characters, or the character length is too long.

12003

"Invalid HTTP method."

Your request used a method that is not supported at this time.

12004

"Invalid API version."

Your request specifies a version of the API that is not supported.

12005

"Invalid query parameter."

The API does not allow you to include query parameters.

12006

"Invalid request URL."

The URL is missing required content or contains content that we cannot process. For example, this is returned if you specify "injectService" instead of "invokeService" in the URL, or if the specified service ID is not hexadecimal.

12007

"Request body exceeds the maximum allowable limit of 8K."

The maximum size of the request body is limited to 8000 bytes.

12008

"Request was blocked. You must contact OpenMarket Support to resolve the issue."

12009

"Username and/or password is invalid. Make sure you are providing the correct credentials."

The request includes invalid credentials. Use an admin account to check the credentials or, if do not have access to the view or edit the MEP customer account, contact OpenMarket Support.

12010

"Unable to authenticate request. Contact OpenMarket Support for assistance to resolve this issue."

You may receive this error if you are using SSL mutual authentication with OpenMarket, and:

  • There is an issue with your certificate
  • The name you provided in the header isn't in the approved list you provided to us