Log In

Getting Started

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 currently v2.

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.

VerbDescription
GETUsed for retrieving resources.
POSTUsed for creating resources.
PUTUsed for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETEUsed 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.

CodeNameDescription
200OKEverything worked successfully!
201CreatedWhen you're creating a new object, this will be returned upon success.
400Bad RequestWe could not process the action due to client error.
403ForbiddenWe couldn't authenticate you, or you don't have access to that resource.
404Not FoundThe requested resource could not be found.
408Request TimeoutThe server timed out waiting for the request. The client may repeat the request without modifications at any later time.
409ConflictThe request could not be processed because of a conflict in the request.
415Unsupported Media TypeThe request entity has a media type which the server or resource does not support.
500Internal Server ErrorOoops! Something went wrong in MOCA Backend. The team will look into it.
503Service UnavailableThe 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.

ArgumentOptional?Data typeDescription
offsetYESintegerthe sequential index of the first object to return.
limitYESintegerthe maximum number of objects to retrieve.

Response headers

Each API response has an associated header automatically generated by MOCA servers.

Header nameDescription
X-Server-TimestampUTC timestamp generated by the server when generating this response.
X-Api-VersionREST API version number
ServerName of the server that generated the response.