Quickstart Guide
*** Due to unforeseen issues reported by clients who have tested the beta version of Express Entry v4, we are postponing the release of the service to the week of August 9, 2021. ***
*Express Entry Major Update:(v4 Release)
Beginning August 9, 2021, our Express Entry API will be updated from Version 3 to version 4, introducing back-end architectural improvements on the address completion engine in order to give better results. We expect all changes to the service to be backwards compatible. However, this may not be the case for some integrations, especially those using older technologies that would otherwise be incompatible with the new the new version’s header structure. This is also true for users who have stricter implementations that are not able to dynamically handle changes to the API response headers. Express Entry Version 4 also introduces several changes and improvements to how the search algorithm works, causing the data returned in the response to change. We are strongly advising all our subscribers to test the beta endpoint in order to ensure the compatibility of your integration moving forward and that all business requirements are still met.
Additional Update:
As an additional optimization to the API, Version 4 will return by default a maximum of 10 records in the response if the MaxRecords option is not specified. Users still have the ability to set MaxRecords, but only up to a maximum value of 100. By limiting the MaxRecords to 100 and setting a default of 10 records, this will prevent the API from returning an overwhelmingly large amount of records (sometimes up to 3000 records) in a single response. This has been a long standing issue that has caused the API to slow down for our users which we are now mitigating. It is strongly recommended to for clients to test the beta link to ensure that the default MaxRecords to 10 and limit of 100 MaxRecords per request does not affect their current service.
Why are we updating to Version 4?
In order to stay relevant in the Industry, Melissa continuously improves and evolves it’s APIs. As we move to the future, we are making several back-end improvement in order to accommodate the ever changing needs of our clients. This primarily includes:
For all inquiries, issues and questions please contact Melissa Tech Support.
JULY 5, 2021
We will be updating Express Entry from Version 3 to Version 4 on the week of July 5th, 2021. Please make sure to test the beta endpoint of Express Entry to ensure that your application/integration is compatible with the new version.
What will happen if I cannot connect to Express Entry v4 by the deadline?
If your integration is not backwards compatible with Express Entry v4, your application may stop working or crash.
In order to test your application for compatibility with Express Entry v4, you will need to point your application to the v4 Beta URL. Please make the following changes to the URL in the application or in your code:
Production v3:
Beta v4:
Header Changes
| Protocols Affected | Current Production (v3) | Express Entry v4 |
|---|---|---|
| All | Cache-Control: private | Cache-Control: no-cache,no-store,must-revalidate,private |
| All | Does not Exist | X-Frame-Options: deny X-XSS-Protection: 1 |
| All | Does not Exist | Pragma: no-cache |
| All | X-AspNet-Version: 4.0.30319 X-Powered-By: ASP.NET |
Does not exist |
| All | Server: Microsoft-IIS/8.5 | Server: Kestrel |
| JSONP | Content-Type: application/x-javascript | Content-Type: application/json; charset=utf-8 |
Search Algorithm Changes
With the conversion of the Express Entry code to .NET Core, the engine for auto complete searches was also re-worked in several areas. These changes ultimately provide more optimal processing time overall and reduce the number of unnecessary results when searches are too vague. What this means is that the information returned between v3 and v4 will likely be different when there are more than 10 records returned (which usually occurs with 6 keystrokes or less). This change however, is not an indication of an error as internally, the order of the records returned may be different between v3 and v4 whenever there are too many results.
Also with the re-work of the engine, the service may also return different responses when there are typographical errors in the input. Overall, v4 improves the way it is able to handle incorrectly typed/entered values. However, there will be cases where v4 is able to find results for certain searches with misspellings, while v3 does not, and vice versa.
CityAccepted and CityNotAccepted Changes
In order to standardize and normalize the output structure for Express Entry, all countries will now have the same output structure for all endpoints.
Old Behavior (Format=JSON, Version 3):
"CountryName": "Canada",
"ISO3166_2": "CA",
"ISO3166_3": "CAN",
"ISO3166_N": "124",
"SuperAdministrativeArea": "",
"AdministrativeArea": "AB",
"SubAdministrativeArea": "",
"Locality": "Calgary",
"DependentLocality": "",
"DoubleDependentLocality": "",
New Behavior (Format=JSON, Version 4):
"CountryName": "Canada",
"ISO3166_2": "CA",
"ISO3166_3": "CAN",
"ISO3166_N": "124",
"SuperAdministrativeArea": "",
"AdministrativeArea": "AB",
"SubAdministrativeArea": "",
"Locality": "Canmore",
"CityAccepted": "",
"CityNotAccepted": "",
"DependentLocality": "",
*This change applies to all Express Entry Endpoints.
Previously, Accepted and Non-Accepted city names were not outputting the correct results. The data has now been corrected to output in accordance to the USPS standards. As a background, ‘Preferred City Name’ is the USPS recommended name for an address’s city to receive mail. ‘Accepted City Names’ represent the vanity names for a city that the USPS recognizes as valid alternatives to the Preferred. And ‘Not Accepted City Names’ are ones that the USPS recommends to avoid. For example, addresses in ZIP code 90056 will now return city names as follows:
Old Behavior (Format=JSON, Version 3):
"Locality": "Los Angeles",
"CityAccepted": "Los Angeles, Los Angeles",
"CityNotAccepted": "Baldwin Hills,Windsor Hills",
New Behavior (Format=JSON, Version 4):
"Locality": "Los Angeles",
"CityAccepted": "Baldwin Hills,Windsor Hills",
"CityNotAccepted": "Crenshaw",
*This change applies to all Express Entry Endpoints
Additional Update:
Default MaxRecords to 10 and Allow up to 100 MaxRecords per Request
Having a default value of 10 for MaxRecords and limiting the maximum to 100 will improve the performance of the API greatly and minimize performance issues for Express Entry users.