ARELLO API via SourceRE

Last Revision: 10/26/2025

Table of Contents

• Introduction
• Quick Start Instructions
• Search API Details
• Interface
• Formatting the Request
• How Searches Are Performed
• Search Signals
• Search Parameters
• Reading the Response
• Warnings and Errors
• Rate Limits
• Testing Environment
• Jurisdiction Participation and License Format Information
• Contact Us

Introduction

The ARELLO API (formerly known as the Licensee Verification Web Service) allows clients to obtain real estate licensee information in an automated fashion via a single HTTP request. When supplied with a practitioner's jurisdiction, license number, last name and first name in an HTTP POST request, the service returns matching records with a score indicating the degree to which each result matched the parameters.

As of October 27, 2025, this service is provided via SourceRE, and is available upon purchasing any ARELLO API data Feed within the SourceRE Data Marketplace. Users of the previous version of the service, provided by ARELLO, will need to update their implementation to use the new service.

SourceRE offers two different Plans for ARELLO data Feeds:

• Search - This Plan provides access to the standard "Search" API, which functions virtually identically to the previous service, with the exception of the endpoint URL and the authentication method. Whereas the previous service required a username and password, the new service requires a JWT bearer token. More information about the authentication method and Search functionality is provided below.
• Enhanced (Coming Soon) - This plan allows for RESTful access to License, Jurisdiction, and Disciplinary Action data, via the SourceRE RESO Web API. Purchasers of this Plan have full access to the Search API as well. Full information about the Enhanced Plan will be provided upon release.

Both of these Plans are priced on a per-jurisdication model, meaning that the cost of the Feed is based on the number of jurisdictions you wish to access data for. You may add/remove jurisdictions to your Feed at any time. At least one jurisdiction is required for an Active Feed.

Quick Start Instructions for the Search API

• Step 1: Read and become familiar with this documentation.
• Step 2: Purchase an ARELLO data Feed within the SourceRE Data Marketplace.
• Step 3: Connect to the testing API, and use it to develop your application and ensure it's functioning as intended.
• Step 4: Once you've developed and tested your application and you're ready to go live, update your implementation to use the live API, and you're off!

Note: The RESO Web API, which is available for purchasers of the "Enhanced" Plan, does NOT have a testing environment.

Search API Details

Interface

The ARELLO Search API expects an HTTP POST request with URL-encoded form parameters. The service returns results in JSON format. TLS encryption is required.

The web service endpoint URL is: https://api.sourceredb.com/Search. The same URL is used for live and testing environments; use the "searchMode" parameter to switch.

Formatting the Request

The web service expects to receive an HTTP POST request with URL-encoded form parameters. This is a standard POST request just like you'd make through a web browser. This type of request is supported by HTTP libraries in all major programming languages.

The JWT Bearer Token for your ARELLO data Feed must be included in the Authorization header. This token may be copied from your Feed card within the Data Marketplace. The token replaces the username and password which were used in the previous version of the service and are no longer required.

Example request:

The following parameters are accepted in the request body as URL-encoded form fields:

* one of licenseNumber OR lastName is required

How Searches Are Performed

In order to get the best and most reliable results from the Licensee Verification Web Service, it is important to understand how the web service searches the database. Understanding the search routine will help you to know what data to provide, what is most important and what is least important in getting meaningful results.

Search Signals

In order to provide the best matches possible, we calculate and compare a variety of search signals in addition to searching for exact matches. This means that an exact match to licensee data is not required to get meaningful results.

• License number numeric reduction – we maintain license number formatting information for all participating jurisdictions, and we use that information to calculate a numeric reduction of the license number for comparison. For example, some jurisdictions use character prefixes (REB. 12345) and some use leading zeroes (0012345). The numeric reduction of both examples is 12345. When you search and provide a license number parameter, the value you provide is numerically reduced and compared to this signal.
• Soundex pattern matching – names are often misspelled, or spelling is inferred from phonetics. Soundex is a method of encoding the phonetic form of a name for comparison. For example, while McAlister and McCallister are spelled differently, their Soundex encoding is identical.
• Alternate names – often, people choose to be called by less formal versions of their first name, but on official records the more formal version is used. We maintain a database of alternate names which are used in the search. For example, if you search for Bill Jones, we also search for alternate first names like Will and William.

Search Parameters

Searches can only be performed on data that you provide. If you omit any of the search parameters, the likelihood of erroneous results increases. It is to your advantage to provide all the search parameters. For each parameter you provide, one of the signals must match in order for a result to be returned.

