The MOCA API can be used to automate beacon and geofence fleet management, manage your MOCA Campaigns, send remote push notifications and query analytics data the likes of you see in our MOCA Console. Through MOCA REST API, you can integrate third-party systems and access processed data.
The MOCA API is fully RESTful and supports GET, POST, PUT and DELETE methods. It is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website's client-side code). JSON will be returned in all responses from the API, including errors.
Examples of the many things you can do with our REST API:
- Register new mobile app
- Manage fleet of beacons
- Automatically register all your places (i.e. physical locations)
- Create audience segments
- Program marketing campaigns targeted to selected segments
- Send push notifications
- Query analytics data such as: new users, returning users, visitors and aggregated user geolocations.
URL Encoding
Parameters sent to the REST API must be URL encoded. More about URL Encoding can be found here.
SSL only
We require that all requests are done over SSL. Calls made over plain HTTP will fail. You must authenticate for all requests.
UTF-8 encoding
Every string passed to and from the MOCA API needs to be UTF-8 encoded. For maximum compatibility, normalize to Unicode Normalization Form C (NFC) before UTF-8 encoding.
Date & time format
All dates and times in the API are 64-big long integer that encode number of milliseconds since midnight, January 1, 1970 UTC.
Making a request
The MOCA REST API is accessed from the URL
https://api.mocaplatform.com/v2/
. The path is prefixed with the API version which is currentlyv2
.
To send a new request, you must include a Content-Type
header and JSON payload.
HTTP verbs
Where possible, API v1 strives to use appropriate HTTP verbs for each action.
Verb | Description |
---|---|
GET | Used for retrieving resources. |
POST | Used for creating resources. |
PUT | Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero. |
DELETE | Used for deleting resources. |
Error handling
MOCA uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the caller provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with MOCA's servers.
Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted.
Code | Name | Description |
---|---|---|
200 | OK | Everything worked successfully! |
201 | Created | When you're creating a new object, this will be returned upon success. |
400 | Bad Request | We could not process the action due to client error. |
403 | Forbidden | We couldn't authenticate you, or you don't have access to that resource. |
404 | Not Found | The requested resource could not be found. |
408 | Request Timeout | The server timed out waiting for the request. The client may repeat the request without modifications at any later time. |
409 | Conflict | The request could not be processed because of a conflict in the request. |
415 | Unsupported Media Type | The request entity has a media type which the server or resource does not support. |
500 | Internal Server Error | Ooops! Something went wrong in MOCA Backend. The team will look into it. |
503 | Service Unavailable | The service is currently unavailable because it is overloaded or down for maintenance. |
Our API libraries can raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend always trying to gracefully handle exceptions from our API.
Pagination
All top-level MOCA API resources have support for bulk fetches — "list" API methods. For instance you can List Apps, List Beacons, and List Experiences. These list API methods share a common structure.
MOCA utilizes cursor-based pagination, using the parameters offset
and limit
.
Argument | Optional? | Data type | Description |
---|---|---|---|
offset | YES | integer | the sequential index of the first object to return. |
limit | YES | integer | the maximum number of objects to retrieve. |
Response headers
Each API response has an associated header automatically generated by MOCA servers.
Header name | Description |
---|---|
X-Server-Timestamp | UTC timestamp generated by the server when generating this response. |
X-Api-Version | REST API version number |
Server | Name of the server that generated the response. |