Focus USA’s Demographic API is provided as a RESTful web service.
You will need to send an HTTP GET request to the API endpoint specifying your API key and pass your data in the body of the request. You will receive a JSON-formatted response.
The API Endpoint #
The Focus USA API is located at: https://api.focususaconnect.com/
- The specific endpoint for this service is – api.focususaconnect.com/v1/b2cprem
Authentication #
Authentication is handled via API key.
- Add the header x-api-key to your API calls. Contact your sales rep or info@focus-usa.com to request a key.
Rate Limiting #
By default, accounts are limited to 10 requests per second (600 requests per minute). This can be increased upon request.
Metadata #
The following fields can be passed in the body of the request. Field names ARE CASE SENSITIVE. first_name, last_name, address and zip are the minimum requirement in order to produce a match. The process will standardize and correct addresses for the highest match rate.
Request (Input)
| FIELD NAME | DESCRIPTION | EXAMPLE |
|---|---|---|
| first_name | First Name | ABC |
| last_name | Last Name | DEF |
| address | Full Address | 123 MAIN ST APT 3 |
| city | City Name | AGAWAM |
| state | State Abbreviation | MA |
| zip | Zip Code | 01001 |
| reference_id | Your ID for the request, if needed for confirmation. | ABC123 |
Response (Output)
| FIELD NAME | EXAMPLE | VALUES | DESCRIPTION |
|---|---|---|---|
| reference_id | ABC123 | char (25) | Pass your unique value used to validate your request internally, or provide to support to investigate the request in the event of an issue. |
| status | Completed – Matched | Completed – Matched Completed – No Match Failed | Status of the request |
| credits_remaining | 1287 | 0-9999999 | The number of credits remaining in the account. |
| age | 36 | 018-99 | Age of the individual |
| gender | M | M = Male F = Female U = Unknown | Gender of the individual |
| marital_status | M | M = Married S = Single U = Unknown | Marital Status of the individual. |
| homeowner | 4 | See Values  | Classification of household as an owner/renter. |
| presence_of_children | Y | Y or N | Presence of Children in the Household. |
| length_of_residence | 3 | See Values | Length lived at the current residence. |
| date_of_birth | 19880314 | YYYYMMDD | |
| income | G | See Values | Household Income Model |
| credit_score_index | 720 | 450-850 | Modeled Credit Score applied at the Neighborhood level. Values = 450-850 |
| net_worth | E | See Values | Net Worth model. Value equals household’s asset minus liabilities. |
| home_value | 435 | 9999 | Home Market Value Model. Values are in thousands. 9999 = $9,999,000 |
| education | 4 | See Values | Median school years completed by adults age 18 or older |
| household_composition | MY | See Values | Represents the makeup of the household, such as married or single, with and without children. |
| political_party | D | D = Democrat R = Republican I = Independent | Political party based upon voter registration data |
| number_of_children | 1 | 1-9 | Number of children in the household. Values = 1-9. |
| child_gender | F | M = Male F = Female B = Both U = Unknown | Gender of the child in the household |
| discretionary_spending | D | See Values | Household income after taxes, shelter, food, clothes, transportation, utilities, and healthcare. |
| pets | U | D = Dog C = Cat B = Both U = Unknown | Pet in the household. |
| personas | A7 | Proprietary clustering; 26 Main Groups and 108 Sub-Groups. | |
| channel_preference | DG | EM = Email DG = Digital DM = Direct Mail | Modeled field based on response and transaction data predicting a consumer’s preferred response channel. |
| cost_of_living | 106.83 | Index comparing the living expenses of a zipcode against the country. | |
| latitude | 40.7143 | Rooftop Latitude of the address | |
| longitude | -74.0067 | Rooftop Longitude of the address | |
| county | BERGEN | Geographic Region |
Examples #
cURL:
curl --location --request GET 'https://api.focususaconnect.com/v1/b2cprem' \
--header 'x-api-key: YOUR-API-KEY-HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"first_name": "JOE",
"last_name": “SMITH",
"address": "123 MAIN STREET",
"zip": "01001",
"reference_id": "abc123"
}Successful Response:
{
"status": "Completed - Matched",
"credits_remaining": "1287",
"reference_id": "abc123",
"input_first_name": "JOE",
"input_last_name": "SMITH",
"input_address": "123 MAIN STREET",
"input_zip": "01001",
"age": "36",
"gender": "M",
"marital_status": "M",
"homeowner": "4",
"presence_of_children": "Y",
"length_of_residence": "3",
"date_of_birth": "19880314",
"income": "G",
"credit_score_index": "720",
"net_worth": "E",
"home_value": "0435",
"education": "4",
"household_composition": "MY",
"political_party": "D",
"number_of_children": "1",
"child_gender": "F",
"discretionary_spending": "D",
"pets": "U",
"personas": "A7",
"channel_preference": "DG",
"cost_of_living": "106.83",
"latitude": "40.7143",
"longitude": "-74.0067",
"county": "BERGEN"
}Failed Response:
{
"reference_id": "abc123",
"status": "Failed",
"reason": "Out of credits"
}