• For License Number, there must be an exact match or numeric reduction match
• For Last Name, there must be an exact match or Soundex match
• For First Name, there must be an exact match, alternate name match, or Soundex match

If you provide multiple parameters, all parameters must return a match for a result to be included. Think "AND" logic as opposed to "OR."

After the search results are selected from the database, they are assigned a score based on the quality of the match. The maximum possible score is 100, if all 3 search parameters return an exact match. White space is ignored for exact matches ("Aaron" is an exact match of "Aaron ").

Note that it is to your advantage to provide all the search parameters when searching. If a parameter is not included in the request, the score for the parameter is automatically 0. For example, if you don't include a first name, the maximum possible score you can get is 80 (License Number exact + Last Name exact).

Reading the Response

The response from the web service is a JSON structure with 4 top-level keys:

• "request" (struct) - The request information that produced the response.
• "results" (array of struct) - The results of the search.
• "warnings" (array of string) - Any warnings that may have occurred.
• "errors" (array of struct) - Any errors that may have occurred.

The response is formatted as follows:

In the payload of the response, "results" is an array of structs with the following keys:

Warnings and Errors

The web service may produce warnings and errors if it encounters a problem with a request.

In cases where the issue is minor, the web service may be able to recover and still produce a usable result. These are called "warnings." A warning indicates that something went wrong while processing the request, but the service was able to correct the problem and still produce results. Examples of events that produce warnings include:

• Failure to provide optional parameters (the warning indicates the default value used).
• Providing a minScore or maxResults value that is out of range.

In the case of warnings, the service simply corrects the erroneous value to an acceptable value, and continues to perform the search. Searches that produce warnings will still return results, and therefore they are logged to the database, just like a normal search.

The "warnings" key in the response is an array of strings. Each string is a human-readable warning message.

In other cases, the service may be unable to process a request and produce usable results. These are called errors. An error indicates that the service could not continue executing. Examples of events that produce errors include:

• Failing to provide required search parameters, like "jurisdiction" and "lastName"
• Providing an incorrect jurisdiction abbreviation
• Searching within a jurisdiction that does not participate in the program
• Searching in "live" mode when your account is only enabled for "test" mode
• Performing too many requests in a short amount of time (see "Rate Limits" for more information)
• Searching using a disabled or expired account.

The "errors" key in the response is an array of structs:

Multiple warnings may be present in the response. No more than one "Fatal" error will exist.

Testing Environment

When developing your application to interface with the Search API, we provide a testing API with some known records to search for.

The testing database is comprised of a random 1% of the records from the live database. There are also several records of bogus data that can be used for assuring that the web service returns expected results.

Users can enter any of the above as is and get a score of 100. One can also obtain different confidences by using specifically formatted requests.

• Searching for license number "12345" in AL gives one result with a score of 30 (license number numeric reduction).
• Searching for license number "000012345" and last name "doe" in AL gives a score of 80 (exact license number and last name).
• Searching for first name = "bill" and last name = "jones" in AK gives one result with a score of 55 (exact last name and alternate first name).
• Searching for first name = "marie" and last name = "richardson" in AK gives one result with a score of 50 (exact last name and Soundex first name).

Rate Limits & Tokens

Unless otherwise noted, the following rate limits apply per Feed:

• No concurrent requests
• Max 3 requests per second
• Max 5,000 requests per hour

Violations result in HTTP 429 responses.

The Rate Limits do not apply to the JWT Bearer Token, but to your Feed. Every time you press "Copy Bearer Token" on the Feed within the Data Marketplace, a new token is generated. This does not invalidate previous tokens. Every token is valid for 1 year.

Jurisdiction Participation and License Format Information

ARELLO is constantly working with its jurisdictions to get the latest information as frequently as possible, but unfortunately, there still is not 100% participation. Some jurisdictions are unable to participate for legal reasons, and some are simply not ARELLO members.

Additionally, jurisdictions which do participate have varying license number formats, and it can be difficult to get an exact match without knowing something about the format before conducting a search. To help you perform better searches, ARELLO provides information about jurisdiction participation, update frequency and license number format in several formats which you can access and use in your client application.

Endpoints and available formats:

• JSON: https://www.arello.com/api/participants.cfm?format=json
• XML: https://www.arello.com/api/participants.cfm?format=xml
• CSV: https://www.arello.com/api/participants.cfm?format=csv

These resources include the following information for each jurisdiction:

Contact Us

For any questions or assistance, please contact us at: support@sourceredb.com.