CVA‐IM support - global-121/121-platform GitHub Wiki
121 API endpoints
Some configurations of the 121 platform can be executed through the 121 interface, for other configurations you need to use the 121 API endpoints.
The page where to find these endpoints can be accessed through:
- https://status.121.global/
- Navigate to instance you want to modify
- Click on
121-service | vx
, on the top right
How to use 121 API endpoint
- Click on the API endpoint you want to use
- Click on
Try it out
- Depending on type of endpoint, give input, eg:
- Specific field that is asked for - might be required or not
- Request body - an example is given already, which you can use to understand how the body should look like
- Click on
Execute
- Review response
- Response code
- Informational responses (100 – 199)
- Successful responses (200 – 299)
- Redirection messages (300 – 399)
- Client error responses (400 – 499)
- Server error responses (500 – 599)
- Information from first Google hit
- Response body
- Might give you the details you are looking for :)
- Response code
- Important! In order to be able to use the API endpoints, you should be logged in as an admin. You can do this by going to
POST /api/users/login
(see below) and use the credentials from Bitwarden.
Different HTTP request methods
There are different methods, the ones used by 121 API endpoints are listed here:
GET
- The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.POST
- The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.PATCH
- The PATCH method applies partial modifications to a resource.PUT
- The PUT method replaces all current representations of the target resource with the request payload.DELETE
- The DELETE method deletes the specified resource.
Information from first Google hit
Highlight of 121 API endpoints
This part will highlight some API endpoints that have been used as CVA-IM support
Tips:
- To get the id of the program, go to the program in the portal and check the url, eg:
https://portal.demo.121.global/program/[id]/payment
financial-service-providers
GET /api/financial-service-providers
- Get all Financial Service Providers
instance
POST /api/scripts/reset
- Reset instance database- Explanation of seed scripts and other inputs
notifications
GET /api/notifications/{programId}/message-templates
- Get all message templates per programPOST /api/notifications/{programId}/message-templates
- Create message templateDELETE /api/notifications/{programId}/message-templates/{type}
- Delete message template(s) by type and optionally languagePATCH /api/notifications/{programId}/message-templates/{type}/{language}
- Update message template
programs
POST /api/programs
- Create a program- Explanation of creation from Kobo
GET /api/programs/{programId}
- Get program by idDELETE /api/programs/{programId}
- Delete program and all related dataPATCH /api/programs/{programId}
- Update programGET /api/programs/{programId}/fsp-configuration
- Get all ProgramFspConfigurationEntity for a specific programPOST /api/programs/{programId}/fsp-configuration
- Create ProgramFspConfigurationEntity for a programPUT /api/programs/{programId}/fsp-configuration/{programFspConfigurationId}
- Update ProgramFsPConfigurationEntityPOST /api/programs/{programId}/program-questions
- Create program questionPATCH /api/programs/{programId}/program-questions/{programQuestionId}
- Update program questionDELETE /api/programs/{programId}/program-questions/{programQuestionId}
- Delete program question and related answers
programs/registrations
PATCH /api/programs/{programId}/registrations
- Bulk update registrations using a CSV file
roles
GET /api/roles
- Get all user rolesPOST /api/roles
- Create new user rolePUT /api/roles/{userRoleId}
- Update existing user roleDELETE /api/roles/{userRoleId}
- Delete existing user role
users
GET /api/programs/{programId}/users/search
- Search for user based on usernamePOST /api/users
- Sign up new userDELETE /api/users/{userId}
- Delete user by userIdPOST /api/users/login
- Log in existing user
Tips
- Note that for PATCH endpoint you do not need to fill all the fields in the body, you can only give the input on the things you want to change
- Some FSPs (only Excel?) can be configured per program, with the FSP configuration. For Excel, read more documentation how to use the API endpoint here: https://github.com/global-121/121-platform/wiki/Excel-payment-instructions-FSP
FAQ
Set up of program
- How do I create a new program?
- Prepare Kobo form so that it is correctly set up
- Make sure all "default" questions are in the form, either calculated based on questions or 'static' / default for all registrations, eg:
fspName
,maxPayments
andpreferredLanguage
- Add "Program configuration" questions, like the "design phase" attributes, and other meta data
- Review the following template to see which program configurations are necessary: Template XLS Form
- Template to be updated so that it's cleaner, eg. based on the standard demo program that was created
- There are fields that can contain comma separated values, namely:
fullnameNamingConvention
,language
,financialServiceProviders
- Review the following template to see which program configurations are necessary: Template XLS Form
- Add tags for questions
- that are FSP questions, so that these questions are not created again
- that the program team would like to deduplicate on
- How:
- In XLS Form: Add column
hxl
and add tags in this format:#121+dedupe
or#121+fsp
- In Kobo Builder:
- In XLS Form: Add column
- NB: One field can only contain one of the two tags. If a field is a FSP question AND it should be a field used for deduplication, this can be done currently by updating the FSP question via the API endpoints, which means it's done on an instance level.
- FSP questions should have the exact same internal name as in 121, OR the Kobo Connect headers should be changed later to the correct internal name used in 121
- Phone number should be called
phoneNumber
- Make sure all "default" questions are in the form, either calculated based on questions or 'static' / default for all registrations, eg:
- Go to "Create program" in the menu
- Set the Kobo Token and Kobo Asset ID
- Kobo Token: Go to kobo.ifrc.org/token while being logged in as a user with access to the Kobo form (assuming the Kobo form is on the IFRC server)
- Kobo Asset ID: Can be found in the URL of the Kobo form in the 'back-end' (kobo.ifrc.org/#/forms/[assetID]/summary)
- If not there already, create a Kobo user for the instance with the role to only create registrations
- Add the Kobo user to the newly created program
- Add the following headers to the REST Service that has been created with the Kobo form:
url121
,username121
,password121
and if necessaryprogramid
- Test if it works :)
- Prepare Kobo form so that it is correctly set up
- Creation of program fails, what can I check?
- No option of a dropdown question is set to NaN
- Could happen when using xlsTo121 (option None -> NaN) - Interesting to check how this works with the "Create program" functionality
- Admin role should be set up in the instance, although the admin user does not even has to have this role assigned
- No option of a dropdown question is set to NaN
- Kobo Connect does not work, what can I check?
- select_one / dropdown questions should have a default answer (once this was a problem, but it doesn't seem to be anymore?)
- phoneNumber should always be part of the payload
- Although can be empty if allowEmptyPhoneNumber is set to true in the program set up
- Explanation of difference between FSP and program questions (and custom attributes? But will be removed?)
- How do I add a field after set up of the program?
- Use
POST /api/programs/{programId}/program-questions
- Use
- How do I edit a field after set up of the program?
- Use
PATCH /api/programs/{programId}/program-questions/{programQuestionId}
- Use
- How do I delete a field after set up of the program?
- Use
DELETE /api/programs/{programId}/program-questions/{programQuestionId}
- Use
- How do I set up deduplication?
- In the JSON object of the questions of the program, there is a key called
duplicateCheck
, which has a value of eithertrue
orfalse
- If the
duplicateCheck
of a question is set totrue
, this field will be taken into account when exporting the "duplicate report"
- In the JSON object of the questions of the program, there is a key called
- Can I do deduplication on first and last name?
- At the moment you can choose the fields which should be taken into account for the duplicate report, where it will only deduplicate against that field itself
- It is possible to include both first and last name in the duplicate report, but it will be treated as two separate fields
- It is possible to, when importing the registrations (either via Kobo or manual) to concatenate the first and last name into one name field and use this field in the deduplication report, BUT unfortunately, when the first or last name gets updated in the 121 platform, the one field name will not be automatically updated and thus should also be manually updated to not show up in the deduplication report anymore - thus this option is not optimal
- In short, there is no easy way yet to deduplicate on both first and last name if those are separate questions in the program set up
User management
- How do I add a new user?
- Use
POST /api/users
, with the email as username and generate a strong password - The user is created and can now be found in the portal under "Users" in the main menu
- The user then needs to be added to the correct program
- This can also be done by the program team itself (although the first user with these "user management" rights need to be added by admin)
- Go to the program
- Go to "Team" in the top left corner
- Click on "Add team member"
- Search for the team member and give the user the correct role and if necessary scope
- Use
- How do I change the role of a user?
- The role of a user is set in the portal per program (not on instance level)
- You go to the program and click on "Team" in the top left
- You search for the user you want to update and click on the three dots on the right, then "Edit"
- The role can be changed, then click on "Save"
- Also see documentation on Roles and Permissions
- The role of a user is set in the portal per program (not on instance level)
- How do I remove a user?
- A user can be removed from a program (by the program team) by going to Team, three dots and click "Remove from Team"
- If a user is not assigned to any program, the user can log in but not see any data
- A user can also be completely deleted, by using
DELETE /api/users/{userId}
- Get the id of the user to remove by using
GET /api/users
- Get the id of the user to remove by using
- At the moment it is not possible to set a user to "inactive"
Other
- How can I inspect the form definition of my Kobo form?
- Go to: kobo.ifrc.org/api/v2/assets/[assetID]