This describes the resources that make up the official REST API v1. If you have any problems or requests, please contact us.
All API access is over HTTPS, and accessed from https://ezlocate.app/api. All data is sent and received as JSON.
curl -i https://ezlocate.app/apiBlank fields are included as null instead of being omitted.
All timestamps return in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZThe API uses access_token to authorize. Requests that requires authentication will return 403 Forbidden.
curl -u "username:access_token" https://ezlocate.app/apiPassing a base 64 encoded username:access_token through the request header.
curl -H "Authorization: Basic XXXXXX" https://ezlocate.app/apiMany API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:
curl -i -H "Authorization: Basic XXXXXX" https://ezlocate.app/api/orders?since=todayFor POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json:
curl -i -H "Authorization: Basic XXXXXX" -d '{"ref":"12345","address":"Somewhere in the middle, TX 1234"}' https://ezlocate.app/api/ordersWhere possible, API v1 strives to use appropriate HTTP verbs for each action.
| Verb | Description |
|---|---|
GET |
Used for retrieving resources. |
POST |
Used for creating resources. |
PATCH |
Used for updating resources with partial JSON data. For instance, an Order resource has notes attribute. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests. |
PUT |
Used for replacing resources or collections. |
DELETE |
Used for deleting resources. |
Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.
curl 'https://ezlocate.app/api/orders?page=2&per_page=100'Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.
The Link header includes pagination information:
Link: <https://ezlocate.app/orders?page=3&per_page=100>; rel="next",
<https://ezlocate.app/orders?page=50&per_page=100>; rel="last"The example includes a line break for readability.
This Link response header contains one or more Hypermedia link relations, some of which may require expansion as URI templates.
The possible rel values are:
| Name | Description |
|---|---|
next |
The link relation for the immediate next page of results. |
last |
The link relation for the last page of results. |
first |
The link relation for the first page of results. |
prev |
The link relation for the immediate previous page of results. |
For API requests using Basic Authentication, you can make up to 5000 requests per hour, per access_token.
ALL requests are authenticated.
The returned HTTP headers of any API request show your current rate limit status:
curl -i https://ezlocate.app/orders/:id
HTTP/1.2 200 OK
Date: Mon, 01 Jul 2019 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 3200
X-RateLimit-Reset: 1562003273| Header Name | Description |
|---|---|
X-RateLimit-Limit |
The maximum number of requests you're permitted to make per hour. |
X-RateLimit-Remaining |
The number of requests remaining in the current rate limit window. |
X-RateLimit-Reset |
The time at which the current rate limit window resets in UTC epoch seconds. |
If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.
new Date(1562003273 * 1000)
// => Mon Jul 01 2019 13:47:53 GMT-0400 (EDT)If you exceed the rate limit, an error response returns:
HTTP/1.2 403 Forbidden
Date: Tue, 20 Aug 2019 14:50:41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
"message": "API rate limit exceeded",
"documentation_url": "https://ezlocate.app/docs/developer#rate-limiting"
}If you exceed your rate limit using Basic Authentication, you can likely fix the issue by caching API responses and using conditional requests.
All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. We request that you use your EZ Locate username, or the name of your application, for the User-Agent header value. This allows us to contact you if there are problems.
Here's an example:
User-Agent: My-Awesome-AppcURL sends a valid User-Agent header by default. If you provide an invalid User-Agent header via cURL (or via an alternative client), you will receive a 403 Forbidden response:
HTTP/1.2 403 Forbidden
Date: Tue, 20 Aug 2019 14:50:41 GMT
Status: 403 Forbidden
{
"message": "Please make sure your request has a User-Agent header",
"documentation_url": "https://ezlocate.app/docs/developer#user-agent-required"
}The order resource.
List the available orders of the client.
GET /ordersParameters
| Name | Type | Description |
|---|---|---|
sort |
string |
What to sort results by. Can be either created, updated. Default: created |
direction |
string |
The direction of the sort. Can be either asc or desc. Default: desc |
since |
string |
Only orders updated at or after this time are returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. |
Response
HTTP/1.2 200 OK
Link: <https://ezlocate.app/api/orders?page=2>; rel="next",
<https://ezlocate.app/api/orders?page=3>; rel="last"
[
{
"id": 4120,
"ref": "863334",
"ref_2": null,
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"entities": [
{
"id": 7481,
"order_id": 4120,
"created_at": "2019-06-18T05:13:25+0800",
"addons": [
{
"id": 27569,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"service": {
"id": 1,
"name": "Verification",
"product": "Address Cleansing"
}
},
{
"id": 27570,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"service": {
"id": 2,
"name": "Geocoding",
"product": "Address Cleansing"
}
},
...
],
"properties": {
"id": 6750,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "5128 W Yesenia Harbors Locks",
"street_2": "BLDG 3339",
"city": "Louietown",
"state": "KY",
"zip": "64865",
"created_at": "2019-06-18T05:13:25+0800",
"formatted_address": "5128 W Yesenia Harbors Locks, BLDG 3339, Louietown, KY 64865",
"points": 0,
"type": "Residential"
},
"type": "address",
"attributes": []
},
{
"id": 7482,
"order_id": 4120,
"created_at": "2019-06-18T05:13:25+0800",
"addons": [
{
"id": 27578,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"service": {
"id": 18,
"name": "Multi Source Client Reviewed",
"product": "People Finding"
}
}
],
"properties": {
"id": 2494,
"portfolio_id": null,
"ref": null,
"firstname": "Astrid",
"middlename": null,
"lastname": "Heller",
"dob": "1995-06-18",
"dod": null,
"ssn": "590617387",
"created_at": "2019-06-18T05:13:25+0800",
"addresses": [
{
"id": 6750,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "5128 W Yesenia Harbors Locks",
"street_2": "BLDG 3339",
"city": "Louietown",
"state": "KY",
"zip": "64865",
"created_at": "2019-06-18T05:13:25+0800",
"formatted_address": "5128 W Yesenia Harbors Locks, BLDG 3339, Louietown, KY 64865",
"points": 0,
"type": "Residential"
}
],
"vehicles": [],
"contacts": [
{
"id": 3959,
"type": "Phone",
"value": "1-670-758-9955 x9294",
"active_at": null,
"created_at": "2019-06-18T05:13:25+0800"
}
],
"properties": [],
"active_address": {
"id": 6750,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "5128 W Yesenia Harbors Locks",
"street_2": "BLDG 3339",
"city": "Louietown",
"state": "KY",
"zip": "64865",
"created_at": "2019-06-18T05:13:25+0800",
"formatted_address": "5128 W Yesenia Harbors Locks, BLDG 3339, Louietown, KY 64865",
"points": 0,
"type": "Residential"
}
},
"type": "person",
"attributes": []
},
...
],
"completed": false,
"notes": [
{
"id": 3702,
"content": "Batch #27 created via batch locate",
"created_at": "2019-06-18T05:13:25+0800",
"user": {
"id": 356,
"username": "lodev09",
"created_at": "2018-11-14T02:18:31+0800",
"name": " ",
"avatar_url": "https://www.gravatar.com/avatar/ad71ba828efb290bd39d04989b39040d?s=48&d=identicon&r=g"
}
}
]
},
...
]Get a single order by if you secured an id.
GET /orders/:idResponse
Status: 200 OK
{
"id": 4120,
"ref": "863334",
"ref_2": null,
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"entities": [
{
"id": 7481,
"order_id": 4120,
"created_at": "2019-06-18T05:13:25+0800",
"addons": [
{
"id": 27569,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"service": {
"id": 1,
"name": "Verification",
"product": "Address Cleansing"
}
},
{
"id": 27570,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"service": {
"id": 2,
"name": "Geocoding",
"product": "Address Cleansing"
}
},
...
],
"properties": {
"id": 6750,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "5128 W Yesenia Harbors Locks",
"street_2": "BLDG 3339",
"city": "Louietown",
"state": "KY",
"zip": "64865",
"created_at": "2019-06-18T05:13:25+0800",
"formatted_address": "5128 W Yesenia Harbors Locks, BLDG 3339, Louietown, KY 64865",
"points": 0,
"type": "Residential"
},
"type": "address",
"attributes": []
},
{
"id": 7482,
"order_id": 4120,
"created_at": "2019-06-18T05:13:25+0800",
"addons": [
{
"id": 27578,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"service": {
"id": 18,
"name": "Multi Source Client Reviewed",
"product": "People Finding"
}
}
],
"properties": {
"id": 2494,
"portfolio_id": null,
"ref": null,
"firstname": "Astrid",
"middlename": null,
"lastname": "Heller",
"dob": "1995-06-18",
"dod": null,
"ssn": "590617387",
"created_at": "2019-06-18T05:13:25+0800",
"addresses": [
{
"id": 6750,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "5128 W Yesenia Harbors Locks",
"street_2": "BLDG 3339",
"city": "Louietown",
"state": "KY",
"zip": "64865",
"created_at": "2019-06-18T05:13:25+0800",
"formatted_address": "5128 W Yesenia Harbors Locks, BLDG 3339, Louietown, KY 64865",
"points": 0,
"type": "Residential"
}
],
"vehicles": [],
"contacts": [
{
"id": 3959,
"type": "Phone",
"value": "1-670-758-9955 x9294",
"active_at": null,
"created_at": "2019-06-18T05:13:25+0800"
}
],
"properties": [],
"active_address": {
"id": 6750,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "5128 W Yesenia Harbors Locks",
"street_2": "BLDG 3339",
"city": "Louietown",
"state": "KY",
"zip": "64865",
"created_at": "2019-06-18T05:13:25+0800",
"formatted_address": "5128 W Yesenia Harbors Locks, BLDG 3339, Louietown, KY 64865",
"points": 0,
"type": "Residential"
}
},
"type": "person",
"attributes": []
},
...
],
"completed": false,
"notes": [
{
"id": 3702,
"content": "Batch #27 created via batch locate",
"created_at": "2019-06-18T05:13:25+0800",
"user": {
"id": 356,
"username": "lodev09",
"created_at": "2018-11-14T02:18:31+0800",
"name": " ",
"avatar_url": "https://www.gravatar.com/avatar/ad71ba828efb290bd39d04989b39040d?s=48&d=identicon&r=g"
}
}
]
}Create a order through a POST request with the required fields.
The address parameter can either be an object or a string. For the object type, street_1, city, state and zip fields are required. You can provide the latitude and the longitude value to the address parameter if available. For string type, pass the formatted address.
POST /ordersParameters
| Name | Type | Description |
|---|---|---|
notes |
string |
Additional notes of the order. |
ref |
string |
Client custom reference number. |
address |
object |
The address associated with the order. addons property is not required. Default: [1] |
person |
object |
The person associated with the order. method property is not required. Default: 12 |
asset |
object |
The asset associated with the order. search property is required. |
The addons , method and search properties in each type of product are defined by the following.
| ID | Name | Product |
|---|---|---|
| 1 | Verification | Address Cleansing |
| 2 | Geocoding | Address Cleansing |
| 3 | Medical Facility Check | Address Cleansing |
| 4 | Urban Check | Address Cleansing |
| 5 | Military Check | Address Cleansing |
| 6 | Reservation Check | Address Cleansing |
| 7 | Correctional Check | Address Cleansing |
| 8 | Danger Check | Address Cleansing |
| 9 | Venue Check | Address Cleansing |
| 10 | Single Source Automated | People Finding |
| 11 | Multi Source Automated | People Finding |
| 12 | Multi Source Reviewed | People Finding |
| 13 | Deep Multi Source Reviewed | People Finding |
| 14 | Bank | Asset Location |
| 15 | Vehicles | Asset Location |
| 16 | Employer | Asset Location |
| 17 | Known Associates | Asset Location |
| 18 | Multi Source Client Reviewed | People Finding |
| 19 | PO Box check | Address Cleansing |
The address parameter will look something like this
{
"street_1": "1334 S Wolf Summit Road",
"street_2": "FL 168",
"city": "West Sister",
"state": "AZ",
"zip": "52437",
"type": "Business",
"addons": [1, 2, 9, 19]
}The person parameter will look something like this. Alternatively, you can pass the addons property to specify the address cleansing services to be used for new addresses found by EZ Locate. Default to 1 - Verification.
{
"firstname": "Cedrick",
"lastname": "Schoen",
"ssn": "745-57-5293",
"dob": "06/27/1996",
"phone": "(648) 582-8988",
"method": 12,
"addons": [1, 2, 9]
}Putting it all together, the entire order object will look something like this.
{
"notes": "Cumque optio aut sed itaque voluptates molestiae est in. Rerum eos error vel enim eaque est. Quo asperiores possimus dolores et culpa.",
"ref": "919013",
"address": {
"street_1": "1334 S Wolf Summit Road",
"street_2": "FL 168",
"city": "West Sister",
"state": "AZ",
"zip": "52437",
"type": "Business",
"addons": [1, 2, 9, 19]
},
"person": {
"firstname": "Cedrick",
"lastname": "Schoen",
"ssn": "745-57-5293",
"dob": "06/27/1996",
"phone": "(648) 582-8988",
"method": 12,
"addons": [1, 2]
}
}Response
Status: 201 Created
Location: https://ezlocate.app/api/orders/4329
{
"id": 4329,
"ref": "919013",
"completed_at": null,
"created_at": "2019-06-27T00:34:00+0800",
"entities": [
{
"id": 7972,
"order_id": 4329,
"created_at": "2019-06-27T00:34:00+0800",
"addons": [
{
"id": 30376,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-27T00:34:00+0800",
"service": {
"id": 1,
"name": "Verification",
"product": "Address Cleansing"
}
},
{
"id": 30377,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-27T00:34:00+0800",
"service": {
"id": 2,
"name": "Geocoding",
"product": "Address Cleansing"
}
},
{
"id": 30384,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-27T00:34:01+0800",
"service": {
"id": 9,
"name": "Venue Check",
"product": "Address Cleansing"
}
},
{
"id": 30385,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-27T00:34:01+0800",
"service": {
"id": 19,
"name": "PO Box Check",
"product": "Address Cleansing"
}
}
],
"properties": {
"id": 7130,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "1334 S Wolf Summit Road",
"street_2": "FL 168",
"city": "West Sister",
"state": "AZ",
"zip": "52437",
"pobox": null,
"created_at": "2019-06-27T00:34:00+0800",
"formatted_address": "1334 S Wolf Summit Road, FL 168, West Sister, AZ 52437",
"points": 0,
"type": "Business",
"venue": null
},
"type": "address",
"attributes": []
},
{
"id": 7973,
"order_id": 4329,
"created_at": "2019-06-27T00:34:01+0800",
"addons": [
{
"id": 30386,
"status": "pending",
"completed_at": null,
"created_at": "2019-06-27T00:34:01+0800",
"service": {
"id": 12,
"name": "Multi Source EZL Reviewed",
"product": "People Finding"
}
}
],
"properties": {
"id": 2605,
"portfolio_id": null,
"ref": null,
"firstname": "Cedrick",
"middlename": null,
"lastname": "Schoen",
"dob": "1996-06-27",
"dod": null,
"created_at": "2019-06-27T00:34:01+0800",
"ssn": "745-57-5293",
"addresses": [
{
"id": 7130,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "1334 S Wolf Summit Road",
"street_2": "FL 168",
"city": "West Sister",
"state": "AZ",
"zip": "52437",
"pobox": null,
"created_at": "2019-06-27T00:34:00+0800",
"formatted_address": "1334 S Wolf Summit Road, FL 168, West Sister, AZ 52437",
"points": 0,
"type": "Business",
"venue": null
}
],
"vehicles": [],
"contacts": [
{
"id": 4305,
"type": "Phone",
"value": "(648) 582-8988",
"active_at": null,
"created_at": "2019-06-27T00:34:01+0800"
}
],
"properties": [],
"active_address": {
"id": 7130,
"ref": null,
"updated": null,
"lat": null,
"lng": null,
"street_1": "1334 S Wolf Summit Road",
"street_2": "FL 168",
"city": "West Sister",
"state": "AZ",
"zip": "52437",
"pobox": null,
"created_at": "2019-06-27T00:34:00+0800",
"formatted_address": "1334 S Wolf Summit Road, FL 168, West Sister, AZ 52437",
"points": 0,
"type": "Business",
"venue": null
}
},
"type": "person",
"attributes": []
}
],
"completed": false,
"notes": [
{
"id": 3909,
"content": "Cumque optio aut sed itaque voluptates molestiae est in. Rerum eos error vel enim eaque est. Quo asperiores possimus dolores et culpa.",
"created_at": "2019-06-27T00:34:00+0800",
"user": {
"id": 1,
"username": "lodev09",
"created_at": "2019-06-20T00:59:44+0800",
"name": "Jovanni Lo",
"avatar_url": "https://www.gravatar.com/avatar/d41d8cd98f00b204e9800998ecf8427e?s=48&d=identicon&r=g",
"url": "https://ezlocate.app/users/system"
}
}
]
}Batch locate requires the form data content type header:
Content-Type: multipart/form-dataThe API supports comma/pipe delimited files (.csv), .xlsx or similar data files.
You can also supply the mapping parameter to map the columns. The API will try to detect the correct mappings if not supplied.
POST /orders/batchesParameters
| Name | Type | Description |
|---|---|---|
mapping |
object |
The mapping object |
file |
@file |
The uploaded file. |
Response
Status: 201 Created
Location: https://ezlocate.app/api/orders/batches/161
{
"id": 161,
"processed": 2,
"exceptions": [],
"filename": "BATCH_bg9ylFQ777GYLdnk.csv",
"mapping": "",
"completed_at": null,
"created_at": "2019-06-15T16:23:28+0800"
}You can retrieve a single batch that was previously created.
GET /orders/batches/:idResponse
Status: 200 OK
{
"id": 159,
"token": "b83d308c7b23c8b8bd407892d3d230b67cbd68ffaa9e5bccd9b0379b71728d9a",
"filename": "REQUEST_20190614_zPo3m02bFPA8ZSYw.csv",
"completed_at": "2019-06-13T16:58:04+0800",
"created_at": "2019-06-14T00:57:10+0800",
"actor_user": {
"id": 1,
"username": "lodev09",
"created_at": "2019-01-29T01:11:56+0800",
"name": "Jovanni Lo",
"avatar_url": "https://www.gravatar.com/avatar/b6b307d6680bb64cb6f1fd99a9fe43fc?s=48&d=identicon&r=g"
},
"mapping": null
}List the items that were created for a batch.
GET /orders/batches/:id/itemsResponse
Status: 200 OK
[
{
"id": 4120,
"ref": "863334",
"ref_2": null,
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"entities": [...],
"completed": false,
"notes": []
},
{
"id": 4121,
"ref": "904916",
"ref_2": null,
"completed_at": null,
"created_at": "2019-06-18T05:13:25+0800",
"entities": [...],
"completed": false,
"notes": []
}
]Webhooks allow you to subscribe to certain events on EZ Locate. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL.
When configuring a webhook, you can choose which events you would like to receive payloads for. You can even opt-in to all current and future events. Only subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server. You can change the list of subscribed events through the API or UI anytime.
Each event corresponds to a certain set of actions that can happen to your data. For example, if you subscribe to the entities event you'll receive detailed payloads every time an entity is updated, status changed, result received, etc.
The available events are:
| Name | Description |
|---|---|
orders |
Any time an order is created, deleted, completed or updated. |
item_results |
Any time an order item’s result is updated, deleted and completed. |
order_entities |
Any time an entity is added and updated. |
order_notes |
Any time a note is added to an order. |
item_review |
Any time an order item is done or ready for review |
order_person_vehicles |
Any time a vehicle of a person is added, modified |
Each event type has a specific payload format with the relevant event information.
In addition to the fields documented for each event, webhook payloads may include the user who performed the event (sender).
HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:
| Header | Description |
|---|---|
X-EZLocate-Event |
Name of the event type that triggered the delivery. |
X-EZLocate-Delivery |
A GUID to identify the delivery. |
X-EZLocate-Signature |
The HMAC hex digest of the response body. This header will be sent if the webhook is configured with a secret. The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key. |
POST /payload HTTP/1.2
X-EZLocate-Delivery: 491e4a14-869f-4d25-92b3-f1a4b500d698
X-EZLocate-Signature: sha1=522d278de0594822b0bf2a9a611c444b8d278688
X-EZLocate-Event: item_results
Content-Type: application/json
{
"action": "completed",
"result": {
"id": "1",
"data": "EZL1050",
"description": "Attributes: EZL1050 The sub premise (suite) unit number was added or changed."
},
"item": {
"id": 73,
"status": "completed",
"completed_at": "2018-12-15T04:11:22+0800",
"created_at": "2018-12-15T03:56:14+0800",
"service": {
"id": 1,
"name": "Verification",
"product": "Address Cleansing"
}
},
"entity": {
"id": 10,
"order_id": 10,
"created_at": "2018-12-15T03:56:14+0800",
"properties": {
"id": 2052,
"updated": 0,
"lat": null,
"lng": null,
"street_1": "502 Bronco Trail",
"street_2": "",
"city": "Oak Point",
"state": "TX",
"zip": "75068",
"created_at": "2018-12-15T03:56:14+0800",
"points": "2"
},
"type": "address",
"attributes": [
{
"code": "EZL1050",
"name": "Sub Premise Number Change",
"desc": "The sub premise (suite) unit number was added or changed."
}
]
},
"order": {
"id": 10,
"ref": "14",
"completed_at": null,
"created_at": "2018-12-15T03:56:14+0800",
"notes": []
}
}EZ Locate API v1 is also available in PHP. You can download it here.