.png?sv=2022-11-02&spr=https&st=2024-11-23T14%3A17%3A59Z&se=2024-11-23T14%3A27%3A59Z&sr=c&sp=r&sig=kKpbPp5fxZWK%2B0iMqmONjhSwPJz8VVujxFvb0in5U7c%3D){kind=logo}
Transactions Documentation
- Print
- DarkLight
- PDF
Transactions Documentation
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Purpose
The LightBox Transactions API provides access to historical and current transactions. LightBox updates this datasets weekly for ~2700 US counties across the nation. You will find up to 29 years of historical transactions at the property level. Both arm's length and non arm's length transactions are tracked.
Swagger: OAS 3.1 Specification
Features
- Historical transactions at the property level as of 2022, going back up to 29 years and growing every year.
- Arm's length and non arm's length transactions.
- Includes date transfer, transfer price.
- Seller name and buyer names.
- Lender name.
Related to the Assessment Record
The transaction dataset is a tabular dataset without an associated geometry. A set of transactions are related to an assessment record by the LightBox assessment ID.
Requirements
The LightBox APIs are hosted in the cloud and therefore have no platform requirements. Application requirements include:- A network connection to the LightBox API server
- Ability to parse JavaScript Object Notation (JSON) API responses
- Secure HTTPS connection
- LightBox authentication key
- LightBox authentication key
Connecting your account
When your LightBox user account is created, a unique API key is also generated. The API key should be kept secret at all times and can only be used for API requests. The key is required in all API calls.
To retrieve your unique API key:
- Log in to the LightBox Developer Portal
- Select Apps from the menu bar
- In your approved App, note your API key (under Consumer Key)
Performing API requests
All API requests must be made over secure HTTPS connections. Requests made over HTTP will fail.
The base URL of the API server that all API requests will be made to is: https://api.lightboxre.com/ followed by a version number https://api.lightboxre.com/v1
Authentication
LightBox APIs uses a token-based authentication. All requests to the LightBox APIs must be authenticated. The token to be passed via an HTTP header with key 'x-api-key' and value <Your authentication token>
Pass your unique API key in the authorization header of every LightBox API call. LightBox uses this information to authenticate your identify and determine whether you have sufficient permissions to complete the operation. curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/
API Requests
By Assessment ID
Return historical transactions by the LightBox Assessment ID. A transaction happens at the assessment level so this is the logical ID to use when accessing transactions for a property.
GET /transactions/us/assessment/{id}
Example requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/transactions/us/assessment/0306F25KSXL0JZ4RTLPP99
https://api.lightboxre.com/v1/transactions/us/assessment/0306F25KSXL0JZ4RTLPP99
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | LightBox Assessment ID | required |
Response
Media type: application/json
GET by Transaction ID
This endpoint is to return a single transaction. This ID is returned on the response object so it can be stored and used at a future date.
GET /transactions/us/{id}
Example requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/transactions/us/0806F25KSXL0JZ4RTLPP99
https://api.lightboxre.com/v1/transactions/us/0806F25KSXL0JZ4RTLPP99
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | LightBox Transaction ID | required |
Response
Media type: application/json
By County FIPS and Week
This endpoint is to be used to return new arm's length transactions for a county for the last week. It allows a data client to update data between quarterly deliveries with current owner information.
Pro Tip
This should be run on Saturday night using the week notation for the previous Sunday.
The system will query for all transactions with a week of that is >= the date entered.
The system will query for all transactions with a week of that is >= the date entered.
There is a limit to how far one can go back
This is a large dataset and has been tested to go back a month in time. If going back further than a month there can be possible timeout errors for very large counties.
Page through the results
Because there is a potential for a lot of transactions to be returned, we have implemented a paging system. See the parameters below. A max of 100 records can be returned at a time.
GET /transactions/us/{fips}/{weekOf}
Example requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/transactions/us/06059/20220725
https://api.lightboxre.com/v1/addresses/search?text=25481 Buckwood, Lake Forest, Ca
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| fips | path | The five-digit FIPS (Federal Information Processing Standards) code for the county that the property is located within (e.g., '06059'). | required |
| weekOf | path | A date string in this format yyyymmdd, 4 digit year, 2 digit month, 2 digit day, ex. 20220725. This endpoint will query records that have been added on or after this date, within the county noted by the FIPS code. Optional you can add just the word previous week which will generate the date for the Saturday of last week. | required |
| limit | query | The number of records to limit returned. | required |
| offset | query | Offset from the first record (Record 0). | required |
| filter | query | PRQL style query string to filter the results. See below | optional |
Filter
At the moment we only support filtering in a single field (transactionType_code)
Prql style filter to filter the results. Only field that we support at this time is . Primary use is to be able to pull different transactions type each week. The word filter must exist as the first word in the filter.
Supported Fields to filter on:
Prql style filter to filter the results. Only field that we support at this time is . Primary use is to be able to pull different transactions type each week. The word filter must exist as the first word in the filter.
Supported Fields to filter on:
- transactiontype_code
- landuse_normalized_code
Examples
- filter transactionType_code == 1
- filter (transactionType_code == 1 || transactionType_code == 2)
- filter (transactionType_code == 1 || transactionType_code == 2 || transactionType_code == 9)
- filter transactionType_code == '2' filter (landuse_normalized_code == 1110 || landuse_normalized_code == 1100
Response
Media type: application/json
API Response
For each endpoint other than the tile requests the response will stay consistent.
{
"$ref": "string",
"$metadata": {
"geogcs": {
"epsg": "4326"
},
"currency": {
"code": "AED"
},
"units": {
"length": "ft",
"area": "sqft"
},
"recordSet": {
"limit": 100,
"offset": 0,
"totalRecords": 99
}
},
"transactions": [
{
"$ref": "string",
"apn": "string",
"fips": "string",
"id": "string",
"assessmentId": "string",
"buyer": {
"name": "SMITH, FREDERICK; SMITH, MONICA",
"names": [
{
"firstAndMiddle": "string",
"last": "string",
"code": "string"
}
],
"mailingAddress": {
"streetAddress": "string",
"locality": "string",
"regionCode": "AL",
"unit": "string",
"unitPrefix": "string",
"postalCode": "string",
"postalCodeExt": "string",
"countryCode": "US"
},
"vesting": {
"code": "CR",
"description": "null"
}
},
"isArmsLength": true,
"isBuilderSale": true,
"isCashPurchase": true,
"isConstructionLoan": true,
"isEquityCreditLine": true,
"isForeclosureSale": true,
"isInterFamily": true,
"isQuitClaim": true,
"isMarketSale": true,
"isReoSale": "Y",
"isStandAloneRefi": true,
"transferTax": {
"city": 0,
"county": 0,
"total": 0
},
"pricePerArea": 0,
"dateFiling": "2022-12-14",
"dateNoValueTransfer": "2022-12-14",
"dateTransfer": "2022-12-14",
"document": {
"number": "string",
"type": "AA",
"typeDescription": "Assignment of Sub Agreement of Sale (Hawaii)"
},
"partialInterestTransfered": "95%",
"interestRate": {
"rate": 0,
"code": "ADJ",
"description": "Adjustable Rate"
},
"legal": {
"description": "string",
"cityTownshipMunicipality": "string",
"district": "string",
"landLot": "string",
"lotCode": "M",
"phase": "14",
"sectionTownshipRange": "SW4SW4 S26T19NR16E",
"unit": "11"
},
"lender": {
"address": {
"streetAddress": "string",
"locality": "string",
"regionCode": "string",
"unit": "string",
"unitPrefix": "string",
"postalCode": "string",
"postalCodeExt": "string",
"countryCode": "US"
},
"isCreditLine": true,
"dbaName": "FREEDOM MORTGAGE CORPORATION",
"name": "DOMESTIC BANK",
"type": {
"code": "B",
"description": "Bank"
}
},
"loan": {
"currentSale": {
"dateTransfer": "2022-12-14",
"book": "string",
"page": "string",
"documentNumber": "string"
},
"dueDate": "2022-12-14",
"term": {
"months": 120,
"years": 0
},
"type": {
"code": "string",
"description": "string"
},
"value": {
"first": 0,
"second": 0
}
},
"multipleApnFlag": {
"code": "2",
"description": "2 APN's being conveyed",
"count": "2"
},
"propertyUseCode": "SFR",
"recorder": {
"book": "string",
"page": "string",
"mapReference": "MB 739 PG 12-19"
},
"reo": {
"flag": "Y",
"inOut": "1",
"inOutDescription": "In"
},
"residentialIndicator": 0,
"salePrice": {
"code": "2",
"description": "Full amount stated on Document.",
"value": 0
},
"seller": {
"names": {
"firstAndMiddle": "string",
"last": "string",
"code": "string"
},
"code": "AB",
"description": "ALTERNATE BENEFICIARY",
"name": "string"
},
"transactionType": {
"code": "string",
"description": "string"
},
"siteAddress": {
"streetAddress": "string",
"locality": "string",
"regionCode": "AL",
"unit": "string",
"unitPrefix": "string",
"postalCode": "string",
"postalCodeExt": "string",
"countryCode": "US"
},
"trustDeedDocumentNumber": "string",
"titleCompanyName": "string",
"landUse": {
"normalized": {
"code": "string",
"description": "string",
"categoryCode": "string",
"categoryDescription": "string"
}
}
}
]
}Field Dictionary
| Field | Type | Description |
|---|---|---|
| fips | string | Federal Information Processing Code for the State, as well as the Federal Information Processing Code for the county. The first two digits are the state code and the last three digits are the county code. |
| id | string | LightBox primary ID for this transaction record. |
| assessmentId | string | LightBox ID for the related assessment record. |
| buyer.name | string | Full buyer name, including both names if two names exist. |
| buyer.names[].firstAndMiddle | string | The first name and middle name (when present) without abbreviations, or first name and middle initial (if that is how it appears on the document). |
| buyer.names[].last | string | If the last name is composed of two names, both are entered in the sequence they appear separated with a space. |
| buyer.names[].code | string | Used to identify the nature of each grantee keyed from the recorded document. |
| buyer.mailingAddress.streetAddress | string | Street address, which comprises street name, street directional prefix, street number, street suffix, unit type, and unit number (e.g., '125 Main Street S Unit 5'), of the buyer. |
| buyer.mailingAddress.locality | string | City portion of the buyer address. |
| buyer.mailingAddress.regionCode | string | State portion of the buyer address. |
| buyer.mailingAddress.unit | string | Unit number of the buyer address. |
| buyer.mailingAddress.unitPrefix | string | Unit prefix of the buyer address. |
| buyer.mailingAddress.postalCode | string | 5 digit zip code of the buyer address. |
| buyer.mailingAddress.postalCodeExt | string | 4 digit zip code extension of the buyer address. |
| buyer.mailingAddress.countryCode | string | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). |
| buyer.vesting.code | string | The vesting code, when present, indicates how the buyers took title to the subject property. |
| buyer.vesting.description | string | The vesting code description, when present, indicates how the buyers took title to the subject property. |
| isArmsLength | boolean | The sale was a residential resale, a residential new construction sale, or an insured non-residential grant deed. |
| isBuilderSale | boolean | Residential property sold by a builder. |
| isCashPurchase | boolean | Indicates the concurrent mortgage is for cash. |
| isConstructionLoan | boolean | Indicates the concurrent mortgage is a building/construction loan. |
| isEquityCreditLine | boolean | Indicates the concurrent mortgage is a home equity credit line. |
| isForeclosureSale | boolean | The property was sold in foreclosure. |
| isInterFamily | boolean | Indicates the document is an inter-family transfer. |
| isQuitclaim | boolean | Quick claim sale. |
| isMarketSale | boolean | Indicates the document is a market sale. |
| isReoSale | boolean | Y if this transaction was a Real Estate Owned (REO) sale. Real estate owned (REO) is property owned by a lender—usually a bank or government entity—after an unsuccessful sale at a foreclosure auction. |
| isStandAlongRefi | boolean | Indicates the concurrent mortgage is a stand-alone second. |
| transferTax.city | number | City transfer tax. Only applies to cities that levy a city tax on real estate transactions. |
| transferTax.county | number | County transfer tax. Generally appears in the form of a transfer tax stamp on the deed. |
| transferTax.total | number | If the region has either a city and or county transfer tax this is the sum of the two. |
| dateFiling | string | The original date of contract. |
| dateNoValueTransfer | string | ? Do we have this field |
| dateTransfer | string | The official recording date. |
| document.number | string | Sequential number assigned to documents at the time of recording. |
| document.type | string | Type of the recorded document. |
| document.typeDescription | string | Type description of the recorded document. |
| partialInterestTransfered | string | Whenever LESS than 100% ownership interest is transferred by the recorded instrument. For example, a partner sells only his 50% interest. This also applies to transfers where the grantor's entire ownership interest is LESS than 100%. For example, the grantor conveys all of his interest in the property, which is a 25% interest. When the percentage is a single digit (1-9), it is preceded by a zero: 5% = 05. When interest shown is a whole number plus a value after the decimal or fraction, it is rounded to the nearest whole number only: 75.5% = 76; 33 1/3% = 33, etc. |
| interestRate.rate | float | When available, initial rate as given on the trust deed. |
| interestRate.type | string | Interest rate code. |
| interestRate1.typeDescription | string | Interest rate description. |
| legal.description | string | Narrative description of the property as documented by the assessor. |
| legal.cityTownshipMunicipality | string | The jurisdiction in which the property is located. May be “Unincorporated,” if applicable. |
| legal.district | string | The district in which the property is located. |
| legal.landLot | string | A large portion or tract of land in which the property is located. |
| legal.lotCode | string | Identifies properties which include more than one lot or partial lots. (M='More than one lot',MP='Multiple w/a portion of one or more lots',P='Portion of a lot',B='Bank') |
| legal.phase | string | The phase of a subdivision or tract development. |
| legal.sectionTownshipRange | string | Legal section, township, and range in which the property is located. |
| legal.unit | string | The subdivision unit number. Common for condominiums, townhomes, etc. |
| lender.address.streetAddress | string | Lender street address. |
| lender.address.locality | string | Lender city. |
| lender.address.regionCode | string | State portion of the lender address. |
| lender.address.unitNumber | string | Unit number of the lender address. |
| lender.address.postalCode | string | 5 digit zip code of the lender address. |
| lender.address.postalCodeExt | string | 4 digit zip code extension of the lender address. |
| lender.address.countryCode | string | Country code of the lender address. |
| lender.isCreditLine | boolean | Indicates the mortgage is a home equity credit line. |
| lender.dbaName | string | Lender DBA Name. 'DBA' takes priority over 'C/O' if both are present. |
| lender.name | string | Concurrent lender beneficiary name. |
| lender.type.Description | string | Lender type code description. |
| loan.currentSale.dateTransfer | string | Shared Appreciation Mortgage (SAM)/Loan Current Sale - Recording Date. |
| loan.currentSale.book | string | Shared Appreciation Mortgage (SAM)/Loan Current Sale - Book Number |
| loan.currentsale.page | string | Shared Appreciation Mortgage (SAM)/Loan Current Sale - Page Number |
| loan.currentSale.documentNumber | string | Shared Appreciation Mortgage (SAM)/Loan Current Sale - Document Number. |
| loan.dueDate | string | The date the concurrent trust deed will be paid in full. |
| loan.term.months | number | Loan term in months. |
| loan.term.years | number | Loan term in years. |
| loan.type.code | string | Indicates the type of loan, if able to determine from the recorded document. |
| loan.type.description | string | Loan type code description. |
| loan.value.first | float | First loan amount. |
| loan.value.second | float | Second loan amount. |
| mulitpleApnFlag.code | string | Indicates if multiple APNs appear on the conveying instrument. |
| mulitpleApnFlag.description | string | Description of the Multiple APN Flag code. |
| mulitpleApnFlag.count | string | Indicates the number of APNs (2-9) appearing on the conveying instrument. Left blank if only one parcel. |
| propertyUseCode | string | Property use as indicated on the trust deed (mortgage) and/or attached rider. |
| recorders.book | string | Recorder's book number. Some counties only use book & page reference without the document number, others may use only the document number. |
| recorders.page | string | Recorder's page number. Some counties only use book & page reference without the document number, others may use only the document number. |
| recorders.mapReference | string | Standardized to identify each portion. Multiples indicated with the ampersand (&), and ranges separated with a hyphen (-). Depending on the length of the Map Reference, spaces may be omitted. |
| reo.flag | string | Real estate owned flag. |
| reo.inOut | string | Real estate owned (REO) is property owned by a lender, usually a bank or government entity, after an unsuccessful sale at a foreclosure auction. |
| reo.inOutDescription | string | Real estate owned (REO) inOut description. |
| residentalIndicator | string | Indicates residential use based on assessor's land use. |
| salePrice.code | string | Sale price code. |
| salePrice.description | string | Sale price code description. |
| salePrice.value | float | Sale price. |
| seller.names[].firstAndMiddle | string | First and middle name of the first seller. |
| seller.names[].last | string | Last name of the first seller. |
| seller.names[].idCode | string | Used to identify the nature of each grantor keyed from the recorded document. |
| seller.code | string | Seller code. |
| seller.description | string | Seller code description. |
| seller.name | string | Seller name, first and last. |
| transactionType.code | string | The type of sale transaction. Example: non-arm's length transfer, residential resale. Values 1-11 see description and code values under the description. |
| transactionType.description | string | The description of the sale transaction type code in transactionType.code 1 - Non-Arms length transactions WITH a valid TITLE COMPANY NAME (no accommodations) 2 - Arms-length Residential transactions (Purchase/Resales) 3 - New Construction residential transactions 4 - HELOCS - both Purchase Money and Non-Purchase Money HELOCS 5 - REFI LOANS and 2ND TRUST DEEDS (purchase and non-purchase money trust deeds). 6 - REO and TRUSTEE DEEDS 7 - RESALE PURCHASE MONEY LOANS (Subset of TRANSACTION TYPE 2) 8 - CONSTRUCTION LOANS both Purchase Money and Non-Purchase Money Loans (LOAN TYPE "B"). 9 - INSURED NON-RESIDENTIAL GRANT DEEDS 10 - NEW RESIDENTIAL PURCHASE MONEY LOANS - Subset of TRANSACTION TYPE 3 11 - NON-RESIDENTIAL Mortgages (Purchase & non-purchase) |
| siteAddress.streetAddress | string | Street address, which comprises street name, street directional prefix, street number, street suffix, unit type, and unit number (e.g., '125 Main Street S Unit 5'). |
| siteAddress.localtity | string | The city portion of the address (e.g., CHICAGO, ATLANTA, DENVER, etc.). |
| siteAddress.postalCode | string | Postal Code portion of the address (e.g 92675). |
| siteAddress.postalCodeExt | string | The four-digit code of the address. Also referred to as the 'plus 4 code' and the 'add on code.' Used by the US Postal Service to identify a geographic segment within a five-digit postal ZIP code. |
| siteAddress.regionCode | string | The two-letter state code of the address (e.g., CA, NV, WA, etc.). |
| siteAddress.countryCode | string | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). |
| trustDeedDocumentNumber | string | Trust Deed Document number assigned to the concurrent mortgage at the time of recording. |
| titleCompanyName | string | Name of title company which issues the certificate of title insurance. Taken from the deed and/or concurrent trust deed. |
| landUse.normalized.code | string | Standardized land use code. |
| landUse.normalized.description | string | Description of the standardized land use code in 'code.' |
| landUse.normalized.categoryCode | string | The standardized land use code category code. |
| landUse.normalized.categoryCodeDescription | string | The category description of the standardized land use code in 'categoryCode.' |
HTTP Error Codes
HTTP Response status codes along with a brief summary of their commonly accepted usage. These status codes are returned by LightBox APIs for each request:
| 200 | The request succeeded. |
| 201 | The object was created successfully |
| 202 | Accepted, no content |
| 204 | Successful, no content |
| 204 | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. Typically returned on a DELETE |
| 400 | One or more of the request parameters were invalid. |
| 401 | The client must authenticate itself to get the requested response. Note: This could also be due to your trial key has expired. |
| 404 | The server cannot find the requested resource. This can also mean that the endpoint is valid but the resource itself does not exist. |
| 429 | Too many requests were made in a short period of time, or you have exceeded your request-lot pool. |
| 500 | The server has encountered an error it does not know how to handle. |
| 503 | Service Unavailable. |
Was this article helpful?
.png?sv=2022-11-02&spr=https&st=2024-11-23T14%3A17%3A59Z&se=2024-11-23T14%3A32%3A59Z&sr=c&sp=r&sig=1KBuTSmwS2PYWeUQXxvdejOgXJgD4kfHqba8BTk2RXA%3D){kind=logo}