Before you can automate your data integration using the WebAdMIT API, you’ll need to think through your business process. The WebAdMIT API exposes data and document exports that are configured within WebAdMIT itself: you’ll have to build the lists, exports, PDF manager templates, and custom fields you need in WebAdMIT before you can interact with them using the API. Guidance on using these WebAdMIT features can be found in the Help Center. Be sure to always include enough information in your exports to completely identify in your local systems the person and application to which the data or documents belong.
First, you’ll need to get an API key from WebAdMIT. Log in to WebAdMIT and click the Account link in the top right-hand corner of the screen. Once there, click Edit My Account. About halfway down the next screen is a section called API Key. If you don’t already have an API key, click the Generate New Key button. If you do have a key, click Show Key. Record the alphanumeric string displayed here—you’ll need to include with every call you make to the WebAdMIT API.
The root URL for your API call depends on which environment you're trying to interact with:
|
Environment |
Root URL |
|---|---|
|
Production |
|
|
Prelaunch |
Loading data to WebAdMIT is possible using the WebAdMIT API. Custom fields created in WebAdMIT can be accessed—data added, retrieved, and/or removed. Custom questions set up in the application can’t be accessed via the API; it is possible to retrieve custom question data using the Export Manager. Interactions with custom field data via the API are at the individual application level: in other words, each custom field is updated one at a time and not in a batch. That being the case, the best approach to loading data to WebAdMIT starts with a complete data set of all applications to be updated in WebAdMIT, including the necessary information to identify the appropriate application and custom field, and the data to upload. This data set will be easiest to work with if there is one row per custom field to be updated. It is recommended to gather the necessary information from WebAdMIT—user identity, program ID, custom field ID, applicant CAS ID—before constructing the data set for the upload.
With the appropriate API key and root URL in hand, pull down all user identities accessible to the user with the “User Identity List” endpoint (GET /api/v1/user_identities https://liaison-intl.github.io/user_identity.html). Each user identity corresponds to a specific combination of cycle, association, and organization. Users frequently have more than one user identity, especially when there’s more than one CAS on campus. For example, a user will have one user identity for accessing CASPA 2023-2024 data, and a different one for accessing PTCAS 2023-2024 data. Think about which applicants you’re interested in and select the appropriate user identity—you’ll use the “id” for this user identity to load data to WebAdMIT.
Since custom fields in WebAdMIT can be defined at the program level, it’s necessary to specify the program when uploading data to an applicant’s record in WebAdMIT. Pull down a list of programs accessible to the user identity with the “Program List” endpoint (GET /api/v1/user_identities/:user_identity_id/programs https://liaison-intl.github.io/program.html). Identify the program to which you want to upload data. Use the program’s “name” and “organization_name” to identify the intended program. You’ll use the program’s “id” from the response to this call to upload data.
It’s possible to create multiple custom fields in WebAdMIT. You’ll need to identify the custom field that you want to upload data to. Pull down a list of custom fields present in the selected program with the “Custom Field List” endpoint (GET /api/v1/user_identities/:user_identity_id/programs/:program_id/custom_fields https://liaison-intl.github.io/custom_field.html). Use the “label” and “field_type” values to identify the custom field of interest. You’ll use the custom field “id” from this response when uploading data.
The user identity, program, and custom field information gathered above are necessary for each API call to load data to WebAdMIT. Two other pieces of information are also needed: the CAS ID for each applicant to be updated and the value to be loaded to the custom field. These two pieces of information will come from your local systems. It is recommended that CAS ID be included in all imports into your local systems. Without the CAS ID, it isn’t possible to upload data to custom fields in WebAdMIT.
The value to be loaded to the custom field must match the custom field’s data type. There are five possible data types for WebAdMIT custom fields:
There are many ways to gather local data for upload to WebAdMIT. You might be able to query the local system’s database directly, pulling the data into an object in your coding language of choice that can be iterated through to upload each custom field value for each applicant. You might have to set up a flat file export from your local system, then read the data from that file into an object before loading.
Combining the list of applicants to be updated that includes each applicant’s CAS ID and intended custom field value with the user identity, program, and custom field information gathered above, you’re ready to load data to WebAdMIT. For each applicant, make a call to the Custom Field Answer Store endpoint (PUT /api/v1/user_identities/:user_identity_id/programs/:program_id/applicants_by_cas_id/:applicant_cas_id/custom_field_answers/:custom_field_id https://liaison-intl.github.io/custo...ld_answer.html) including in the body of the request a JSON string matching the following format. Note that you’ll have to set the “field_type” to match the data type of the custom field you’re trying to update (see above). The “value” is the intended custom field value for the applicant.
{
"custom_field_answer": {
"field_type": "select",
"value": "Option A"
}
}
The response to the upload call will contain information confirming whether it was successful. Successful requests will return the ID, label, and data type of the custom field updated, along with the value loaded. To be extra careful, you might check the value returned in the response against the intended value you uploaded to make sure it loaded correctly.
The upload call will add a value to a custom field if none exists, and it will update the value if one already exists. There is no need to intentionally delete an existing custom field value to upload a new one. It is possible, however, to delete custom field values using the WebAdMIT API. You might want to do this if you use custom fields in WebAdMIT to manage your workflow (e.g., indicating whether financial aid information exists in your local systems for a given applicant). To delete a custom field value, make a call to the “Custom Field Answer Destroy” endpoint (DELETE /api/v1/user_identities/:user_identity_id/programs/:program_id/applicants_by_cas_id/:applicant_cas_id/custom_field_answers/:custom_field_id https://liaison-intl.github.io/custo...ld_answer.html). There is no need to include a JSON string in the body of this request.
For an exhaustive list of API endpoints available in WebAdMIT, visit our Swagger page.