{"type":"doc","content":[{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"multiexcerpt-include-macro","parameters":{"macroParams":{"macro_uuid":{"value":"77a79df7-a5d1-4f8f-828d-6c8d8a40e9b2"},"name":{"value":"Software Plan - Pro"},"templateData":{"value":"eJyLjgUAARUAuQ=="},"page":{"value":"CommCare Help Site Design Guidance"},"addpanel":{"value":"false"}},"macroMetadata":{"macroId":{"value":"f345059a-caac-41b4-a970-0568905b5033"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://raw.githubusercontent.com/fuegokit/appfire-design-systems-brand-svg/main/single-color-brand-icons/af-logo-multi-excerpt-24.svg"}}],"title":"MultiExcerpt Include"}},"localId":"412bb3dd-5915-4404-b810-312825ecd7b0"}}]},{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"multiexcerpt-include-macro","parameters":{"macroParams":{"macro_uuid":{"value":"846f10d6-3459-462c-8ce9-b12bb0b90265"},"name":{"value":"Technical Documentation"},"templateData":{"value":"eJyLjgUAARUAuQ=="},"page":{"value":"CommCare Help Site Design Guidance"},"addpanel":{"value":"false"}},"macroMetadata":{"macroId":{"value":"2ae60e0e-6dd5-48d8-9c62-9b1eb9e80784"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://raw.githubusercontent.com/fuegokit/appfire-design-systems-brand-svg/main/single-color-brand-icons/af-logo-multi-excerpt-24.svg"}}],"title":"MultiExcerpt Include"}},"localId":"63d87be0-58cd-4b7d-b26f-753cfdf03adc"}}]},{"type":"paragraph","content":[{"text":"This page below provides an overview of CommCare’s API functionality. ","type":"text","marks":[{"type":"strong"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"4"},"outline":{"value":"false"},"style":{"value":"default"},"type":{"value":"list"},"printable":{"value":"true"}},"macroMetadata":{"macroId":{"value":"813dd801-6397-40aa-8b84-4987b82955f3"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"dde522a5-0374-40c9-ae59-f127221c3acb"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"This section is for you if...","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You are a ","type":"text"},{"text":"programmer","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You are looking to write code that interacts directly with CommCare HQ through its APIs.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If you are ","type":"text"},{"text":"not ","type":"text","marks":[{"type":"strong"}]},{"text":"a programmer and are looking to integrate CommCare with other platforms we recommend looking at ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://dimagi.atlassian.net/wiki/x/fRzKfw"}},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Things we take for granted...","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You should have a familiarity with HTTP conventions, such as GET and POST and url parameters.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"To follow the examples, you should be familiar with the standard command line tool ","type":"text"},{"text":"curl","type":"text","marks":[{"type":"strong"}]},{"text":". Here's the manual: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://curl.se/docs/"}},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Character encoding is UTF-8. Dates should be compliant ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://en.wikipedia.org/wiki/ISO_8601"}},{"text":". (In some cases we're still using RFC 3339, but we're moving towards ISO 8601.) Guids should be generated in accordance with RFC 4122.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Versioning","type":"text"}]},{"type":"paragraph","content":[{"text":"The CommCareHQ API is comprised of resources, representing individual data","type":"text"},{"type":"hardBreak"},{"text":"models. Each resource may contain multiple endpoints (list, detail, etc), and","type":"text"},{"type":"hardBreak"},{"text":"may have multiple versions.","type":"text"}]},{"type":"paragraph","content":[{"text":"Some changes are occasionally made to individual resources. Where possible,","type":"text"},{"type":"hardBreak"},{"text":"these are done in a backwards-compatible manner that should not disrupt existing","type":"text"},{"type":"hardBreak"},{"text":"integrations. Otherwise, we will introduce a new version of that resource so new","type":"text"},{"type":"hardBreak"},{"text":"integrations can make use of the updated functionality without impacting","type":"text"},{"type":"hardBreak"},{"text":"existing integrations.","type":"text"}]},{"type":"paragraph","content":[{"text":"Here are examples of some changes we consider backwards compatible.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Adding a new field to the response","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Adding a new query parameter that can be used to filter the data returned or","type":"text"},{"type":"hardBreak"},{"text":"to control the serialization","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Adding a new option for an existing field or parameter","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Adding an additional endpoints or request methods for an existing resource","type":"text"},{"type":"hardBreak"},{"text":"(eg: adding POST handlers to an API that previously only supported GET","type":"text"},{"type":"hardBreak"},{"text":"requests)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"The API's support a few different methods of authentication in addition to the normal session-based authentication used on the rest of CommCare HQ. This makes it easy to access these URLs programmatically.","type":"text"}]},{"type":"paragraph","content":[{"text":"The examples below use ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://en.wikipedia.org/wiki/CURL"}},{"text":". ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Basic authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://en.wikipedia.org/wiki/Basic_access_authentication"}},{"text":" for details of basic authentication.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example (will prompt for the password):","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl -v -u [USERNAME] '[URL]'\n","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also include the password in the command as follows:","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl -v -u [USERNAME]:[PASSWORD] '[URL]'","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"API Key authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"Your API Keys can be found at ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://www.commcarehq.org/accounts/login/?next=/account/api_keys/"}},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"From that page you can generate new API keys and scope them to individual IP addresses. If an API key has an IP address whitelist, any request originating from a different IP address that uses that API key will be rejected.","type":"text"}]},{"type":"paragraph","content":[{"text":"When an API key is deleted, all requests using that key will be rejected. Unfortunately deleted keys cannot be recovered.","type":"text"}]},{"type":"paragraph","content":[{"text":"When creating a new API key, the actual key will only be shown once so you should note it down at that moment.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"wide","width":1400,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1280,"id":"093e0692-5dbd-4e26-839c-d6a0259e49b6","collection":"contentId-2279637003","type":"file","height":124}}]},{"type":"paragraph","content":[{"text":"If you use this method of authentication, you do not need to provide a 2 factor OTP header (this is only relevant for API calls with 2 factor auth required.)","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl -H \"Authorization: ApiKey [USERNAME]:[API_KEY]\" '[URL]'","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Two-Factor authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"If you have two factor authentication (2FA) set up on your account, then basic authentication is not directly supported for accessing APIs. Instead, you must use Api Key authentication, as described above, or pass in a two factor token generated via SMS or your authenticator application via the \"otp\" url parameter. For example: https://www.commcarehq.org/a//api/v0.5/case/?otp=123456","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Explorer","type":"text"}]},{"type":"paragraph","content":[{"text":"A tool for browsing the read-only CommCare APIs can be found at ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://commcare-api-explorer.dimagi.com/"}},{"text":" . This tool will connect directly to your CommCare account using ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://oauth.net/2/"}},{"text":" so you don't have to worry about handling authentication. See ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2349990373"}},{"text":" for more information.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Standards","type":"text"}]},{"type":"paragraph","content":[{"text":"This page contains some shared information about all our APIs.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dates","type":"text"}]},{"type":"paragraph","content":[{"text":"We need to decide on a standardized date and datetime format. We will most likely go with ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://en.wikipedia.org/wiki/ISO_8601"}},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Formats","type":"text"}]},{"type":"paragraph","content":[{"text":"All APIs will be available in both JSON and XML format. Because XML is a more complex representation than JSON, there is not a simple 1:1 mapping. However, we will base the APIs on the JSON format and define a consistent schema for converting JSON to XML for consistency. Here are some standards that we're using.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Objects, Types, and IDs","type":"text"}]},{"type":"paragraph","content":[{"text":"Root objects should always have a type and id property. The type will be used to define the XML element name of the object, and the ID will be tagged as an attribute on the root element. Here is a very simple example demonstrating this:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Sample Object JSON","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"{ type: \"myobject\",\n id: \"objectid5342\",\n name: \"An Object\",\n color: \"green\"\n}","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Sample Object XML","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"\n An Object\n green\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Lists","type":"text"}]},{"type":"paragraph","content":[{"text":"In JSON lists are allowed to be either very simple lists of a single basic value (typically a string), or lists of objects. Flat lists will be converted to XML as follows:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Sample Object with List JSON","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"{ type: \"myobject\",\n id: \"objectid5342\",\n name: \"An Object\",\n colors: [\"green\", \"blue\", \"purple\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Sample Object with List XML","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"\n An Object\n \n green\n blue\n purple\n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"The choice of element name for the internal list items (in this case \"color\") will be defined statically, per element, or may be guessed if there is no static mapping. Typically guessing would entail removing a trailing \"s\" from the list property name, as in this example.","type":"text"}]},{"type":"paragraph","content":[{"text":"Lists of objects expect the type property to be present on the object to choose the inner element name, although if none is present will use either a static mapping or guess. The ID attribute is optional but will be treated as described above if present. Root lists of objects should be wrapped in a one-element dictionary, the key of which represents the root element name. The following example shows a basic list of objects. If types are defined it is illegal for any object in the list to have a type different from the others.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Sample List of Objects JSON","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"{objectcollection: [\n { \n type: \"myobject\",\n id: \"1\",\n name: \"A clover\",\n color: \"green\"\n },\n { \n type: \"myobject\",\n id: \"2\",\n name: \"The sky\",\n color: \"blue\"\n },\n { \n type: \"myobject\",\n id: \"3\",\n name: \"Minda\",\n color: \"purple\"\n }\n]}","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Sample List of Objects XML","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"\n \n A clover\n green\n \n \n The sky\n blue\n \n \n Minda\n purple\n \n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Standards used in Some APIs","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"f2b7d48c-c487-449e-8cff-edb7350b94a1"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"Standard","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[542.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"OpenRosa Request","type":"text","marks":[{"type":"link","attrs":{"href":"https://bitbucket.org/javarosa/javarosa/wiki/OpenRosaRequest"}}]},{"text":" ","type":"text"},{"text":"†","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[542.0]},"content":[{"type":"paragraph","content":[{"text":"The standard for HTTP(S) interactions between CommCare client and server","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"text":"Meta Data Schema","type":"text","marks":[{"type":"link","attrs":{"href":"https://bitbucket.org/javarosa/javarosa/wiki/OpenRosaMetaDataSchema"}}]},{"text":" ","type":"text"},{"text":"†","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[542.0]},"content":[{"type":"paragraph","content":[{"text":"Open Rosa standard meta data tags. (Taken care of by default by CommCare HQ.)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://github.com/dimagi/commcare-core/wiki/casexml20"}},{"text":"†","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[542.0]},"content":[{"type":"paragraph","content":[{"text":"XML spec for case-related transactions. (Taken care of by default by CommCare HQ.)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://github.com/dimagi/commcare-core/wiki/CentralAuthAPI"}},{"text":"†","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[542.0]},"content":[{"type":"paragraph","content":[{"text":"How authentication is done between a CommCare device and the server ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[218.0]},"content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://github.com/dimagi/commcare-core/wiki/CommCare20Specs"}},{"text":" † ","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[542.0]},"content":[{"type":"paragraph","content":[{"text":"Additional documentation for CommCare APIs","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"†","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]},{"text":" External links to the JavaRosa/CommCare docs","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Documented APIs and use of Standards","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"All the APIs are documented here","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://commcare-hq.readthedocs.io/api/index.html#commcare-apis"}}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"paragraph","content":[{"text":"In the above, [version] should always be replaced with one of v0.5, v0.4. These documents only describe the latest version - some prior versions remain available only to support backwards compatibility with ","type":"text"},{"text":"deployed systems","type":"text","marks":[{"type":"em"}]},{"text":", not for general use.","type":"text"}]},{"type":"paragraph","content":[{"text":"The latest version is ","type":"text"},{"text":"v0.5","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition to the permissions listed, all APIs also require the \"API Access\" permission. The URL endpoints listed below should be utilized as part of a curl authentication command. You can read more about this under ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2279637003/CommCare+API+Overview#API-Authentication"}},{"text":" .","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Clients","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that any third party libraries are not supported by Dimagi.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Python","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://github.com/dimagi/commcare-hq-api"}},{"text":" ","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Key Restrictions","type":"text"}]},{"type":"paragraph","content":[{"text":"API Keys can be restricted by two methods IP address and/or Domain. ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The IP Allowlist restriction defines a specific IP address or comma separated list of IP addresses where the API Key can be used. The field references ","type":"text"},{"text":"IPv4. ","type":"text","marks":[{"type":"strong"}]},{"text":"There are many ways to check what your IP Address is, one simple way is to use: ","type":"text"},{"text":"https://whatismyipaddress.com/","type":"text","marks":[{"type":"link","attrs":{"href":"https://whatismyipaddress.com/"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The Domain restriction allows an API Key to be restricted to a specific domain/project space.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If either of these fields are left blank, the API Key will by default be unrestricted.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Rate Limiting","type":"text"}]},{"type":"paragraph","content":[{"text":"CommCare applies API rate limits on all project spaces at all times. You can read more about rate limiting here: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143956626/CommCare+Rate+Limiting#API-Rate-Limiting"}},{"text":" ","type":"text"}]}],"version":1}

Browser not supported