{"__v":17,"_id":"55a58a500f354f0d00fd0313","category":{"project":"559a61d2dbcfd20d00710b39","version":"559a61d2dbcfd20d00710b3c","_id":"55afb260902fd51700f5f8c2","pages":[],"__v":0,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-07-22T15:10:24.728Z","from_sync":false,"order":5,"slug":"rest-api-1","title":"REST API"},"parentDoc":null,"project":"559a61d2dbcfd20d00710b39","user":"55a575ebaaf9cf1900114d73","version":{"__v":23,"_id":"559a61d2dbcfd20d00710b3c","project":"559a61d2dbcfd20d00710b39","createdAt":"2015-07-06T11:09:06.510Z","releaseDate":"2015-07-06T11:09:06.510Z","categories":["559a61d3dbcfd20d00710b3d","55a589ddaaf9cf1900114dd0","55a589e30f354f0d00fd0312","55a589ea80c8a30d00b323cc","55a589f6aaf9cf1900114dd1","55a58d4e80c8a30d00b323e6","55a8e7a227a17d21005251a2","55a93098cf45e1390093f351","55afb085f202b12100cd9e83","55afb22e902fd51700f5f8bf","55afb260902fd51700f5f8c2","55afb28ec8a85321007a5462","55afb294f202b12100cd9e95","55afb29b902fd51700f5f8c5","55afb2a1c8a85321007a5463","55afb2a7902fd51700f5f8c7","55afb2ad902fd51700f5f8c8","55afb2b5902fd51700f5f8ca","55b74b2131bccb190081bedc","55bb441b54f9640d006e6cf2","565711085cb2420d00d70071","5681681330018c0d006bf7ff","588f38b5923d610f00c72dad"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-07-14T22:16:48.027Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The MOCA API can be used to automate beacon fleet management, connect your CRM data, built custom functionalities, and query analytics reports. Through MOCA REST API, you can integrate third-party systems and access raw data. It enables the inclusion of maps and analysis of mobile users’ flow indoors and outdoors.\n\nThe MOCA API is organized around REST. The API lets you interact with MOCA Platform from anything that can send an HTTP request. Our API 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.\n\nThere are many things you can do with the REST API. For example:\n* Register new mobile app\n* Manage fleet of beacons\n* Automatically register all your places (i.e. physical locations)\n* Create audience segments\n* Program marketing campaigns targeted to selected segments\n* Send push notifications\n* Query analytics data \n* Query user profiles\n* Export raw data\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"SSL only\"\n}\n[/block]\nWe require that all requests are done over SSL. Calls made over plain HTTP will fail. You must authenticate for all requests.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"UTF-8 encoding\"\n}\n[/block]\nEvery string passed to and from the MOCA API needs to be UTF-8 encoded. For maximum compatibility, normalize to [Unicode Normalization Form C (NFC)](http://unicode.org/reports/tr15/) before UTF-8 encoding.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Date & time format\"\n}\n[/block]\nAll dates and times in the API are 64-big long integer that encode number of milliseconds since midnight, January 1, 1970 UTC.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Making a request\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The MOCA REST API is accessed from the URL `https://api.mocaplatform.com/v1/`. The path is prefixed with the API version which is currently *`v1`*.\"\n}\n[/block]\nTo send a new request, you must include a `User-Agent` header, `Content-Type` header and JSON payload.\t\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"You must include a User-Agent header with name of your client application. If you don't supply this header, you will get a 400 Bad Request.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP verbs\"\n}\n[/block]\nWhere possible, API v1 strives to use appropriate HTTP verbs for each action.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Verb\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"GET\",\n    \"1-0\": \"POST\",\n    \"2-0\": \"PUT\",\n    \"3-0\": \"DELETE\",\n    \"3-1\": \"Used for deleting resources.\",\n    \"2-1\": \"Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.\",\n    \"1-1\": \"Used for creating resources.\",\n    \"0-1\": \"Used for retrieving resources.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Error handling\"\n}\n[/block]\nMOCA 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.\n\nErrors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted. See [complete list of error codes](moca-rest-api-error-handling).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nMOCA supports [OAuth 2.0](http://oauth.net/) for authenticating all API requests. Find out more in the [Authentication](moca-rest-api-authentication) guide.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination\"\n}\n[/block]\nAll 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.\n\nMOCA utilizes cursor-based pagination, using the parameters `firstResult` and `maxResults`.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Argument\",\n    \"h-1\": \"Optional?\",\n    \"h-2\": \"Data type\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"firstResult\",\n    \"0-3\": \"the sequential index of the first object to return.\",\n    \"0-1\": \"YES\",\n    \"0-2\": \"integer\",\n    \"1-0\": \"maxResults\",\n    \"1-1\": \"YES\",\n    \"1-2\": \"integer\",\n    \"1-3\": \"the maximum number of objects to retrieve.\"\n  },\n  \"cols\": 4,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response headers\"\n}\n[/block]\nEach API response has an associated header automatically generated by MOCA servers.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Header name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"X-Server-Timestamp\",\n    \"0-1\": \"UTC timestamp generated by the server when generating this response.\",\n    \"1-0\": \"X-Api-Version\",\n    \"1-1\": \"REST API version number\",\n    \"2-0\": \"Server\",\n    \"2-1\": \"Name of the server that generated the response.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]","excerpt":"","slug":"moca-rest-api-getting-started","type":"basic","title":"Getting Started"}
The MOCA API can be used to automate beacon fleet management, connect your CRM data, built custom functionalities, and query analytics reports. Through MOCA REST API, you can integrate third-party systems and access raw data. It enables the inclusion of maps and analysis of mobile users’ flow indoors and outdoors. The MOCA API is organized around REST. The API lets you interact with MOCA Platform from anything that can send an HTTP request. Our API 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. There are many things you can do with the REST API. For example: * 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 * Query user profiles * Export raw data [block:api-header] { "type": "basic", "title": "SSL only" } [/block] We require that all requests are done over SSL. Calls made over plain HTTP will fail. You must authenticate for all requests. [block:api-header] { "type": "basic", "title": "UTF-8 encoding" } [/block] 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)](http://unicode.org/reports/tr15/) before UTF-8 encoding. [block:api-header] { "type": "basic", "title": "Date & time format" } [/block] All dates and times in the API are 64-big long integer that encode number of milliseconds since midnight, January 1, 1970 UTC. [block:api-header] { "type": "basic", "title": "Making a request" } [/block] [block:callout] { "type": "info", "body": "The MOCA REST API is accessed from the URL `https://api.mocaplatform.com/v1/`. The path is prefixed with the API version which is currently *`v1`*." } [/block] To send a new request, you must include a `User-Agent` header, `Content-Type` header and JSON payload. [block:callout] { "type": "warning", "body": "You must include a User-Agent header with name of your client application. If you don't supply this header, you will get a 400 Bad Request." } [/block] [block:api-header] { "type": "basic", "title": "HTTP verbs" } [/block] Where possible, API v1 strives to use appropriate HTTP verbs for each action. [block:parameters] { "data": { "h-0": "Verb", "h-1": "Description", "0-0": "GET", "1-0": "POST", "2-0": "PUT", "3-0": "DELETE", "3-1": "Used for deleting resources.", "2-1": "Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.", "1-1": "Used for creating resources.", "0-1": "Used for retrieving resources." }, "cols": 2, "rows": 4 } [/block] [block:api-header] { "type": "basic", "title": "Error handling" } [/block] 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. See [complete list of error codes](moca-rest-api-error-handling). [block:api-header] { "type": "basic", "title": "Authentication" } [/block] MOCA supports [OAuth 2.0](http://oauth.net/) for authenticating all API requests. Find out more in the [Authentication](moca-rest-api-authentication) guide. [block:api-header] { "type": "basic", "title": "Pagination" } [/block] 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 `firstResult` and `maxResults`. [block:parameters] { "data": { "h-0": "Argument", "h-1": "Optional?", "h-2": "Data type", "h-3": "Description", "0-0": "firstResult", "0-3": "the sequential index of the first object to return.", "0-1": "YES", "0-2": "integer", "1-0": "maxResults", "1-1": "YES", "1-2": "integer", "1-3": "the maximum number of objects to retrieve." }, "cols": 4, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Response headers" } [/block] Each API response has an associated header automatically generated by MOCA servers. [block:parameters] { "data": { "h-0": "Header name", "h-1": "Description", "0-0": "X-Server-Timestamp", "0-1": "UTC timestamp generated by the server when generating this response.", "1-0": "X-Api-Version", "1-1": "REST API version number", "2-0": "Server", "2-1": "Name of the server that generated the response." }, "cols": 2, "rows": 3 } [/block]