Partner API Documentation

From Developer Wiki

Contents

Overview

These APIs are intended for data exchange between partners and Mozes.

Registration

To use Mozes partner APIs, you first need an API key and shared secret. Contact support@mozes-inc.com to request them.

Authentication

For partner API calls, partner applications are identified by passing their API key with each request. They are authenticated by passing an authentication token created using the shared secret. The Mozes server uses the same one-way hash algorithm that the partner client application used to generate the authentication token to verify that client application indeed knows the shared secret.

Generating authentication tokens

The shared secret is concatenated with other data referred to as salt and a one-way hash algorithm is run on the result to produce the authentication token.

Salt

The salt string varies for each API but always contains a time stamp used like a nonce to help guard against replay attacks.

Timestamp

The timestamp is Unix time in seconds since epoch. In PHP, it's produced by calling the time() function 

$timestamp = time();

One-way hash

Authentication tokens are 128-bit MD5 hashes represented as a sequence of 32 hexadecimal digits. In PHP, it's as simple as calling the md5 function 

$token = md5($shared_secret . $salt);

Example

Suppose the salt for the API we're calling in just the Unix time stamp. The authentication token can be created in PHP like so 

$shared_secret = 'super_secret_password';
$salt = time(); //1219432310 for Fri, 22 Aug 2008 19:11:50 GMT
$auth_token = md5($shared_secret . $salt) //a43f9fd4b790ffb971496fb219f1211e for the above values

Normalized phone numbers

Phone numbers need to formatted as a string of digits, including country code. North American Numbering Plan Area numbers need a 1 prepended to the area code. For example, (555) 999-1234 would be formatted as 15559991234.

APIs

Mob Subscribe

Example API call

For the following parameters, 

API key: test
Shared secret: super_secret_password
Phone: (555) 999-1234
Keyword: iammobile
Time: Fri, 22 Aug 2008 19:11:50 GMT (Unix time 1219432310)

The authentication token would be calculated by concatenating the shared secret, user phone number, and Unix timestamp and taking the md5 digest 

md5('super_secret_password155599912341219432310'); //6ebcd2de543f6febb6d9a7edb36663b1

The mob subscribe API call would get an HTTP GET to 

https://www.mozes.com/_/api/mob_subscribe?partner_login=test&keyword=iammobile&phone=15559991234&time=1219432310&token=6ebcd2de543f6febb6d9a7edb36663b1

API Response

The response is a simple XML document. Here's an example of a successful result. 

<?xml version="1.0" ?>
<MozesMobSubscribeResult>
 <Status>SUCCESS</Status>
 <ErrorMsg></ErrorMsg>
 <Keyword>iammobile</Keyword>
 <Phone>15559991234</Phone>
</MozesMobSubscribeResult>

Here's an example of a error 

<?xml version="1.0" ?>
<MozesMobSubscribeResult>
 <Status>ERROR</Status>
 <ErrorMsg>You are not authorized to register users for this keyword</ErrorMsg>
 <Keyword></Keyword>
 <Phone></Phone>
</MozesMobSubscribeResult>

Mob Unsubscribe

Example API call

For the following parameters, 

API key: test
Shared secret: super_secret_password
Phone: (555) 999-1234
Keyword: iammobile
Time: Fri, 22 Aug 2008 19:11:50 GMT (Unix time 1219432310)

The authentication token would be calculated by concatenating the shared secret, user phone number, and Unix timestamp and taking the md5 digest 

md5('super_secret_password155599912341219432310'); //6ebcd2de543f6febb6d9a7edb36663b1

The mob unsubscribe API call would get an HTTP GET to 

https://www.mozes.com/_/api/mob_unsubscribe?partner_login=test&keyword=iammobile&phone=15559991234&time=1219432310&token=6ebcd2de543f6febb6d9a7edb36663b1

API Response

The response is a simple XML document. Here's an example of a successful result. 

<?xml version="1.0" ?>
<MozesMobUnsubscribeResult>
 <Status>SUCCESS</Status>
 <ErrorMsg></ErrorMsg>
 <Keyword>iammobile</Keyword>
 <Phone>15559991234</Phone>
</MozesMobUnsubscribeResult>

Here's an example of a error 

<?xml version="1.0" ?>
<MozesMobUnsubscribeResult>
 <Status>ERROR</Status>
 <ErrorMsg>You are not authorized to register users for this keyword</ErrorMsg>
 <Keyword></Keyword>
 <Phone></Phone>
</MozesMobUnsubscribeResult>

Mob User Status

Example API call

For the following parameters, 

API key: test
Shared secret: super_secret_password
Phone: (555) 999-1234
Keyword: iammobile
Time: Fri, 22 Aug 2008 19:11:50 GMT (Unix time 1219432310)

The authentication token would be calculated by concatenating the shared secret, user phone number, and Unix timestamp and taking the md5 digest 

md5('super_secret_password155599912341219432310'); //6ebcd2de543f6febb6d9a7edb36663b1

The mob user status API call would get an HTTP GET to 

https://www.mozes.com/_/api/mob_user_status?partner_login=test&keyword=iammobile&phone=15559991234&time=1219432310&token=6ebcd2de543f6febb6d9a7edb36663b1

API Response

The response is a simple XML document. Here's an example of a successful result. 

<?xml version="1.0" ?>
<MozesMobUserStatusResult>
 <Status>SUCCESS</Status>
 <ErrorMsg></ErrorMsg>
 <Keyword>iammobile</Keyword>
 <Phone>15559991234</Phone>
 <IsSubscribed>false</IsSubscribed>
</MozesMobUserStatusResult>

Here's an example of a error 

<?xml version="1.0" ?>
<MozesMobUserStatusResult>
 <Status>ERROR</Status>
 <ErrorMsg>You are not authorized to register users for this keyword</ErrorMsg>
 <Keyword></Keyword>
 <Phone></Phone>
</MozesMobUserStatusResult>


Client Libraries

To make Mozes Partner APIs easier to use, we have a few clients libraries available.

  • PHP 5
  • PHP 4 (Mob subscribe example only)
  • .NET (Mob subscribe example only)
Retrieved from "http://wiki.mozes.com/developer/index.php/Partner_API_Documentation"