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:

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
  • 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 program
  • POST /api/notifications/{programId}/message-templates - Create message template
  • DELETE /api/notifications/{programId}/message-templates/{type} - Delete message template(s) by type and optionally language
  • PATCH /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 id
  • DELETE /api/programs/{programId} - Delete program and all related data
  • PATCH /api/programs/{programId} - Update program
  • GET /api/programs/{programId}/fsp-configuration - Get all ProgramFspConfigurationEntity for a specific program
  • POST /api/programs/{programId}/fsp-configuration - Create ProgramFspConfigurationEntity for a program
  • PUT /api/programs/{programId}/fsp-configuration/{programFspConfigurationId} - Update ProgramFsPConfigurationEntity
  • POST /api/programs/{programId}/program-questions - Create program question
  • PATCH /api/programs/{programId}/program-questions/{programQuestionId} - Update program question
  • DELETE /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 roles
  • POST /api/roles - Create new user role
  • PUT /api/roles/{userRoleId} - Update existing user role
  • DELETE /api/roles/{userRoleId} - Delete existing user role

users

  • GET /api/programs/{programId}/users/search - Search for user based on username
  • POST /api/users - Sign up new user
  • DELETE /api/users/{userId} - Delete user by userId
  • POST /api/users/login - Log in existing user

Tips

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 and preferredLanguage
      • 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
      • Add tags for questions
        1. that are FSP questions, so that these questions are not created again
        2. 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: image
        • 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
    • 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 necessary programid
    • Test if it works :)
  • 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
  • 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
  • How do I edit a field after set up of the program?
    • Use PATCH /api/programs/{programId}/program-questions/{programQuestionId}
  • How do I delete a field after set up of the program?
    • Use DELETE /api/programs/{programId}/program-questions/{programQuestionId}
  • 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 either true or false
    • If the duplicateCheck of a question is set to true, this field will be taken into account when exporting the "duplicate report"
  • 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
  • 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
  • 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
    • 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]