This API utilizes the REACH Job processing queue to generate a B2C Listgen csv file, which can be downloaded after creation.
By submitting the API request, you agree to be charged based on the results from the generated list.
Format
API End point: https://api.versium.com/v2/jobs?operation=b2cPeopleListGen
Http method: POST
This API uses the Configuration Parameters and Demographic Filter Parameters
Required Configuration Parameters
| Name | Description | Value Type | Notes |
|---|---|---|---|
| name | What to name the list | string | |
| project_name | The name of the project to store the list in. If a project with this name doesn’t exist, a new one will be created. | string | Required if project_id is not provided |
| project_id | The id of an existing project to store the list in. | integer | Required if project_name is not provided |
| callback_url | A URL to ping when the job has completed or failed. | string |
For additional required and optional configuration parameters, see the Configuration Parameters page.
For the list of demographic filters, see the Demographic Filter Parameters page.
Optional Configuration Parameters
| Name | Description | Value Type |
|---|---|---|
| callback_url | A URL to ping when the job has completed or failed. | string |
Example:
Generate a list with the following configuration and filters:
- name: 98052_98033
- in project name: 1116
- with attributes Fist name, last name, postal address and email
- in the geographical area of zip codes 98052 and 98033.
https://api.versium.com/v2/jobs?operation=b2cPeopleListGen&name=98052_98033&project_name=1116&required_fields[]=address&required_fields[]=email&d_zip[]=98052&d_zip[]=98033
The JSON response will contain meta information and the state_url that can be used to obtain the job status. Once completed the JSON response will include the URL to send subsequent API requests to.
Dispatched response
{
"versium": {
"version": "2.0",
"query_id": "9dc4828868e938d263a77fd1a7a63623",
"query_time": 0.18544507026672363,
"results": {
"id": 674929,
"guid": "9c448796-9dae-4b68-976f-e29375f2af46",
"state": "dispatched",
"operation": "b2cPeopleListGen",
"created_at": "2023-12-13T14:51:18.000000Z",
"finished_at": null,
"output_list": {
"id": 529079,
"download_url": null,
"num_matches": 0,
"num_records": 0,
"project_id": 80370,
"insights": null
},
"state_url": "https://api.versium.com/v2/jobs/674929",
"callback_url": null,
"suppression_input_list_ids": null
}
}
}
Processing response:
{
"versium": {
"version": "2.0",
"query_id": "3570e37172475acffd82f1f2fd6a144a",
"query_time": 0.06275701522827148,
"results": {
"id": 674966,
"guid": "f8bab7cf-f98b-4c9a-9de6-5d1c117498b1",
"state": "processing",
"operation": "b2cPeopleListGen",
"created_at": "2023-12-13T14:55:43.000000Z",
"finished_at": null,
"output_list": {
"id": 529115,
"download_url": null,
"num_matches": 0,
"num_records": 0,
"project_id": 80370,
"insights": null
},
"state_url": "https://api.versium.com/v2/jobs/674966",
"callback_url": null,
"suppression_input_list_ids": null
}
}
}
Completed job:
Once the job is completed, the response will contain the "state":"Done" string. The response will also contain the following:
- download URL - the url that can be used to download the generated list in CSV format.
- number of matches in the list
- number of records in the list
- insights - a set of data containing the insights of the generated list
{
"versium": {
"version": "2.0",
"query_id": "0a1a1c6a52ac83e5918f9852ed4fe111",
"query_time": 0.06901788711547852,
"results": {
"id": 674966,
"guid": "f8bab7cf-f98b-4c9a-9de6-5d1c117498b1",
"state": "done",
"operation": "b2cPeopleListGen",
"created_at": "2023-12-13T14:55:43.000000Z",
"finished_at": "2023-12-13 14:56:09",
"output_list": {
"id": 529115,
"download_url": "https://api.versium.com/v2/lists/529115/download",
"num_matches": 26070,
"num_records": 13035,
"project_id": 80370,
"insights": {
"Age": {
"data": [
[
"18-24",
0.3
],
[
"25-34",
6
],
[
"35-44",
14.8
],
[
"45-54",
22.7
],
[
"55-64",
22.9
],
[
"65-74",
18.7
],
[
"75 +",
14.6
]
],
"fillRate": 95.62749309604172,
"highestValue": [
"55-64",
22.9
]
},
"Gender": {
"data": [
[
"M",
49.2
],
[
"F",
50.8
]
],
"fillRate": 91.0095121202823,
"highestValue": [
"F",
50.8
]
},
"Income": {
"data": [
[
"< 50,000",
11.2
],
[
"50,000-149,000",
41.8
],
[
"150,000-249,000",
30.2
],
[
"250,000 +",
16.8
]
],
"fillRate": 97.8521018717398,
"highestValue": [
"50,000-149,000",
41.8
]
},
"AgeGender": {
"data": [
{
"F": 0,
"M": 0,
"AgeRange": "18-24"
},
{
"F": 6.1,
"M": 5,
"AgeRange": "25-34"
},
{
"F": 16.2,
"M": 13,
"AgeRange": "35-44"
},
{
"F": 21.2,
"M": 22,
"AgeRange": "45-54"
},
{
"F": 22.2,
"M": 24,
"AgeRange": "55-64"
},
{
"F": 20.2,
"M": 19,
"AgeRange": "65-74"
},
{
"F": 14.1,
"M": 17,
"AgeRange": "75 +"
}
],
"fillRate": 87.91040196379257,
"highestValue": [
"",
0
]
},
"Education": {
"data": [
[
"Completed High School",
25.4
],
[
"Tech/Vocational Training",
0.5
],
[
"Completed College",
60.2
],
[
"Completed Grad School",
13.9
]
],
"fillRate": 64.85118134397054,
"highestValue": [
"Completed College",
60.2
]
},
"Ethnicity": {
"data": [
[
"White, Caucasian, European",
76
],
[
"Asian",
14.6
],
[
"Hispanic",
5.1
],
[
"Middle Eastern",
2.5
],
[
"Black, African American",
1.2
],
[
"Polynesian",
0.5
],
[
"Native American",
0.1
]
],
"fillRate": 88.61613992022093,
"highestValue": [
"White, Caucasian, European",
76
]
},
"B2CLocation": {
"data": [
[
"WA",
100
]
],
"fillRate": 99.9923289352562,
"highestValue": [
"WA",
100
]
},
"Generations": {
"data": [
[
"iGen",
0.3
],
[
"Millenial",
18.5
],
[
"Gen X",
34
],
[
"Baby Boomer",
36.7
],
[
"Silent",
10.3
],
[
"Greatest",
0.2
]
],
"fillRate": 95.62749309604172,
"highestValue": [
"Baby Boomer",
36.7
]
},
"NumChildren": {
"data": [
[
0,
60.5
],
[
"1-2",
36.2
],
[
"3-4",
3.3
],
[
"5 +",
0
]
],
"fillRate": 99.9923289352562,
"highestValue": [
0,
60.5
]
},
"MaritalStatus": {
"data": [
[
"M",
47.1
],
[
"S",
52.9
]
],
"fillRate": 94.97545259281988,
"highestValue": [
"S",
52.9
]
}
}
},
"state_url": "https://api.versium.com/v2/jobs/674966",
"callback_url": null,
"suppression_input_list_ids": null
}
}
}