From 01752bdcfbcf0bc25c400114a3bdcc71f81855c1 Mon Sep 17 00:00:00 2001 From: apoorvapendse Date: Mon, 18 Aug 2025 17:57:38 +0530 Subject: [PATCH 01/20] feat(#10221): add documentation to create/update a person Signed-off-by: apoorvapendse --- content/en/building/reference/api.md | 167 +++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 7130c4fa00..6ac62a960f 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1259,6 +1259,173 @@ Content-Type: application/json; charset=utf-8 } ``` +### POST /api/v1/person + +*Added in x.x.x* +#### Description +Used to create a person. + +#### Supported Properties + +Use JSON in the request body to specify a person’s details. + +#### Permissions +Should have `can_edit` or both `can_view_contacts` and `can_create_people`. + +#### Required +| Field | Description | Format | +| ---- | ----------------------------------- | -------- | +| name | Name of the person. | string | +| type | ID of the `contact_type` for the new person. Pass in `person` for older versions. | string | +| parent | ID of the parent document, which is a place, for the new person. The type of the parent must belong to one of the allowed `parents` for the `contact_type` id in the settings config. | UUID string | + +#### Optional + +| Field | Description | Format | +| ------------- | ---------------------------------------------------------------------- | ----------- | +| reported_date | Timestamp of when the record was reported or created. Defaults to now. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | +| _id | ID of the new person document to be created. | UUID string | +| short_name | String to denote short name of the person. | string | +| phone | Phone number of the person in string format. | string | +| role | Role of the person in string format. | string | + + +#### Examples +Create a person with a clinic as its parent place. + +```bash +POST /api/v1/person +Content-type: application/json + +{ + "name": "dummyuser", + "type": "person", + "parent":"01992f01-f155-4386-8538-5080c3155585" +} +``` + +Example response: +```json +{ + "_id": "4dcd842e813fd1bcabec03f98f002a98", + "_rev": "1-bf4ecb779a3a369f6162a149853cbb02", + "name": "dummyuser", + "type": "contact", + "parent": { + "_id": "01992f01-f155-4386-8538-5080c3155585", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + } + }, + "reported_date": 1755519112122, + "contact_type": "person" +} +``` + +### PUT /api/v1/person + +*Added in x.x.x* +#### Description +Used to update mutable fields of a person, or delete them if they are not part of update payload. + +#### Supported Properties + +Use JSON in the request body to specify a person’s details. + +#### Permissions +Either of the two: +1. `can_edit` +2. `can_view_contacts` and `can_update_people` + +#### Required immutable fields +| Field | Description | Format | +| ---- | ----------------------------------- | -------- | +| _id | ID of the person doc to be updated. | UUID string | +| _rev | Revision ID of the person doc to be updated. | string | +| reported_date | Timestamp of when the record was reported or created. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch | +| contact_type| Required if the type of the person is `contact`. | string | +| type | The type of the person. | string | +| parent | The parent lineage of the person to be updated. | Minified or hydrated parent lineage | + +#### Required mutable fields +| Field | Description | +| ---- | ----------------------------------- | +| name | Name of the person. | + +#### Examples +Updating `sex` from "male" to "female" and deleting the `short_name` field + +Original Doc: +```json +{ + "_id": "4dcd842e813fd1bcabec03f98f004c96", + "_rev": "1-1492a8ddf25a350cdd35c217a561f27a", + "name": "dummyuser", + "type": "contact", + "parent": { + "_id": "01992f01-f155-4386-8538-5080c3155585", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + } + }, + "sex": "male", + "short_name": "userX", + "reported_date": 1755519752958, + "contact_type": "person" +} +``` + +Request Body: +```bash +PUT /api/v1/person +{ + "_id": "4dcd842e813fd1bcabec03f98f004c96", + "_rev": "1-1492a8ddf25a350cdd35c217a561f27a", + "name": "dummyuser", + "type": "contact", + "parent": { + "_id": "01992f01-f155-4386-8538-5080c3155585", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + } + }, + "sex": "female", + "reported_date": 1755519752958, + "contact_type": "person" +} +``` + +Response: +```json +{ + "_id": "4dcd842e813fd1bcabec03f98f004c96", + "_rev": "2-3100df4acfd79b641173ff7d0d53e871", + "name": "dummyuser", + "type": "contact", + "parent": { + "_id": "01992f01-f155-4386-8538-5080c3155585", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + } + }, + "sex": "female", + "reported_date": 1755519752958, + "contact_type": "person" +} +``` + ## People ### Supported Properties From e57d4bc1f5f640b6bda3a65ae1f6ad9125a0b534 Mon Sep 17 00:00:00 2001 From: Apoorva Pendse Date: Tue, 19 Aug 2025 19:38:54 +0530 Subject: [PATCH 02/20] create place documentation Signed-off-by: Apoorva Pendse --- content/en/building/reference/api.md | 75 ++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 6ac62a960f..bd05a4d73d 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1789,6 +1789,81 @@ Content-Type: application/json; charset=utf-8 } ``` +### POST /api/v1/place + +*Added in x.x.x* +#### Description +Used to create a place. + +#### Supported Properties + +Use JSON in the request body to specify the details of a place. + +#### Permissions +Should have `can_edit` or both `can_view_contacts` and `can_create_places`. + +#### Required +| Field | Description | Format | +| ---- | ----------------------------------- | -------- | +| name | Name of the place. | string | +| type | ID of the `contact_type` for the new place. Pass in `place` for older versions. | string | +| parent | ID of the parent document. The type of the parent must belong to one of the allowed `parents` for the `contact_type` id in the settings config. | UUID string | + +Note: Places that are at the top of the hierarchy, should not have a `parent`. +Doing so will result in an "Unexpected parent for {placePayload} error." + +#### Optional + +| Field | Description | Format | +| ------------- | ---------------------------------------------------------------------- | ----------- | +| reported_date | Timestamp of when the record was reported or created. Defaults to now. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | +| _id | ID of the new place document to be created. | UUID string | +| contact | ID of the primary person contact to be linked with the created place. | UUID string | + +#### Examples + +Request: +```bash +POST /api/v1/place +Content-Type: application/json + +{ + "name": "test place", + "type": "clinic", + "parent":"35a2f31e-705c-4833-b385-efd069b1ce3f", + "contact":"00058058-e637-4e65-b5db-cd4b2da4375e" +} +``` + +Response: +```json +{ + "_id": "36aed043a50315f00f625af18c0043af", + "_rev": "1-9ffb5015e3ec6a800e8f70d6c9ea12ee", + "name": "test place", + "type": "contact", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + }, + "contact": { + "_id": "00058058-e637-4e65-b5db-cd4b2da4375e", + "parent": { + "_id": "0fc7c7c4-76c0-4c1b-8eac-43ee5b42f646", + "parent": { + "_id": "c79e489a-1ee0-4537-a618-bfab496a7e29", + "parent": { + "_id": "a177578c-a2a2-4731-931c-2bbff842d0f4" + } + } + } + }, + "reported_date": "2025-08-19T14:30:25.568Z", + "contact_type": "clinic" +} +``` ## Places From ab7235b7e22cd3ac3bc300b04ccfa669fcbc6ca6 Mon Sep 17 00:00:00 2001 From: apoorvapendse Date: Tue, 19 Aug 2025 20:25:28 +0530 Subject: [PATCH 03/20] update place documentation Signed-off-by: apoorvapendse --- content/en/building/reference/api.md | 114 +++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index bd05a4d73d..b628df9aaf 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1792,6 +1792,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/place *Added in x.x.x* + #### Description Used to create a place. @@ -1865,6 +1866,119 @@ Response: } ``` +### PUT /api/v1/place + +#### Description +Used to update mutable fields of a place, or delete them if they are not part of update payload. + +#### Supported Properties + +Use JSON in the request body to specify the details of a place. + +#### Permissions +Should have `can_edit` or both `can_view_contacts` and `can_update_places`. + +#### Required immutable fields +| Field | Description | Format | +| ---- | ----------------------------------- | -------- | +| _id | ID of the place doc to be updated. | UUID string | +| _rev | Revision ID of the place doc to be updated. | string | +| reported_date | Timestamp of when the record was reported or created. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch | +| contact_type| Required if the type of the place is `contact`. | string | +| type | The type of the place. | string | +| parent | The parent lineage of the place to be updated. Not required if the place is at the top of the hierarchy. | Minified or hydrated parent lineage | +| contact | The contact lineage linked with the place. This can be inserted as a part of update if not already present. | Minified or hydrated lineage | + +### Required mutable fields +| Field | Description | Format | +| ---- | ----------------------------------- | -------- | +| name | The name of the place. | string | + +#### Examples + +**Adding `contact` field as a part of the update and changing `name` of the place.** + +Original place object: +```json +{ + "_id": "36aed043a50315f00f625af18c004bcf", + "_rev": "1-d29dc4cf44845f0c1842bcd57390d1d3", + "name": "test place", + "type": "contact", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + }, + "reported_date": "2025-08-19T14:48:16.436Z", + "contact_type": "clinic" +} +``` + +Request: +```bash +PUT /api/v1/place +Content-Type: application/json + +{ + "_id": "36aed043a50315f00f625af18c004bcf", + "_rev": "1-d29dc4cf44845f0c1842bcd57390d1d3", + "name": "new place", + "type": "contact", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + }, + "contact": { + "_id": "00058058-e637-4e65-b5db-cd4b2da4375e", + "parent": { + "_id": "0fc7c7c4-76c0-4c1b-8eac-43ee5b42f646", + "parent": { + "_id": "c79e489a-1ee0-4537-a618-bfab496a7e29", + "parent": { + "_id": "a177578c-a2a2-4731-931c-2bbff842d0f4" + } + } + } + }, + "reported_date": "2025-08-19T14:48:16.436Z", + "contact_type": "clinic" +} +``` + +Response: +```json +{ + "_id": "36aed043a50315f00f625af18c004bcf", + "_rev": "2-7d9114d21f80451b436d6d25d8ac5a75", + "name": "new place", + "type": "contact", + "parent": { + "_id": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "parent": { + "_id": "29368c93-d267-4e80-8fbe-6543f702ff30" + } + }, + "contact": { + "_id": "00058058-e637-4e65-b5db-cd4b2da4375e", + "parent": { + "_id": "0fc7c7c4-76c0-4c1b-8eac-43ee5b42f646", + "parent": { + "_id": "c79e489a-1ee0-4537-a618-bfab496a7e29", + "parent": { + "_id": "a177578c-a2a2-4731-931c-2bbff842d0f4" + } + } + } + }, + "reported_date": "2025-08-19T14:48:16.436Z", + "contact_type": "clinic" +} +``` + ## Places By default any user can create or modify a place. From c8906e41f4045b81cdf6ba8728a97a1caafce8a6 Mon Sep 17 00:00:00 2001 From: apoorvapendse Date: Sun, 24 Aug 2025 17:33:22 +0530 Subject: [PATCH 04/20] report create/update documentation Signed-off-by: apoorvapendse --- content/en/building/reference/api.md | 156 +++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index b628df9aaf..ed57339a8e 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -2407,6 +2407,162 @@ Content-Type: application/json; charset=utf-8 } ``` +### POST /api/v1/report + +*Added in x.x.x* +#### Description +Used to create a report. + +#### Supported Properties + +Use JSON in the request body to specify a report’s details. + +#### Permissions +Should have `can_view_reports` and `can_create_records`. + +#### Required +| Field | Description | Format | +| ---- | ----------------------------------- | -------- | +| form | Must be a valid form value from the forms available in the `medic-client/doc_by_type` view (queried with key=["form"]).| string | +| type | Type of the report. | string | +| contact | ID of the contact document which can be either a person or place, for the new report | UUID string | + +Note: A valid `form` value, `type` being `data_record` and having a valid `contact` is necessary for the report to appear in the webapp. + +#### Optional + +| Field | Description | Format | +| ------------- | ---------------------------------------------------------------------- | ----------- | +| reported_date | Timestamp of when the record was reported or created. Defaults to now. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | +| _id | ID of the new report document to be created. | UUID string | +| fields | Fields containing the report data | Object | + +#### Examples +Request: +```bash +POST /api/v1/report +Content-type: application/json + +{ + "form":"pregnancy_home_visit", + "type":"data_record", + "contact":"00ba941a-a052-4e45-ada7-c32f59542133" +} +``` + +Response: +```json +{ + "_id": "b8208fa332bf1f09b606e6efd8002a4a", + "_rev": "1-9ffca0e670bcc111de86f68ae8f47d3b", + "form": "pregnancy_home_visit", + "type": "data_record", + "contact": { + "_id": "00ba941a-a052-4e45-ada7-c32f59542133", + "parent": { + "_id": "4583e5aa-b1c1-40d4-9f65-ce63610b8c52", + "parent": { + "_id": "f0d44e4c-bd37-44a2-a7a5-dd38de32d9a2" + } + } + }, + "reported_date": "2025-08-24T11:37:06.815Z" +} +``` + +### PUT /api/v1/report + +#### Description +Used to update a report. + +#### Supported Properties + +Use JSON in the request body to specify a report’s details. + +#### Permissions +Should have `can_view_reports` and `can_update_records`. + +#### Required immutable fields +| Field | Description | Format | +| ---- | ----------------------------------- | -------- | +| type | Type of the report. | string | +| contact | Contact document associated with the report | Minified or hydrated contact lineage | +| reported_date | Timestamp of when the record was reported or created. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | +| _id | ID of the report document to be updated. | UUID string | +| _rev | Revision ID of the report doc to be updated. | string | + + +#### Required mutable fields +| Field | Description | Format | +| ------------- | ---------------------------------------------------------------------- | ----------- | +| form | Must be a valid form value from the forms available in the `medic-client/doc_by_type` view (queried with key=["form"]). | string | + +#### Examples + +Changing form value from `pregnancy_home_visit` to `pregnancy_danger_sign` + +Original Document: +```json +{ + "_id": "b8208fa332bf1f09b606e6efd8002a4a", + "_rev": "1-9ffca0e670bcc111de86f68ae8f47d3b", + "form": "pregnancy_home_visit", + "type": "data_record", + "contact": { + "_id": "00ba941a-a052-4e45-ada7-c32f59542133", + "parent": { + "_id": "4583e5aa-b1c1-40d4-9f65-ce63610b8c52", + "parent": { + "_id": "f0d44e4c-bd37-44a2-a7a5-dd38de32d9a2" + } + } + }, + "reported_date": "2025-08-24T11:37:06.815Z" +} +``` + +Request: +```bash +PUT /api/v1/report +Content-type: application/json +{ + "_id": "b8208fa332bf1f09b606e6efd8002a4a", + "_rev": "1-9ffca0e670bcc111de86f68ae8f47d3b", + "form": "pregnancy_danger_sign", + "type": "data_record", + "contact": { + "_id": "00ba941a-a052-4e45-ada7-c32f59542133", + "parent": { + "_id": "4583e5aa-b1c1-40d4-9f65-ce63610b8c52", + "parent": { + "_id": "f0d44e4c-bd37-44a2-a7a5-dd38de32d9a2" + } + } + }, + "reported_date": "2025-08-24T11:37:06.815Z" +} + +``` + +Response: +```json +{ + "_id": "b8208fa332bf1f09b606e6efd8002a4a", + "_rev": "2-82b274ab67cf5fbab0ea870cbb62ab48", + "form": "pregnancy_danger_sign", + "type": "data_record", + "contact": { + "_id": "00ba941a-a052-4e45-ada7-c32f59542133", + "parent": { + "_id": "4583e5aa-b1c1-40d4-9f65-ce63610b8c52", + "parent": { + "_id": "f0d44e4c-bd37-44a2-a7a5-dd38de32d9a2" + } + } + }, + "reported_date": "2025-08-24T11:37:06.815Z" +} +``` ## Users All user related requests are limited to users with admin privileges by default. From 79e86a91f4cac2ca2b7f990846d429ce0e01317e Mon Sep 17 00:00:00 2001 From: Apoorva Pendse Date: Mon, 25 Aug 2025 11:59:36 +0530 Subject: [PATCH 05/20] Update content/en/building/reference/api.md Co-authored-by: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> --- content/en/building/reference/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index ed57339a8e..a6c70593a2 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1896,7 +1896,7 @@ Should have `can_edit` or both `can_view_contacts` and `can_update_places`. #### Examples -**Adding `contact` field as a part of the update and changing `name` of the place.** +Adding `contact` field as a part of the update and changing `name` of the place. Original place object: ```json From 0bf38464a5ee6c098f89f2bb5ce54c7f6b5f4188 Mon Sep 17 00:00:00 2001 From: Apoorva Pendse Date: Mon, 25 Aug 2025 12:21:30 +0530 Subject: [PATCH 06/20] formatting and other minor fixes Signed-off-by: Apoorva Pendse --- content/en/building/reference/api.md | 149 ++++++++++++++------------- 1 file changed, 75 insertions(+), 74 deletions(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index a6c70593a2..66f33a1daf 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1261,7 +1261,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/person -*Added in x.x.x* +*Added in 5.0.0* #### Description Used to create a person. @@ -1273,21 +1273,22 @@ Use JSON in the request body to specify a person’s details. Should have `can_edit` or both `can_view_contacts` and `can_create_people`. #### Required -| Field | Description | Format | -| ---- | ----------------------------------- | -------- | -| name | Name of the person. | string | -| type | ID of the `contact_type` for the new person. Pass in `person` for older versions. | string | -| parent | ID of the parent document, which is a place, for the new person. The type of the parent must belong to one of the allowed `parents` for the `contact_type` id in the settings config. | UUID string | +| Field | Description | Format | +|--------|-----------------------------------------------------------------------------------------------------------------------------------|------------| +| name | Name of the person. | string | +| type | ID of the `contact_type` for the new person. Use `person` for older versions. | string | +| parent | ID of the parent document (a place) for the new person. The parent’s type must match one of the allowed `parents` in the settings. | UUID string | #### Optional -| Field | Description | Format | -| ------------- | ---------------------------------------------------------------------- | ----------- | -| reported_date | Timestamp of when the record was reported or created. Defaults to now. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | -| _id | ID of the new person document to be created. | UUID string | -| short_name | String to denote short name of the person. | string | -| phone | Phone number of the person in string format. | string | -| role | Role of the person in string format. | string | +| Field | Description | Format | +|---------------|-----------------------------------------------------------------------------|--------------------------------------------------| +| reported_date | Timestamp of when the record was reported or created. Defaults to `now`. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | +| _id | ID of the new person document to be created. | UUID string | +| short_name | Short name of the person. | string | +| phone | Phone number of the person (string format). | string | +| role | Role of the person (string format). | string | + #### Examples @@ -1327,7 +1328,7 @@ Example response: ### PUT /api/v1/person -*Added in x.x.x* +*Added in 5.0.0* #### Description Used to update mutable fields of a person, or delete them if they are not part of update payload. @@ -1336,24 +1337,22 @@ Used to update mutable fields of a person, or delete them if they are not part o Use JSON in the request body to specify a person’s details. #### Permissions -Either of the two: -1. `can_edit` -2. `can_view_contacts` and `can_update_people` +Should have `can_edit` or both `can_view_contacts` and `can_update_people`. #### Required immutable fields -| Field | Description | Format | -| ---- | ----------------------------------- | -------- | -| _id | ID of the person doc to be updated. | UUID string | -| _rev | Revision ID of the person doc to be updated. | string | -| reported_date | Timestamp of when the record was reported or created. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch | -| contact_type| Required if the type of the person is `contact`. | string | -| type | The type of the person. | string | -| parent | The parent lineage of the person to be updated. | Minified or hydrated parent lineage | +| Field | Description | Format | +|---------------|---------------------------------------------------------------|----------------------------------------------------------| +| _id | ID of the person document to be updated. | UUID string | +| _rev | Revision ID of the person document to be updated. | string | +| reported_date | Timestamp of when the record was reported or created. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | +| contact_type | Required if the type of the person is `contact`. | string | +| type | The type of the person. | string | +| parent | The parent lineage of the person to be updated. | Minified or hydrated parent lineage | #### Required mutable fields -| Field | Description | -| ---- | ----------------------------------- | -| name | Name of the person. | +| Field | Description | +|-------|------------------------| +| name | Name of the person. | #### Examples Updating `sex` from "male" to "female" and deleting the `short_name` field @@ -1791,7 +1790,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/place -*Added in x.x.x* +*Added in 5.0.0* #### Description Used to create a place. @@ -1804,22 +1803,22 @@ Use JSON in the request body to specify the details of a place. Should have `can_edit` or both `can_view_contacts` and `can_create_places`. #### Required -| Field | Description | Format | -| ---- | ----------------------------------- | -------- | -| name | Name of the place. | string | -| type | ID of the `contact_type` for the new place. Pass in `place` for older versions. | string | -| parent | ID of the parent document. The type of the parent must belong to one of the allowed `parents` for the `contact_type` id in the settings config. | UUID string | +| Field | Description | Format | +|--------|----------------------------------------------------------------------------------------------------------------------|------------| +| name | Name of the place. | string | +| type | ID of the `contact_type` for the new place. Use `place` for older versions. | string | +| parent | ID of the parent document. The parent’s type must match one of the allowed `parents` in the settings configuration. | UUID string | Note: Places that are at the top of the hierarchy, should not have a `parent`. Doing so will result in an "Unexpected parent for {placePayload} error." #### Optional -| Field | Description | Format | -| ------------- | ---------------------------------------------------------------------- | ----------- | -| reported_date | Timestamp of when the record was reported or created. Defaults to now. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | -| _id | ID of the new place document to be created. | UUID string | -| contact | ID of the primary person contact to be linked with the created place. | UUID string | +| Field | Description | Format | +|---------------|-----------------------------------------------------------------------------|--------------------------------------------------| +| reported_date | Timestamp of when the record was reported or created. Defaults to `now`. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | +| _id | ID of the new place document to be created. | UUID string | +| contact | ID of the primary person contact to be linked with the created place. | UUID string | #### Examples @@ -1879,20 +1878,21 @@ Use JSON in the request body to specify the details of a place. Should have `can_edit` or both `can_view_contacts` and `can_update_places`. #### Required immutable fields -| Field | Description | Format | -| ---- | ----------------------------------- | -------- | -| _id | ID of the place doc to be updated. | UUID string | -| _rev | Revision ID of the place doc to be updated. | string | -| reported_date | Timestamp of when the record was reported or created. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch | -| contact_type| Required if the type of the place is `contact`. | string | -| type | The type of the place. | string | -| parent | The parent lineage of the place to be updated. Not required if the place is at the top of the hierarchy. | Minified or hydrated parent lineage | -| contact | The contact lineage linked with the place. This can be inserted as a part of update if not already present. | Minified or hydrated lineage | - -### Required mutable fields -| Field | Description | Format | -| ---- | ----------------------------------- | -------- | -| name | The name of the place. | string | +| Field | Description | Format | +|---------------|--------------------------------------------------------------------------------------------------|-------------------------------------| +| _id | ID of the place document to be updated. | UUID string | +| _rev | Revision ID of the place document to be updated. | string | +| reported_date | Timestamp of when the record was reported or created. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | +| contact_type | Required if the type of the place is `contact`. | string | +| type | The type of the place. | string | +| parent | The parent lineage of the place to be updated. Not required if the place is at the top of the hierarchy. | Minified or hydrated parent lineage | +| contact | The contact lineage linked with the place. This can be added during update if not already present. | Minified or hydrated lineage | + +#### Required mutable fields +| Field | Description | Format | +|-------|----------------------|--------| +| name | The name of the place. | string | + #### Examples @@ -2409,7 +2409,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/report -*Added in x.x.x* +*Added in 5.0.0* #### Description Used to create a report. @@ -2421,21 +2421,21 @@ Use JSON in the request body to specify a report’s details. Should have `can_view_reports` and `can_create_records`. #### Required -| Field | Description | Format | -| ---- | ----------------------------------- | -------- | -| form | Must be a valid form value from the forms available in the `medic-client/doc_by_type` view (queried with key=["form"]).| string | -| type | Type of the report. | string | -| contact | ID of the contact document which can be either a person or place, for the new report | UUID string | +| Field | Description | Format | +|---------|------------------------------------------------------------------------------------------------------------------|------------| +| form | Must be a valid form value from the forms available in the `medic-client/doc_by_type` view (queried with `key=["form"]`). | string | +| type | Type of the report. | string | +| contact | ID of the contact document (can be either a person or a place) for the new report. | UUID string | Note: A valid `form` value, `type` being `data_record` and having a valid `contact` is necessary for the report to appear in the webapp. #### Optional -| Field | Description | Format | -| ------------- | ---------------------------------------------------------------------- | ----------- | -| reported_date | Timestamp of when the record was reported or created. Defaults to now. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | -| _id | ID of the new report document to be created. | UUID string | -| fields | Fields containing the report data | Object | +| Field | Description | Format | +|---------------|-----------------------------------------------------------------------------|--------------------------------------------------| +| reported_date | Timestamp of when the record was reported or created. Defaults to `now`. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | +| _id | ID of the new report document to be created. | UUID string | +| fields | Fields containing the report data. | Object | #### Examples Request: @@ -2483,19 +2483,20 @@ Use JSON in the request body to specify a report’s details. Should have `can_view_reports` and `can_update_records`. #### Required immutable fields -| Field | Description | Format | -| ---- | ----------------------------------- | -------- | -| type | Type of the report. | string | -| contact | Contact document associated with the report | Minified or hydrated contact lineage | -| reported_date | Timestamp of when the record was reported or created. | 'YYYY-MM-DDTHH:mm:ssZ', 'YYYY-MM-DDTHH:mm:ss.SSSZ', or unix epoch. | -| _id | ID of the report document to be updated. | UUID string | -| _rev | Revision ID of the report doc to be updated. | string | +| Field | Description | Format | +|---------------|---------------------------------------------------------------|--------------------------------------------------| +| type | Type of the report. | string | +| contact | Contact document associated with the report. | Minified or hydrated contact lineage | +| reported_date | Timestamp of when the record was reported or created. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | +| _id | ID of the report document to be updated. | UUID string | +| _rev | Revision ID of the report document to be updated. | string | #### Required mutable fields -| Field | Description | Format | -| ------------- | ---------------------------------------------------------------------- | ----------- | -| form | Must be a valid form value from the forms available in the `medic-client/doc_by_type` view (queried with key=["form"]). | string | +| Field | Description | Format | +|-------|------------------------------------------------------------------------------------------------------------------|--------| +| form | Must be a valid form value from the forms available in the `medic-client/doc_by_type` view (queried with `key=["form"]`). | string | + #### Examples From 038ff2be8b379e2a06f824bd838689d9ce8253bc Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 12:57:47 +0545 Subject: [PATCH 07/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 66f33a1daf..6335a73f74 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1329,6 +1329,7 @@ Example response: ### PUT /api/v1/person *Added in 5.0.0* + #### Description Used to update mutable fields of a person, or delete them if they are not part of update payload. From 2c9daeb7a797c86ff178c414fe8ea753405f80ca Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 12:58:04 +0545 Subject: [PATCH 08/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 6335a73f74..f0affdf6c8 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1262,6 +1262,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/person *Added in 5.0.0* + #### Description Used to create a person. From faedfbb37a1f71965a994c28af1a523b7cf3c74a Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:00:51 +0545 Subject: [PATCH 09/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index f0affdf6c8..61fba222b5 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1869,6 +1869,8 @@ Response: ### PUT /api/v1/place +*Added in 5.0.0* + #### Description Used to update mutable fields of a place, or delete them if they are not part of update payload. From 5afbe37b29766cdcb8d6c706834f9cba37234072 Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:01:35 +0545 Subject: [PATCH 10/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 61fba222b5..534acded08 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -2414,6 +2414,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/report *Added in 5.0.0* + #### Description Used to create a report. From e6cbd84365721502a1930295b9bd87594d95aa65 Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:04:17 +0545 Subject: [PATCH 11/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 534acded08..4c47d989ee 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1811,8 +1811,7 @@ Should have `can_edit` or both `can_view_contacts` and `can_create_places`. | type | ID of the `contact_type` for the new place. Use `place` for older versions. | string | | parent | ID of the parent document. The parent’s type must match one of the allowed `parents` in the settings configuration. | UUID string | -Note: Places that are at the top of the hierarchy, should not have a `parent`. -Doing so will result in an "Unexpected parent for {placePayload} error." +*Note: Places that are at the top of the hierarchy, should not have a `parent`. Doing so will result in an "Unexpected parent for {placePayload} error."* #### Optional From 4ed2c526e668ea253b410ca89d1bb8080e52401c Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:06:17 +0545 Subject: [PATCH 12/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 4c47d989ee..85c61c43c9 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1861,7 +1861,7 @@ Response: } } }, - "reported_date": "2025-08-19T14:30:25.568Z", + "reported_date": 1756120037741, "contact_type": "clinic" } ``` From 32a9940e12a2f46fe29a206f07d8010e62e424da Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:06:27 +0545 Subject: [PATCH 13/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 85c61c43c9..efbe905f56 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -2565,7 +2565,7 @@ Response: } } }, - "reported_date": "2025-08-24T11:37:06.815Z" + "reported_date": 1755490087000 } ``` ## Users From 7507de775c0f7ff0f84a012e8a2f7e55e9aff2f9 Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:07:22 +0545 Subject: [PATCH 14/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index efbe905f56..214a2fece4 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -2476,6 +2476,8 @@ Response: ### PUT /api/v1/report +*Added in 5.0.0* + #### Description Used to update a report. From 102e8cc22a74d2c50c0af44bd826783b2af3516d Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:07:35 +0545 Subject: [PATCH 15/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 214a2fece4..88324caddc 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -2431,7 +2431,7 @@ Should have `can_view_reports` and `can_create_records`. | type | Type of the report. | string | | contact | ID of the contact document (can be either a person or a place) for the new report. | UUID string | -Note: A valid `form` value, `type` being `data_record` and having a valid `contact` is necessary for the report to appear in the webapp. +*Note: A valid `form` value, `type` being `data_record` and having a valid `contact` is necessary for the report to appear in the webapp.* #### Optional From da1180e6ed8a9633b963567b3a8e030bcf24ca3e Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:07:58 +0545 Subject: [PATCH 16/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 88324caddc..64be4cea60 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -2470,7 +2470,7 @@ Response: } } }, - "reported_date": "2025-08-24T11:37:06.815Z" + "reported_date": 1755490087000 } ``` From cc38e87cae714d3f9e7fb60f6ce2f41b16ac4efc Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:08:12 +0545 Subject: [PATCH 17/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 64be4cea60..5bf485233b 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1831,8 +1831,8 @@ Content-Type: application/json { "name": "test place", "type": "clinic", - "parent":"35a2f31e-705c-4833-b385-efd069b1ce3f", - "contact":"00058058-e637-4e65-b5db-cd4b2da4375e" + "parent": "35a2f31e-705c-4833-b385-efd069b1ce3f", + "contact": "00058058-e637-4e65-b5db-cd4b2da4375e" } ``` From ac015563f40d31c6d5707f9dfb6c9bd444a69c3a Mon Sep 17 00:00:00 2001 From: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com> Date: Wed, 27 Aug 2025 13:08:23 +0545 Subject: [PATCH 18/20] Update content/en/building/reference/api.md --- content/en/building/reference/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 5bf485233b..4624447a75 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1977,7 +1977,7 @@ Response: } } }, - "reported_date": "2025-08-19T14:48:16.436Z", + "reported_date": 1756277807624, "contact_type": "clinic" } ``` From ea56a312db3bc26bbec333f779b37dd9b030670a Mon Sep 17 00:00:00 2001 From: Apoorva Pendse Date: Wed, 5 Nov 2025 19:04:02 +0530 Subject: [PATCH 19/20] use the :uuid route param for updates Signed-off-by: Apoorva Pendse --- content/en/building/reference/api.md | 36 ++++++++++++++++++---------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 4624447a75..4cb79dc623 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1327,13 +1327,19 @@ Example response: } ``` -### PUT /api/v1/person +### PUT /api/v1/person/{{uuid}} *Added in 5.0.0* #### Description Used to update mutable fields of a person, or delete them if they are not part of update payload. +#### URL Parameters + +| Variable | Description | +| -------- | ------------------------------------------ | +| uuid | ID of the person document to be updated. | + #### Supported Properties Use JSON in the request body to specify a person’s details. @@ -1344,7 +1350,6 @@ Should have `can_edit` or both `can_view_contacts` and `can_update_people`. #### Required immutable fields | Field | Description | Format | |---------------|---------------------------------------------------------------|----------------------------------------------------------| -| _id | ID of the person document to be updated. | UUID string | | _rev | Revision ID of the person document to be updated. | string | | reported_date | Timestamp of when the record was reported or created. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | | contact_type | Required if the type of the person is `contact`. | string | @@ -1384,9 +1389,8 @@ Original Doc: Request Body: ```bash -PUT /api/v1/person +PUT /api/v1/person/4dcd842e813fd1bcabec03f98f004c96 { - "_id": "4dcd842e813fd1bcabec03f98f004c96", "_rev": "1-1492a8ddf25a350cdd35c217a561f27a", "name": "dummyuser", "type": "contact", @@ -1866,13 +1870,19 @@ Response: } ``` -### PUT /api/v1/place +### PUT /api/v1/place/{{uuid}} *Added in 5.0.0* #### Description Used to update mutable fields of a place, or delete them if they are not part of update payload. +#### URL Parameters + +| Variable | Description | +| -------- | ------------------------------------------ | +| uuid | ID of the place document to be updated. | + #### Supported Properties Use JSON in the request body to specify the details of a place. @@ -1883,7 +1893,6 @@ Should have `can_edit` or both `can_view_contacts` and `can_update_places`. #### Required immutable fields | Field | Description | Format | |---------------|--------------------------------------------------------------------------------------------------|-------------------------------------| -| _id | ID of the place document to be updated. | UUID string | | _rev | Revision ID of the place document to be updated. | string | | reported_date | Timestamp of when the record was reported or created. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | | contact_type | Required if the type of the place is `contact`. | string | @@ -1921,11 +1930,10 @@ Original place object: Request: ```bash -PUT /api/v1/place +PUT /api/v1/place/36aed043a50315f00f625af18c004bcf Content-Type: application/json { - "_id": "36aed043a50315f00f625af18c004bcf", "_rev": "1-d29dc4cf44845f0c1842bcd57390d1d3", "name": "new place", "type": "contact", @@ -2474,13 +2482,19 @@ Response: } ``` -### PUT /api/v1/report +### PUT /api/v1/report/{{uuid}} *Added in 5.0.0* #### Description Used to update a report. +#### URL Parameters + +| Variable | Description | +| -------- | ------------------------------------------ | +| uuid | ID of the report document to be updated. | + #### Supported Properties Use JSON in the request body to specify a report’s details. @@ -2494,7 +2508,6 @@ Should have `can_view_reports` and `can_update_records`. | type | Type of the report. | string | | contact | Contact document associated with the report. | Minified or hydrated contact lineage | | reported_date | Timestamp of when the record was reported or created. | `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, or unix epoch | -| _id | ID of the report document to be updated. | UUID string | | _rev | Revision ID of the report document to be updated. | string | @@ -2530,10 +2543,9 @@ Original Document: Request: ```bash -PUT /api/v1/report +PUT /api/v1/report/b8208fa332bf1f09b606e6efd8002a4a Content-type: application/json { - "_id": "b8208fa332bf1f09b606e6efd8002a4a", "_rev": "1-9ffca0e670bcc111de86f68ae8f47d3b", "form": "pregnancy_danger_sign", "type": "data_record", From b152e28928ac8de0026071fc0943f1737fa4a955 Mon Sep 17 00:00:00 2001 From: Apoorva Pendse Date: Wed, 5 Nov 2025 22:24:09 +0530 Subject: [PATCH 20/20] change release version to 5.1.0 from 5.0.0 Signed-off-by: Apoorva Pendse --- content/en/building/reference/api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/en/building/reference/api.md b/content/en/building/reference/api.md index 4cb79dc623..532d4aab1f 100644 --- a/content/en/building/reference/api.md +++ b/content/en/building/reference/api.md @@ -1261,7 +1261,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/person -*Added in 5.0.0* +*Added in 5.1.0* #### Description Used to create a person. @@ -1329,7 +1329,7 @@ Example response: ### PUT /api/v1/person/{{uuid}} -*Added in 5.0.0* +*Added in 5.1.0* #### Description Used to update mutable fields of a person, or delete them if they are not part of update payload. @@ -1796,7 +1796,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/place -*Added in 5.0.0* +*Added in 5.1.0* #### Description Used to create a place. @@ -1872,7 +1872,7 @@ Response: ### PUT /api/v1/place/{{uuid}} -*Added in 5.0.0* +*Added in 5.1.0* #### Description Used to update mutable fields of a place, or delete them if they are not part of update payload. @@ -2420,7 +2420,7 @@ Content-Type: application/json; charset=utf-8 ### POST /api/v1/report -*Added in 5.0.0* +*Added in 5.1.0* #### Description Used to create a report. @@ -2484,7 +2484,7 @@ Response: ### PUT /api/v1/report/{{uuid}} -*Added in 5.0.0* +*Added in 5.1.0* #### Description Used to update a report.