C4C API

1 Releases
2 Description
3 Request method
4 Authentication
5 Use cases
- 5.1 New C4C flow (first question)
- 5.2 Continue C4C flow (next question)
- 5.3 Results from C4C
6 Payload accepted values
7 Translations
- 7.1 Available languages
8 WIP
9 Versions

Releases

Environment	Version	URL	Release date

Environment	Version	URL	Release date
Production	N/A	N/A	N/A
Development	1.0.0	http://openhim-dev.psi-mis.org:5001/c4c/api/v1/run	Nov 21, 2023

Description

C4C (Counselling for Choice) is an algorith that guides a user through a digital contraceptive counseling session so a short list of family planning methods can be recommended.

This API provides a way of navigating throuh the C4C algorithm providing user answers and obtaining the next question to be asked until the end of the algorithm, which is the methods suggestion step.

Request method

POST is the only allowed method for interacting with the API. Others will be rejected.

Authentication

The usage of this endpoints requires Basic Authentication by Username and Password.

Use cases

Since this endpoint currently does not support session storage (record answers based on a given session), all user answers must be provided for each request in order to obtain the next question or the suggested methods if applies.

New C4C flow (first question)

For starting a new flow, answers parameter should be empty, so the algorithm can respond with the first question.

Example request:

{
    "country":"{{country}}",
    "language":"{{language}}",
    "answers":[],
    "useTranslations":true
}

Each response will contain the following data:

Parameter	Description	Observation

Parameter	Description	Observation
next_question	Code of the question to be asked to the client.	When the flow ends, results will be received as its value.
next_question_text	The full thext of the question in the specified language.	useTranslations must be set to true
next_options	List of codes corresponding to each of the valid options to be presented to the user.	One of these codes will be sent as answer for obtaining the next question.
next_options_text	Full text for each valid option in the specified language, following the same order in next_options.	useTranslations must be set to true
options	Valid option codes for the corresponding question.

Example response:

{
    "next_question": "gender",
    "next_options": [
        "F",
        "N",
        "M"
    ],
    "options": {
        "F": {},
        "M": {},
        "N": {}
    },
    "next_question_text": "Te haré algunas preguntas para ayudarte mejor 😊, dime ¿cómo te identificas?",
    "next_options_text": [
        "Mujer",
        "Prefiero no decir",
        "Hombre"
    ]
}

Continue C4C flow (next question)

When user answers the first question (or next ones), a new request needs to be made adding an entrie to the answers parameter with the question code and the code that matches the user’s answer.

Example

{
    "country":"{{country}}",
    "language":"{{language}}",
    "answers":[
      {"question":"gender", "answer":"F"}
    ],
    "useTranslations":true,

    "matomoPID":"{{matomoPID}}",
    "userID":"{{userID}}",
    "sessionID":"{{sessionID}}"
}

All answers should be provided in the same order that they have been asked (obtained from the algorithm). Last user’s answer at the end of the list. In case there is a mismatch, the flow will resume on the last valid entry (correct order).

If gender, futurePregnancy, breastFeeding and age have been asked before or known from any patient record, these can be provided in the first request (in strict order) so the algorithm can start asking factor1.

Example

Results from C4C

When user reaches the end of the flow, the response from the API will follow the next format:

The main differences from the previous responses are:

next_question value is set to results to indicate the end of the flow.
options contains the suggested methods for the user. The translations can be found at options_text that matches the same order.

Payload accepted values

Parameter	Mandatory	Value Type	Description

Parameter	Mandatory	Value Type	Description
country	required	String	alpha-2 country code (2 letters). This code will determine the exceptions or special considerations to be made when suggesting methods.
language	required	String	language code . Determines the translations to be used when requested. (Default: en)
answers	required	Array	Empty for the first request or to start a new flow. Otherwise, for each of the user answers an entry should be added like:
useTranslations	optional	Boolean	Defines for each request if the text for the questions and valid options should be added in the response based on the language parameter. (Default: true)
matomoPID	optional	String	[WIP]
userID	optional	String	[WIP] For Matomo tracking
sessionID	optional	String	[WIP] For Matomo tracking

Translations

This C4C API consumes a local resource that contains translations for each of the questions and available options, as well as the name of the suggested methods. The translations have been made by some of the PSI team members in the languages listed below. [Translations Last Update: Nov 21, 2023]

Available languages

English [en]
Spanish [es]
Portuguese [pt]
French [fr]

WIP

Track user anwers based on a sessionId.
Integrate Matomo analytics event posting.

Versions

Release	Written by	Reviewed by

Release	Written by	Reviewed by
v1.0.0	Fernando Gomez

Counseling for Choice