MEP APIs

Submit a Service Broadcast

This operation enables you to trigger a service for users in a subscription or multiple subscriptions.

Quick facts

Method	GET
Returns	Accepted response: XML Rejected response: plain text
Available	All regions
Prerequisites	You must have MEP provisioned with OpenMarket, and the following roles set in the user account: Main Roles: Broadcast User Broadcasts - Broadcast Types
More information	See MEP Operations and Making Broadcast Requests.

Try It Out

If you'd like to try out this call using cURL, see Making Broadcast Requests, which will take you through sending SMS, MMS and Service broadcasts, and retrieving any IDs you need to know.

Making a Request

Definition

GET https://cmx2api.openmarket.com/subscriptionapi/createservicebroadcast

URL example

>https://cmx2api.openmarket.com/subscriptionapi/createservicebroadcast?username=MyUsername&password=P4S5W0Rd&serviceid=F9E8D7C6B5A4&subscriptions=A1B2C3D4E5F6%2CB2C3D4E5F6A1&name=Trigger+Thank+You+Service&senddate=2016-04-05+13%3A00%3A00

Query parameters

Parameters must be URL encoded.

Parameter	Description
username	The username used to access MEP. Required: yes Type: string
password	The password associated with the MEP username. Required: yes Type: string
subscriptions	The IDs of the subscriptions for which you want to trigger a service. Use a comma separated list to specify multiple subscription IDs. Required: yes Type: string
serviceid	The ID of the service. The service ID is only available via the GUI. To retrieve a service ID, navigate to the Services homepage and click the Edit Properties icon for the service. Required: yes Type: string
name	The name used to identify the broadcast activity in MEP. This can be up to 255 characters in length. Required: yes Type: string
senddate	The time and date that the service is triggered (based on UK time). This enables you to create a message that MEP sends at the specified time, rather than immediately. Specify this in the format yyyy-MM-dd HH:mm:ss, for example: 1999-12-31 23:59:59 MEP assumes this is the time and date for London, United Kingdom (either GMT or BST, depending on the time of year). If you are based in another region, you will need to offset the time, e.g. by 8 hours for Pacific Standard time. Note that if you specify a time in the past, then MEP broadcasts the message immediately. Required: no Type: string Default: the current date and time

Parameter

Description

username

The username used to access MEP.

Required: yes

Type: string

password

The password associated with the MEP username.

Required: yes

Type: string

subscriptions

The IDs of the subscriptions for which you want to trigger a service. Use a comma separated list to specify multiple subscription IDs.

Required: yes

Type: string

serviceid

The ID of the service.

The service ID is only available via the GUI. To retrieve a service ID, navigate to the Services homepage and click the Edit Properties icon for the service.

Required: yes

Type: string

name

The name used to identify the broadcast activity in MEP. This can be up to 255 characters in length.

Required: yes

Type: string

senddate

The time and date that the service is triggered (based on UK time). This enables you to create a message that MEP sends at the specified time, rather than immediately.

Specify this in the format yyyy-MM-dd HH:mm:ss, for example:

 1999-12-31 23:59:59

MEP assumes this is the time and date for London, United Kingdom (either GMT or BST, depending on the time of year). If you are based in another region, you will need to offset the time, e.g. by 8 hours for Pacific Standard time.

Note that if you specify a time in the past, then MEP broadcasts the message immediately.

Required: no

Type: string

Default: the current date and time

Header fields

There is no data required in the header.

Response from OpenMarket

Accepted requests

MEP will respond to a successful request with a status code of 200 and an ID for the broadcast in the response body.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:36:54 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain
			
<?xml version="1.0" ?>
<broadcast>
   <id>17567FCA39AF3F67</id>
</broadcast>

Rejected requests

If your request is rejected then the body of the response will contain a plain text description of the error. For example:

HTTP/1.1 401 Unauthorized
Date: Tue, 15 Mar 2016 11:48:56 GMT
Server: Apache-Coyote/1.1
Connection: close
Transfer-Encoding: chunked
Content-Type: text/plain
			
Your username and/or password is incorrect. Check and try again.

See Response error messages below for a list of the possible error messages.

Testing your integration

You can test broadcast operations directly with MEP, however, MEP will send any messages to numbers in the specified subscriptions. Therefore to test your integration, we suggest the following:

Create a subscription with no numbers in the list. This is suitable for testing your requests and ability to receive responses from us.
Once you are ready, create a subscription that contains your own test mobile number(s), to confirm that your broadcasts work as you expect. If you are messaging in multiple regions, then we recommend using multiple test numbers that are located in your messaging regions.

For more information on using each operation, see Making Broadcast Requests.

Troubleshooting

Response error messages

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

Message	Description
Your request is invalid, specifically the following parameter is incorrect: <parameter>=<value>	You request contains a problem with the specified mandatory parameter that has stopped MEP from being able to process the request. If the <value> is “null”, then the parameter name is misspelled or the parameter is missing. Otherwise, the value you specified is invalid or does not match the available options. Correct the error and resend the message.
Your username and/or password is incorrect. Check and try again.	Either the username or the password parameter has not been correctly specified. Both parameters are mandatory. Check that both parameters are specified, and that you have entered the correct values for each parameter.
You do not have the necessary roles or permissions to perform the action: <description>	Your access rights in MEP do not allow you use the operation. The information in the <description> part of the response will tell you the role or permission that you are missing.