MZ USSD API Usage

1 Insert data into DHIS2
2 Retrieve data inserted into DHIS2

MZ USSD data processing to DHIS2 has two endpoints:

Insert data into DHIS2
Check the result of the data processed into DHIS2

Insert data into DHIS2

To insert DHIS2 data, the following url:

Dev Environment

POST http://openhim-dev.psi-mis.org:5001/nifi.solidlines.io/surveys

Production Environment

POST http://openhim.psi-mis.org:5001/moz/ussd/nifi/surveys

This endpoint expects a request body with the surveys to be inserted in DHIS2, so the request body must be the following:

{
	"surveys": [
	{
		"orgUnit": "",
		"surveyID": "",
		"surveyDate": "",
		"answers": [{
			"type": "TEA",
			"answer": "M",
			"question": "JcGai6pHG1M"
		}, {
			"type": "DE",
			"answer": "user",
			"question": "fFjTS4qVA4h"
		}, {
			"type": "DE",
			"answer": "0010",
			"question": "C0fLABBqctc"
		}, {
			"type": "DE",
			"answer": "RCP",
			"question": "BUvnfpNC8Sg"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "EXs9avwMrC6"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "dXqvlNSA0rt"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "VC57h7Z9WEZ"
		}, {
			"type": "DE",
			"answer": 0,
			"question": "olkJStuPU6a"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "NrcQzTXHs1y"
		}, {
			"type": "DE",
			"answer": 0,
			"question": "OAeAYYna9Da"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "YjaGSF7gW69"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "goyGi80JLzn"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "s8spLqKaFdR"
		}, {
			"type": "DE",
			"answer": 1,
			"question": "zWV0tzlhwCi"
		}, {
			"question": "FLd1dXDdHhT",
			"type": "TEA",
			"answer": "f22346132907bfe36981cf5614f2c4c8ad2d237e55c8165eabd8d46304bedf1e"
		}]
    }
  ]
}

Question	Refers to	Accepted values	Accepted values meaning

Question	Refers to	Accepted values	Accepted values meaning
JcGai6pHG1M	Thank you for helping us to improve our service. What is the gender of the person served:	M F	Male Female
fFjTS4qVA4h	Who is answering the questionnaire:	user comp	User Companion
C0fLABBqctc	What is the age range of the person served:	0010 1119 2024 2535 35+	0 - 10 years 11 - 19 years 20 - 24 years 25 - 35 years +35 years
BUvnfpNC8Sg	In which sector were you served?	RCP CPN MAT CPP CCR LAB PHA SAAJ PNCT IC PSY NUT STO OPH OTH	Reception/Acceptance CPN (Prenatal consultation) Maternity CPP/CPF (Postpartum Consultation/Family Planning Consultation) CCR (Consultation for Children at Risk) Laboratory Pharmacy SAAJ PNCT (Tuberculosis) Integrated Consultations Psychosocial Support Nutrition Stomatology Ophthalmology Others
EXs9avwMrC6	The way I was treated by the health care provider:	1 0	Makes me want to go back to the Health Center (1) Doesn't feel like going back to the Health Center (0)
dXqvlNSA0rt	During the consultation the health care provider:	1 0	Asked if I had questions (1) Didn't give me room to speak (0)
VC57h7Z9WEZ	Before you finish the consultation the health care provider:	1 0	Gave me room to ask questions (1) Gave me no room to ask questions (0)
olkJStuPU6a	In talking to me the health care provider:	1 0	Explained everything in a simple way (1) Used words I didn't understand (0)
NrcQzTXHs1y	During the consultation the health care provider:	1 0	He was my friend (1) Spoke badly to me (0)
OAeAYYna9Da	During the consultation:	1 0	I understood that the treatment is good for me (1) I was unsure/fearful of the treatment (0)
YjaGSF7gW69	During the consultation the health provider talked about HIV Treatment:	1 0	Yes (If yes move on to the next question) (1) No (If no, finish) (0)
goyGi80JLzn	During the consultation the health care provider:	1 0	Explained importance of complying with HIV Treatment (1) Did not explain importance of complying with HIV Treatment (0)
s8spLqKaFdR	During the consultation the health care provider explained that:	1 0	If I take medicines correctly I will not transmit HIV to partner (1) If I don't take medication I won't be strong and healthy (0)
zWV0tzlhwCi	Viral load is:	1 0 0.000001	The amount of HIV in my body (1) The amount of defenses in my body (0) I don't know (0.000001)
FLd1dXDdHhT	Phone Number	any

The endpoint should respond any of the following cases:

{"message": "invalid request, check if the structure of your request is correct for every survey (accepted answers for questions / all parameters are included within the questions) or if the org unit is accepted"}: meaning that the structure of your request body JSON is not correct, check if all the values sent are accepted.
{"message":"success, valid request"} : meaning that the structure of your request body JSON is correct.

Retrieve data inserted into DHIS2

Everyday at 6:00 AM (GMT+2 Time zone), the server will retrieve all the processed data responses and merge it into one full response, this means that the data that the user can view before 6:00 AM (GMT+2 Time zone) will be replaced with the new one.

If no data was sent, the server will not retrieve any new data, so the response will not be replaced

The url to retrieve all the information of the data processed is the following:

Developer Environment

Production Environment

The endpoint should respond the following structure:

Parameter	Meaning

Parameter	Meaning
surveyID	ID of the survey sent by the user
dhisTeiID	ID created for the Tracked Entity Instance created
dhisEventID	ID created for the Event inserted into the Tracked Entity Instance
status	Message describing if the process was success or if there was any error during the insertion of the data.

The following is an example for a request done to the endpoint:

For the example, two surveys were processed, but this can vary as the user can send more surveys

MZ USSD API Usage

Insert data into DHIS2

Retrieve data inserted into DHIS2

Related content