This page covers the endpoints to use when integrating with the CHT server. If there isn’t an endpoint that provides the function or data you need, direct access to the database is possible via the CouchDB API. Access to the PostgreSQL database may also prove useful for data analysis. If additional endpoints would be helpful, please make suggestions via a GitHub issue.
Various properties throughout this API use a timestamp value, the following formats are supported:
ISO 8601 combined date and time with timezone of the format below where “Z” is offset from UTC like “-03”, “+1245”, or just “Z” which is UTC (0 offset);
YYYY-MM-DDTHH:mm:ssZ
YYYY-MM-DDTHH:mm:ss.SSSZ
Milliseconds since Unix Epoch
A compatible value can be generated using the toISOString
or toValue
method
on a Javascript Date object.
Get and update the app settings.
Returns the settings in JSON format.
Variable | Description |
---|---|
overwrite | Whether to replace settings document with input document. If both replace and overwite are set, then it overwites only. Defaults to replace. |
replace | Whether to replace existing settings for the given properties or to merge. Defaults to false (merging). |
Returns a JSON object with two fields:
{
"success": true,
"upgraded": false
}
Variable | Type | Description |
---|---|---|
success | Boolean | Always true |
upgraded | Boolean | Whether the settings doc was updated or not |
Request different types of data in various formats.
Each of the export endpoints except contacts and feedback supports a parameter which returns date formatted in human readable form (ISO 8601). Setting this parameter to false or leaving it out will return dates formatted as an epoch timestamp.
To set this parameter for a GET request use:
http://admin:pass@localhost:5988/api/v2/export/messages?options[humanReadable]=true
To set this parameter for a POST request submit this as the request body:
{
"options": {
"humanReadable": true
}
}
Exports target data formatted as a DHIS2 dataValueSet. The data can be filtered to a specific section of the contact hierarchy or for a given time interval.
Parameter | Description |
---|---|
dataSet | A DHIS2 dataSet ID. Targets associated with this dataSet will have their data aggregated. (required) |
date.from | Filter the target data to be aggregated to be within the month of this timestamp. (required) |
orgUnit | Filter the target data to only that associated with contacts with attribute { dhis: { orgUnit } } . (optional) |
{
"filters": {
"dataSet": "VMuFODsyWaO",
"date": {
"from": 949392000000,
},
"orgUnit": "KbY9DJ8mBkx"
}
}
It uses the search shared library to ensure identical results in the export and the front-end. It also only supports exporting CSV so we can efficiently stream infinitely large exports.
These are identical to the JS objects passed to the shared library, as if you were using it directly in Javascript.
You may either pass JSON in the request body using POST
:
POST /api/v2/export/reports
{
"filters": {
"forms": {
"selected": [
{
"code": "immunization_visit"
}
]
}
}
}
Or using form-style parameters as GET
:
GET /api/v2/export/reports?filters[search]=&filters[forms][selected][0][code]=immunization_visit
NB: this API is bound directly to this library. For more information on what queries you can perform with the search library, see its documentation.
Download messages.
Column | Description |
---|---|
Record UUID | The unique ID for the message in the database. |
Patient ID | The generated short patient ID for use in SMS. |
Reported Date | The date the message was received or generated. |
From | This phone number the message is or will be sent from. |
Contact Name | The name of the user this message is assigned to. |
Message Type | The type of the message |
Message State | The state of the message at the time this export was generated |
Received Timestamp | The datetime the message was received. Only applies to incoming messages. |
Other Timestamps | The datetime the message transitioned to each state. |
Sent By | The phone number the message was sent from. Only applies to incoming messages. |
To Phone | The phone number the message is or will be sent to. Only applies to outgoing messages. |
Message Body | The content of the message. |
/api/v2/export/messages
Export a file containing the user feedback.
Variable | Description |
---|---|
format | The format of the returned file, either ‘csv’ or ‘xml’. Defaults to ‘csv’. |
locale | Locale for translatable data. Defaults to ‘en’. |
tz | The timezone to show date values in, as an offset in minutes from GMT, for example ‘-120’. |
skip_header_row | ‘true’ to omit the column headings. Defaults to ‘false’. |
Returns a JSON array of contacts.
These are identical to the JS objects passed to the shared library, as if you were using it directly in Javascript.
You may either pass JSON in the request body using POST
:
POST /api/v2/export/contacts
{
"filters": {
"search": "jim"
}
}
Or using form-style parameters as GET
:
GET /api/v2/export/contacts?filters[search]=jim
Returns a list of currently installed forms (in all available formats) in JSON format.
Key | Value | Description |
---|---|---|
X-OpenRosa-Version | 1.0 | If this header is specified returns XML formatted forms list. See OpenRosa FormListAPI. |
Get list of forms currently installed.
GET /api/v1/forms
HTTP/1.1 200
Content-Type: application/json; charset=utf-8
["anc_visit.xml","anc_registration.xml","off.xml", "off.json"]
Get OpenRosa XForms compatible forms installed in XML format.
GET /api/v1/forms
Host: medic.local
X-OpenRosa-Version: 1.0
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
X-OpenRosa-Version: 1.0
<?xml version="1.0" encoding="UTF-8"?>
<xforms xmlns="http://openrosa.org/xforms/xformsList">
<xform>
<name>Visit</name>
<formID>ANCVisit</formID>
<hash>md5:1f0f096602ed794a264ab67224608cf4</hash>
<downloadUrl>http://medic.local/api/v1/forms/anc_visit.xml</downloadUrl>
</xform>
<xform>
<name>Registration with LMP</name>
<formID>PregnancyRegistration</formID>
<hash>md5:1f0f096602ed794a264ab67224608cf4</hash>
<downloadUrl>http://medic.local/api/v1/forms/anc_registration.xml</downloadUrl>
</xform>
<xform>
<name>Stop</name>
<formID>Stop</formID>
<hash>md5:1f0f096602ed794a264ab67224608cf4</hash>
<downloadUrl>http://medic.local/api/v1/forms/off.xml</downloadUrl>
</xform>
</xforms>
Return form definition for a given form ID and format.
Variable | Description |
---|---|
id | Form identifier |
format | Format string or file extension. e.g. xml, json |
Get latest version of the PregnancyRegistration form in xml (XForms) format.
GET /api/v1/forms/pregnancyregistration.xml
Get the latest version of the NPYY form in JSON format.
GET /api/v1/forms/NPYY.json
Create a new record based on a JSON form that has been configured.
Records can be created one of two ways, parsing the form data yourself and submitting a JSON object or by submitting the raw message string.
Key | Value | Description |
---|---|---|
Content-Type | application/x-www-form-urlencoded | Processes form parameters. |
Content-Type | application/json | Processes form data in request body as JSON. |
Only one variant of the Content-Type
header may be provided; RFC 2616 does not
allow multiple content types to appear in a single Content-Type
header.
Variable | Description |
---|---|
message | Message string in a supported format like Muvuku or Textforms. Depending if your Medic Mobile instance is configured in forms-only mode or not you might receive an error if the form is not found. |
from | Reporting phone number. |
reported_date | Timestamp in MS since Unix Epoch of when the message was received on the gateway. Defaults to now. |
Special values reside in the property _meta
, so you can’t have a form field named _meta
. Only strings and numbers are currently support as field values.
All property names will be lowercased.
Key | Description |
---|---|
_meta.form | The form code. |
_meta.from | Reporting phone number. Optional. |
_meta.reported_date | Timestamp in MS since Unix Epoch of when the message was received on the gateway. Defaults to now. |
_meta.locale | Optional locale string. Example: ‘fr’ |
Creating new record using message field.
POST /api/v1/records
Content-Type: application/x-www-form-urlencoded
message=1!YYYZ!Sam#23#2015#ANC&from=+5511943348031&reported_date=1352399720000
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"success": true,
"id": "364c796a843fbe0a73476f9153012733"
}
Creating new record with JSON.
POST /api/v1/records
Content-Type: application/json
{
"nurse": "Sam",
"week": 23,
"year": 2015,
"visit": "ANC",
"_meta": {
"form": "YYYZ",
"reported_date": 1352399720000
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"success": true,
"id": "364c796a843fbe0a73476f9153012733"
}
If required fields are not found return 500.
If invalid JSON return error response 500.
If submitting JSON and corresponding form is not found on the server you will receive an error.
Endpoint used by medic-gateway to send sms messages. More documentation in the medic-gateway repo.
Use JSON in the request body to specify a person’s details.
Note: this does not accomodate having a place
field on your form and will likely be revised soon.
Key | Description |
---|---|
name | String used to describe the person. |
type | ID of the contact_type for the new person. Defaults to ‘person’ for backwards compatibility. |
Key | Description |
---|---|
place | String that references a place or object that defines a new place. |
reported_date | Timestamp of when the record was reported or created. Defaults to now. |
Create new people.
By default any user can create or modify a place. Use these permissions to restrict access:
can_create_people
, can_create_places
Create new person and place hierarchy.
POST /api/v1/people
Content-Type: application/json
{
"name": "Hannah",
"phone": "+2548277210095",
"type": "contact",
"contact_type": "patient",
"place": {
"name": "CHP Area One",
"type": "health_center",
"parent": {
"name": "CHP Branch One",
"type": "district_hospital"
}
}
}
Create new person and assign existing place.
POST /api/v1/people
Content-Type: application/json
{
"name": "Samuel",
"place": "1d83f2b4a27eceb40df9e9f9ad06d137",
"type": "contact",
"contact_type": "chp"
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "71df9d25ed6732ea3b4435862510d115",
"rev": "1-a4060843d78f46a60a6f41051e40e3b5"
}
By default any user can create or modify a place.
Use JSON in the request body to specify a place’s details.
Key | Description |
---|---|
name | String used to describe the place. |
type | Place type |
parent | String that references a place or object that defines a new place. Optional for District Hospital and National Office types. |
Key | Description |
---|---|
contact | String identifier for a person or object that defines a new person. |
reported_date | Timestamp of when the record was reported or created. Defaults to now. |
Key | Description |
---|---|
clinic | Clinic |
health_center | Health Center |
district_hospital | District Hospital |
national_office | National Office |
Create a new place and optionally a contact.
By default any user can create new places. Use these permissions to restrict access:
can_create_places
, can_create_people
Create new place referencing existing parent.
POST /api/v1/places
Content-Type: application/json
{
"name": "Busia Clinic",
"type": "clinic",
"parent": "1d83f2b4a27eceb40df9e9f9ad06d137"
}
Create child and parent places.
POST /api/v1/places
Content-Type: application/json
{
"name": "CHP Area One",
"type": "health_center",
"parent": {
"name": "CHP Branch One",
"type": "district_hospital"
}
}
Also creates contact (person).
POST /api/v1/places
Content-Type: application/json
{
"name": "CHP Area One",
"type": "health_center",
"parent": {
"name": "CHP Branch One",
"type": "district_hospital"
},
"contact": {
"name": "Paul",
"phone": "+254883720611"
}
}
Or assigns them.
POST /api/v1/places
Content-Type: application/json
{
"name": "CHP Area One",
"type": "health_center",
"parent": {
"name": "CHP Branch One",
"type": "district_hospital"
},
"contact": "71df9d25ed6732ea3b4435862510ef8e"
}
Example success response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "71df9d25ed6732ea3b4435862510d115",
"rev": "1-a4060843d78f46a60a6f41051e40e3b5"
}
Error response if facility structure is not correct:
HTTP/1.1 400 Bad Request
Content-Type: text/plain
Health Centers should have "district_hospital" parent type.
Update a place and optionally its contact.
By default any user can update a place. Use these permissions to restrict access:
can_update_places
Update a place’s contact.
POST /api/v1/places/1d83f2b4a27eceb40df9e9f9ad06d137
Content-Type: application/json
{
"contact": "71df9d25ed6732ea3b4435862505f7a9"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "1d83f2b4a27eceb40df9e9f9ad06d137",
"rev": "12-a4060843d78f46a60a6f41051e40e3b5"
}
All user related requests are limited to users with admin privileges by default.
Use JSON in the request body to specify user details. Any properties submitted that are not on the list below will be ignored. Any properties not included will be undefined.
Name | Required | Type | Description | Version |
---|---|---|---|---|
username | yes | String | identifier used for authentication | |
roles | yes | Array | ||
place | yes, if the roles contain an offline role | string or object | Place identifier string (UUID) or object this user resides in. | |
contact | yes, if the roles contain an offline role | string or object | A person identifier string (UUID) or object based on the form configured in the app. | |
password | yes, if token_login is not enabled for the user | String | Password string used for authentication. Only allowed to be set, not retrieved. | |
phone | yes, if token_login is enabled for the user | String | Valid phone number | |
token_login | no | Boolean | A boolean representing whether or not the Login by SMS should be enabled for this user. | 3.10.0 |
fullname | no | String | Full name | |
no | String | Email address | ||
language | no | String | Language preference. e.g. “sw” for Swahili | |
known | no | Boolean | Boolean to define if the user has logged in before. Used mainly to determine whether or not to start a tour on first login. |
When creating or updating a user, sending a truthy value for the field token_login
will enable Login by SMS for this user.
This action resets the user’s password to an unknown string and generates a complex 64 character token, that is used to generate a token-login URL.
The URL is sent to the user’s phone number by SMS, along with another (configurable) SMS that can contain additional information.
Accessing this link, before its expiration time, will log the user in directly - without the need of any other credentials.
The link can only be accessed once, the token becomes invalid after being used for one login.
The token expires in 24 hours, after which logging in is only possible by either generating a new token, or disabling token_login
and manually setting a password.
The SMS messages are stored in a doc of a new type login_token
. These docs cannot be viewed as reports from the webapp, and can only be edited by admins, but their messages are visible in the Admin Message Queue page.
To disable login by SMS for a user, update the user sending token_login
with a false
value.
To regenerate the token, update the user sending token_login
with a true
value.
token_login | user state | action |
---|---|---|
undefined | new | None |
undefined | existent, no token | None |
undefined | existent, with token | None. Login by SMS remains enabled. Token is unchanged. |
true | new | Login by SMS enabled. Token is generated and SMS is sent. |
true | existent, no token | Password is reset. Login by SMS enabled. Token is generated and SMS is sent. Existent sessions are invalidated. |
true | existent, with token | Password is reset. Login by SMS enabled. New token is generated and SMS is sent. Old token is invalid. Existent sessions are invalidated. |
false | new | None. |
false | existent, no token | None. |
false | existent, with token | Request requires a password. Login by SMS is disabled. Old token is invalidated. Existent sessions are invalidated. |
This feature uses app_settings.app_url
and app_settings.token_login
to be defined and enabled.
If app_settings.app_url
is not defined, the generated token-login URL will use the Host
request header, which may not always be correct.
See Also: Accessing CHT Apps
Returns a list of users and their profile data in JSON format.
can_view_users
Get list of users:
GET /api/v1/users
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"id": "org.couchdb.user:admin",
"rev": "10-6486428924d11781c107ea74de6b63b6",
"type": "admin",
"username": "admin",
"language": {
"code": "en"
}
},
{
"id": "org.couchdb.user:demo",
"rev": "14-8758c8493edcc6dac50366173fc3e24a",
"type": "district-manager",
"fullname": "Example User",
"username": "demo",
"language": {
"code": "en"
},
"place": {
"_id": "eeb17d6d-5dde-c2c0-62c4a1a0ca17d38b",
"type": "district_hospital",
"name": "Sample District",
"contact": {
"_id": "eeb17d6d-5dde-c2c0-62c4a1a0ca17fd17",
"type": "person",
"name": "Paul",
"phone": "+2868917046"
}
},
"contact": {
"_id": "eeb17d6d-5dde-c2c0-62c4a1a0ca17fd17",
"type": "person",
"name": "Paul",
"phone": "+2868917046"
}
}
]
Create a new user with a place and a contact.
can_create_users
, can_create_places
, can_create_people
Create a new user that can authenticate with a username of “mary” and password of “secret” that can submit reports and view or modify records associated to their place. The place is created in the background and automatically linked to the contact.
POST /api/v1/users
Content-Type: application/json
{
"password": "secret",
"username": "mary",
"type": "district-manager",
"place": {
"name": "Mary's Area",
"type": "health_center",
"parent": "d14e1c3d557761320b13a77e7806e8f8"
},
"contact": {
"name": "Mary Anyango",
"phone": "+2868917046"
}
}
HTTP/1.1 200
Content-Type: application/json
{
"contact": {
"id": "65416b8ceb53ff88ac1847654501aeb3",
"rev": "1-0b74d219ae13137c1a06f03a0a52e187"
},
"user-settings": {
"id": "org.couchdb.user:mary",
"rev": "1-6ac1d36b775143835f4af53f9895d7ae"
},
"user": {
"id": "org.couchdb.user:mary",
"rev": "1-c3b82a0b47cfe68edd9284c89bebbae4"
}
}
Response if the username already exists:
HTTP/1.1 409 Conflict
Content-Type: text/plain
Document update conflict.
Allows you to change property values on a user account. Properties listed above
are supported except for contact.parent
. Creating or modifying people
through the user is not supported, see People section.
can_update_users
, can_update_places
, can_update_people
You do not need any of the above permissions if the user you are modifying is yourself. However, you are not allowed to modify your type
, roles
, contact
or place
.
Further more, if you’re updating your password
you must be authenticating via Basic Auth (either the header or in the URL). This is to ensure the password is known at time of request, and no one is hijacking a cookie.
Variable | Description |
---|---|
username | String identifier used for authentication. |
POST /api/v1/users/mary
Content-Type: application/json
{
"password": "secret",
"place": "eeb17d6d-5dde-c2c0-62c4a1a0ca17e342"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"user": {
"id": "org.couchdb.user:mary",
"rev": "23-858e01fafdfa0d367d798fe5b44751ff"
},
"user-settings": {
"id": "org.couchdb.user:mary",
"rev": "17-c6d03b86d2d5d70f7270c85e67fea96d"
}
}
Delete a user. Does not affect a person or place associated to a user.
can_delete_users
Variable | Description |
---|---|
username | String identifier used for authentication. |
DELETE /api/v1/users/mary
HTTP/1.1 200 OK
Returns the number of documents an offline user would replicate, along with a warn
flag if this number exceeds the recommended limit (now set at 10 000).
When the authenticated requester has an offline role, it returns the requester doc count.
GET /api/v1/users-info -H 'Cookie: AuthSession=OFFLINE_USER_SESSION;'
HTTP/1.1 200 OK
Content-Type: application/json
{
"total_docs": 5678,
"warn": false,
"limit: 10000
}
When the requester has an online role, the following query parameters are accepted:
Variable | Description | Required |
---|---|---|
facility_id | String identifier representing the uuid of the user’s facility | true |
role | String identifier representing the user role - must be configured as an offline role. Accepts valid UTF-8 JSON array for multiple of roles. | true |
contact_id | String identifier representing the uuid of the user’s associated contact | false |
GET /api/v1/users-info?facility_id={{facility_uuid}}&role={{role}}&contact_id={{contact_uuid}} -H 'Cookie: AuthSession=OFFLINE_USER_SESSION;'
HTTP/1.1 200 OK
Content-Type: application/json
{
"total_docs": 10265,
"warn": true,
"limit: 10000
}
In case any of the required query parameters are omitted or the requested role is not configured as an offline role, the request will result in an error:
GET /api/v1/users-info?role={{online_role}} -H 'Cookie: AuthSession=OFFLINE_USER_SESSION;'
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"code": 400,
"error": "Missing required query params: role and/or facility_id"
}
Bulk delete endpoint for deleting large numbers of documents. Docs will be batched into groups of 100 and will be sent sequentially to couch (new batch sent after the previous one has returned). The response will be chunked JSON (one batch at a time), so if you wish to get an indication of progress you will need to parse incomplete JSON (with a library such as partial-json-parser
.
Only available to online users.
Parameter | Description |
---|---|
docs | Array of JSON objects with _id properties |
An array of objects each with an _id
property is required (rather than an array of strings representing ids) to ensure forwards compatibility if we choose to require that any additional document information (such as _rev
) also be passed in to this endpoint.
If an error is encountered part-way through the response (eg on the third batch), it’s impossible to send new headers to indicate a 5xx error, so the connection will simply be terminated (as recommended here https://github.com/expressjs/express/issues/2700).
POST /api/v1/bulk-delete
Content-Type: application/json
{
"docs": [
{ "_id": "id1" },
{ "_id": "id2" },
...
{ "_id": "id150" }
]
}
HTTP/1.1 200 OK
Content-Type: application/json
[
[
{ "ok": true, "id": "id1", "rev": "1-rev1" },
{ "ok": true, "id": "id2", "rev": "1-rev2" },
...
{ "ok": true, "id": "id100", "rev": "1-rev100" }
],
[
{ "ok": true, "id": "id101", "rev": "1-rev101" },
{ "ok": true, "id": "id102", "rev": "1-rev102" },
...
{ "ok": true, "id": "id150", "rev": "1-rev150" }
]
]
Used to retrieve a range of metrics about the instance. While the output is human readable this is intended for automated monitoring allowing for tracking trends over time and alerting about potential issues.
No permissions required.
curl http://localhost:5988/api/v1/monitoring
{"version":{"app":"3.9.0","node":"v10.16.0","couchdb":"2.3.1"},"couchdb":{"medic":{"name":"medic","update_sequence":5733,"doc_count":278,"doc_del_count":32,"fragmentation":1.0283517758420173}...
JSON path | Type | Description |
---|---|---|
version.app | String | The version of the webapp. |
version.node | String | The version of NodeJS. |
version.couchdb | String | The version of CouchDB. |
couchdb.<dbname>.name | String | The name of the db, usually one of “medic”, “medic-sentinel”, “medic-users-meta”, “_users”. |
couchdb.<dbname>.update_sequence | Number | The number of changes in the db. |
couchdb.<dbname>.doc_count | Number | The number of docs in the db. |
couchdb.<dbname>.doc_del_count | Number | The number of deleted docs in the db. |
couchdb.<dbname>.fragmentation | Number | The fragmentation of the db, lower is better, “1” is no fragmentation. |
date.current | Number | The current server date in millis since the epoch, useful for ensuring the server time is correct. |
date.uptime | Number | How long API has been running. |
sentinel.backlog | Number | Number of changes yet to be processed by Sentinel. |
messaging.outgoing.due | Number | The number of messages due to be sent. |
messaging.outgoing.scheduled | Number | The number of messages scheduled to be sent in the future. |
messaging.outgoing.muted | Number | The number of messages that are muted and therefore will not be sent. |
outbound_push.backlog | Number | Number of changes yet to be processed by Outbound Push. |
feedback.count | Number | Number of feedback docs created usually indicative of client side errors. |
conflict.count | Number | Number of doc conflicts which need to be resolved manually. |
replication_limit.count | Number | Number of users that exceeded the replication limit of documents. |
""
(for string values) or -1
(for numeric values) indicates an error occurred while querying the metric - check the API logs for details.All of these endpoints require the can_configure
permission.
All of these endpoints are asynchronous. Progress can be followed by watching the horti-upgrade
document and looking at the log
property.
Performs a complete upgrade to the provided version. This is equivalent of calling /api/v1/upgrade/stage
and then /api/v1/upgrade/complete
once staging has finished.
POST /api/v1/upgrade
{
"build": {
"namespace": "medic",
"application": "medic",
"version": "3.0.0-beta.1"
}
}
For potential forwards compatibility, you must pass the namespace
and application
as medic
.
The version
should correspond to a release, pre-release or branch that has been pushed to our builds server, which is currently hard-coded to https://staging.dev.medicmobile.org/builds
. This happens automatically upon a successful travis run.
Calling this endpoint will eventually cause api and sentinel to restart.
It is expected that the caller ensures forwards or backwards compatibility is maintained between deployed versions. This endpoint does not stop you from “upgrading” to an earlier version, or a branch that is incompatible with your current state.
Stages an upgrade to the provided version. Does as much of the upgrade as possible without actually swapping versions over and restarting.
Parameters are the same as /api/v1/upgrade
.
You know that an upgrade has been staged when the horti-upgrade
document in CouchDB has "action": "stage"
and "staging_complete": true
.
Completes a staged upgrade. Throws a 404
if there is no upgrade in the staged position.
Accepts a JSON array of document uuids and returns fully hydrated documents, in the same order in which they were requested.
When documents are not found, an entry with the missing uuid and an error is added instead.
Supports both GET and POST.
Only allowed for users with “online” roles.
Name | Required | Description |
---|---|---|
doc_ids | true | A JSON array of document uuids |
GET /api/v1/hydrate?doc_ids=["id1","missingId","id3"]
HTTP/1.1 200 OK
Content-Type: application/json
[
{ "id": "id1", "doc": { <...the hydrated document...> } },
{ "id": "missingId1", "error": "not_found" },
{ "id": "id3", "doc": { <...the hydrated document...> } },
]
Name | Required | Description |
---|---|---|
doc_ids | true | A JSON array of document uuids |
POST /api/v1/hydrate
Content-Type: application/json
{
"doc_ids": ["id1","missingId","id3"]
}
HTTP/1.1 200 OK
Content-Type: application/json
[
{ "id": "id1", "doc": { <...the hydrated document...> } },
{ "id": "missingId", "error": "not_found" },
{ "id": "id3", "doc": { <...the hydrated document...> } },
]
Added in 3.10.0 Accepts a phone number parameter and returns fully hydrated contacts that match the requested phone number. If multiple contacts are found, all are returned. When no matches are found, a 404 error is returned. Supports both GET and POST. Only allowed for users with “online” roles.
Name | Required | Description |
---|---|---|
phone | true | A URL encoded string representing a phone number |
GET /api/v1/contacts-by-phone?phone="%2B40-(744)-999-999"
HTTP/1.1 200 OK
Content-Type: application/json
{
"ok": true,
"docs": {
{ <... first hydrated matching contact found ...> },
{ <... second hydrated matching contact found ...> },
...
}
}
Name | Required | Description |
---|---|---|
phone | true | A string representing a phone number |
POST /api/v1/contacts-by-phone
Content-Type: application/json
{
"phone": "+40 (21) 222-3333"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ok": true,
"docs": {
{ <... first hydrated matching contact found ...> },
{ <... second hydrated matching contact found ...> },
...
}
}
Added in 3.11.0 Returns the quantity of documents that were replicated by each user. Accepts filtering by user name, when not provided, it returns all users. Supports GET. Only allowed for users with “_admin” role.
Name | Required | Description |
---|---|---|
user | false | User’s name |
GET /api/v1/users-doc-count?user=mary"
HTTP/1.1 200 OK
Content-Type: application/json
{
"limit": 10000,
"users": {
"_id": "replication-count-mary",
"_rev": "5-cd3252e852ae075da216c3c3fe461291",
"user": "mary",
"date": 1595328973273,
"count": 58
}
}
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.