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

Notes

callback_url

A URL to ping when the job has completed or failed.

string

rcfg_exclusion_ids[]

When used, the API will use a specific Exclusion Lists identified with its own ID.

array

single exclusion list: rcfg_suppression_ids[]=3

multiple exclusion lists: rcfg_exclusion _ids[]=3&rcfg_exclusion _ids[]=10

Exclusion list ID is the same ID of the listID that can be found in the URL when the list is selected in REACH.

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
        }
    }
}