--- title: B2C Demographic API description: 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… url: "https://www.focus-usa.com/docs/b2c-api/" updated: "2024-08-16" category: Focus USA API Integrations --- # B2C Demographic API 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/](https://api.focususaconnect.com/) - The specific endpoint for this service is – [**api.focususaconnect.com/v1/b2cprem**](http://api.focususaconnect.com/v1/b2cprem) #### Authentication **Authentication is handled via API key.** - Add the header x-api-key to your API calls. [**Contact**](https://www.focus-usa.com/contact-focus-usa/) your sales rep or [**info@focus-usa.com**](mailto: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 requiremen**t 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 | [**S**](https://www.focus-usa.com/wp-content/uploads/2024/04/B2C_API_Data_Dictionary.pdf)[**ee Values**](https://www.focus-usa.com/wp-content/uploads/2024/05/FOCUS-USA-B2C-API-DATA-DICTIONARY.pdf) ![Adobe PDF](https://www.focus-usa.com/wp-content/uploads/2024/03/pdf-icon-16.png) | Classification of household as an owner/renter. | | presence_of_children | Y | Y or N | Presence of Children in the Household. | | length_of_residence | 3 | [**S**](https://www.focus-usa.com/wp-content/uploads/2024/04/B2C_API_Data_Dictionary.pdf)[**ee Values**](https://www.focus-usa.com/wp-content/uploads/2024/05/FOCUS-USA-B2C-API-DATA-DICTIONARY.pdf) ![Adobe PDF](https://www.focus-usa.com/wp-content/uploads/2024/03/pdf-icon-16.png) | Length lived at the current residence. | | date_of_birth | 19880314 | | YYYYMMDD | | income | G | [**S**](https://www.focus-usa.com/wp-content/uploads/2024/04/B2C_API_Data_Dictionary.pdf)[**ee Values**](https://www.focus-usa.com/wp-content/uploads/2024/05/FOCUS-USA-B2C-API-DATA-DICTIONARY.pdf) ![Adobe PDF](https://www.focus-usa.com/wp-content/uploads/2024/03/pdf-icon-16.png) | Household Income Model | | credit_score_index | 720 | 450-850 | Modeled Credit Score applied at the Neighborhood level. Values = 450-850 | | net_worth | E | [**S**](https://www.focus-usa.com/wp-content/uploads/2024/04/B2C_API_Data_Dictionary.pdf)[**ee Values**](https://www.focus-usa.com/wp-content/uploads/2024/05/FOCUS-USA-B2C-API-DATA-DICTIONARY.pdf) ![Adobe PDF](https://www.focus-usa.com/wp-content/uploads/2024/03/pdf-icon-16.png) | 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 | [**S**](https://www.focus-usa.com/wp-content/uploads/2024/04/B2C_API_Data_Dictionary.pdf)[**ee Values**](https://www.focus-usa.com/wp-content/uploads/2024/05/FOCUS-USA-B2C-API-DATA-DICTIONARY.pdf) ![Adobe PDF](https://www.focus-usa.com/wp-content/uploads/2024/03/pdf-icon-16.png) | Median school years completed by adults age 18 or older | | household_composition | MY | [**S**](https://www.focus-usa.com/wp-content/uploads/2024/04/B2C_API_Data_Dictionary.pdf)[**ee Values**](https://www.focus-usa.com/wp-content/uploads/2024/05/FOCUS-USA-B2C-API-DATA-DICTIONARY.pdf) ![Adobe PDF](https://www.focus-usa.com/wp-content/uploads/2024/03/pdf-icon-16.png) | 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 | [**S**](https://www.focus-usa.com/wp-content/uploads/2024/04/B2C_API_Data_Dictionary.pdf)[**ee Values**](https://www.focus-usa.com/wp-content/uploads/2024/05/FOCUS-USA-B2C-API-DATA-DICTIONARY.pdf) ![Adobe PDF](https://www.focus-usa.com/wp-content/uploads/2024/03/pdf-icon-16.png) | 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" } ```