This notice applies to both of the following use cases:
- Integrations using OpenApply V1 fully
- Integrations using OpenApply V3 using the
urlkey to download assets
The former example is an integration that uses V1 for the entire code path, but the latter example uses V3 integration, with just one path that actually uses V1. For developers of the first case, please review "How to Migrate" > "Integrations with V1 below." For developers of the last case, please review "How to Migrate" > "Integrations with V3 using the url key to download assets".
Problem Statement
To ensure compatibility and to take advantage of improvements, all API consumers using OpenApply's Public API Version 1 (V1) need to migrate to Version 3 (V3) by May 1st, 2025. Alternatively, the API tokens for V1 can be deleted.
Benefits of Migrating to V3
Upgrading to V3 provides several key advantages:
- Expanded Data Access: V3 includes all student custom fields in API responses, whereas V1 only includes fields present on the application form.
- Improved Performance. Clients can specify which fields to include in responses using the field mask parameter, reducing unnecessary data transfer.
- New Endpoints: V3 introduces additional endpoints for parents, events, contacts, and fees, expanding functionality.
Immediate Changes to V1
To encourage migration, we are actively winding down V1 by implementing the following restrictions:
- Lower Rate Limits: V1 requests will have stricter rate limits compared to V3.
- Daily Quotas: Limits will be imposed on the number of requests that can be made per day
- Reduced Record Returns: The number of records returned per request will be decreased.
How to Migrate
Integrations with V1
Migrating to Version 3 does not require significant refactoring of code. It necessary steps include:
- Navigate to OpenApply's API manager and create a new V3 credential. Please find steps in this article, which also demonstrates how to setup Postman.
- Use the Client ID and Client Secret to obtain a bearer token from a response to the /oauth/token endpoint.
- Change authentication used in V1 (adding API token) to use a bearer token instead. The bearer token should be placed into a request's
Authorizationheader with prefixBearer, and the token. - Change the path from
v1tov3
Example code for how to obtain a bearer token and add it to the request headers can be found in OpenApply's V3 documentation, available in the "Prerequisites" section via Settings -> Integrations -> Public API -> API Documentation
Integrations with V3 using the url key to download assets
In V3 there was a key in the students response, url, that required a V1 authentication to be successful. There is now an additional key, url_v3, that can be used to retrieve documents with V3 authentication process. Simply add the bearer token to the request, and use the path given at url_3 to download the document.
Summary
| V1 | V3 | |
|---|---|---|
| Authentication | Uses API Token, passed either as query parameter or header | Uses Oauth2 flow |
| Endpoint path | All the paths are /api/v1/{endpoint} | All the paths are /api/v3/{endpoint} |
| Student fields | Same structure, but custom fields are limited to those in the application form only | Same structure, but includes all custom fields from all forms |
| Parent fields | Not available | Available, as well as many other endpoints. |
| Additional endpoints | Not available | Includes parents, events, fees, contacts, and new endpoints will be added to V3, not V1. |
If you need more specific guidance, please consider reaching out to our Integrations Product Director Adam Morris:
: