2023-07-18: Express Entry Suite Input Functionality#

Express Entry Advisory - New Suite Input Functionality#

Beginning the week of July 18th, Melissa’s Express Entry API will be updated with a feature that allows suite input to be entered directly in the ‘ExpressFreeForm’, ‘ExpressAddress’, ‘GlobalExpressFreeForm’, and ‘GlobalExpressAddress’ endpoints. This feature will make it simpler and more elegant to enter apartments and suites in the ‘free form’ or ‘address line 1’ field on your web site.

The update may require a small update to your web site’s code in order to prevent the popup from entering the apartment/suite twice in the address form on your web site.

In order to take full advantage of suite auto completion, we recommend disabling Suite Compression. By Default Express Entry has Suite Compression enabled. Details are explained in the section below, titled ‘Suite Compression Option Explained’.

Who Will Be Affected?#

Express Entry users who use the U.S. endpoints with the ‘popup’ JS code to choose suites in their web sites will be affected. Namely, if your web site was based on ‘ExpressFreeFormPopup.html’ of our sample code, you will need to make a small edit to your web site code.

Specifically, entering ‘1320 Porter Apt 72’ will return only the address with the apartment in the response, thus it will no longer be necessary to use a popup field for your customer to select their apartment number in this case.

Old Way#

../../_images/advisory-20230718-express-entry-suite-input-functionality-01.png

New Way#

../../_images/advisory-20230718-express-entry-suite-input-functionality-02.png

Example Input#

1320 Porter St Apt 72

Example REST Requests#

Global Endpoint#

expressentry.melissadata.net/WEB/GlobalExpressFreeForm?id=YOUR_ID&format=json&country=US&maxrecords=5&ff=1320+porter+st+apt+72 Old Output: XS03, No Results Found New Output (JSON): "Address": "1320 Porter St Apt 72, Dearborn, MI 48124-2833",

U.S. Endpoint#
expressentry.melissadata.net/WEB/ExpressFreeForm?id=YOUR_ID&format=json&country=US&maxrecords=5&ff=1320+porter+st+apt+72

* Old Output: ``XS03``
* New Output (JSON): ``"AddressLine1": "1320 Porter St Apt 72",``

Please see the updated sample code, ExpressEntryJavaScript.zip for the new implementation.

How Can I Test the Upcoming Update?#

To ensure your applications are not affected by the update, you are strongly encouraged to test using the temporary Testing Endpoint:

https://expressentryrc.melissadata.net

Users who use the sample code can also use this endpoint for testing purposes.

NOTE: This url should not be used for production environment. The testing endpoint will be taken down on July 31, 2022.

Suite Compression Option Explained#

&suitecompression=false#

If you are using the global endpoints for U.S. data entry, the option &suitecompression=false will now give each resulting address in the output its own suite/apartment. For example:

REST Request#
http://expressentry.melissadata.net/WEB/GlobalExpressFreeForm?id=YOUR_ID&format=json&country=US&maxrecords=10&ff=1320%20porter%20st&suitecompression=false
Response#
"Address": "1320 Porter St Apt 72, Dearborn, MI 48124-2833"
...
"Address": "1320 Porter St Apt 73, Dearborn, MI 48124-2833"
...
etc.

&suitecompression=true#

Setting &suitecompression=true will return all suites/apartments in a building in one record. For example:

REST Request#
http://expressentry.melissadata.net/WEB/GlobalExpressFreeForm?id=YOUR_ID&format=json&country=US&maxrecords=10&ff=1320%20porter%20st&suitecompression=true
Response#
"Address": "1320 Porter St, Dearborn, MI 48124-2833"
"SubBuilding": "Apt 72,Apt 73,Apt 74,Apt 75,Apt 76,Apt 77,Apt 78,Apt 79,Apt 80,Apt 81,Apt 82,Apt 83,Apt 84,Apt 85,Apt 86,Apt 87,Apt 88,Apt 89,Apt 90,Apt 91",

This option gives you the choice between expanding suites or returning them in a single field. The default is to have suitecompression set to true, where they are ‘folded’ into SubBuilding.

Thank you for your attention to this update!