Output Sample

The B2B2C Crosswalk Append API returns application/json. Response headers include x-versium-query-id (the query id, useful when contacting support) and x-credits-remaining.

field	description
`version`	API version.
`match_counts`	Billable match count per output for this request, including `crosswalk`. Outputs that were requested but did not match are reported as `0`.
`num_matches`	Sum of all values in `match_counts`.
`num_results`	Number of result records: `0` or `1`.
`query_id`	Unique id for the request.
`query_time`	Seconds spent processing the request.
`input_query`	The recognized inputs echoed back.
`results`	Array containing at most one composite record.
`errors`	Array of error strings. Present only when errors occurred.

Result record fields

Empty fields and empty collections are omitted from the record entirely, so a field's absence means no data was found for it.

field	output	type	notes
`EmailAddrJSONB2B`	business_email	array of objects	Each item has `EmailAddr`.
`PhoneJSONB2C`	consumer_mobile	array of objects	Each item has `Phone`, `LineType`, and where available `Carrier`, `CarrierParent`, `CustomerType`, `PaymentType`. Up to `cfg_max_phones_b2c` items.
`EmailAddrJSONB2C`	consumer_email	array of objects	Each item has `EmailAddr`. Up to `cfg_max_emails_b2c` items.
`AddressB2C`, `CityB2C`, `StateB2C`, `ZipB2C`, `CountryB2C`	consumer_address	string	Flat scalar fields for the residential address.

Collections are always JSON arrays, never JSON-encoded strings.

Output based on a match

{
    "versium": {
        "version": "2.0",
        "match_counts": {
            "business_email": 1,
            "consumer_mobile": 1,
            "consumer_email": 1,
            "consumer_address": 1,
            "crosswalk": 1
        },
        "num_matches": 5,
        "num_results": 1,
        "query_id": "3f8a1c9e2b7d4a6f8e1c0b5d7a9f2e4c",
        "query_time": 1.284,
        "input_query": {
            "first": "Jane",
            "last": "Doe",
            "city": "Lincoln",
            "state": "NE"
        },
        "results": [
            {
                "EmailAddrJSONB2B": [
                    { "EmailAddr": "[email protected]" }
                ],
                "PhoneJSONB2C": [
                    {
                        "Phone": "5551234567",
                        "LineType": "Mobile",
                        "Carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS - NE",
                        "CarrierParent": "Verizon"
                    }
                ],
                "EmailAddrJSONB2C": [
                    { "EmailAddr": "[email protected]" }
                ],
                "AddressB2C": "123 MAIN ST",
                "CityB2C": "LINCOLN",
                "StateB2C": "NE",
                "ZipB2C": "68507",
                "CountryB2C": "US"
            }
        ]
    }
}

Output based on no match

A request that runs successfully but finds nothing is a zero-result response, not an error. It returns 200, and every requested output is reported as 0.

{
    "versium": {
        "version": "2.0",
        "match_counts": {
            "business_email": 0,
            "consumer_mobile": 0,
            "crosswalk": 0
        },
        "num_matches": 0,
        "num_results": 0,
        "query_id": "0f0e0d0c0b0a09080706050403020100",
        "query_time": 0.742,
        "input_query": {
            "first": "Jane",
            "last": "Doe",
            "city": "Lincoln",
            "state": "NE"
        },
        "results": []
    }
}

Billing

You are charged per match, not per request. A request that returns no results costs nothing.

match_counts key	Credits	Charged
`business_email`	2	Once per matched record.
`consumer_mobile`	1	Once per matched record, regardless of how many numbers are returned.
`consumer_email`	1	Per email address returned. Two consumer emails cost two credits.
`consumer_address`	1	Once per matched record.
`crosswalk`	1	Once per record that returns any consumer contact point (mobile, email, or address). Not charged when only `business_email` is requested or when no consumer data is found.

Error responses

When an error occurs, the response object contains an errors property, an array of strings.

{
    "versium": {
        "version": "2.0",
        "match_counts": {},
        "num_matches": 0,
        "num_results": 0,
        "query_id": "48f9238aba984c4597df74f405c97527",
        "query_time": 0.031,
        "results": [],
        "errors": [
            "b2b2cAppend requires one of the following input combinations: [[\"li_url\"],[\"first\",\"last\",\"city\",\"state\"]]"
        ]
    }
}

HTTP status codes

The API attempts to return an HTTP status code for every request. When an error code is returned, check the errors property for details.

Code	Description	Fix
200	Successful request and response. Includes zero-result responses.
400	The request is not structured correctly or is missing required parameters — no valid input combination, missing or invalid `output[]`, a `cfg_required` value that is not a subset of `output[]`, or a `cfg_max_*` value outside 1–10.	Correct the request parameters.
401	Unauthenticated — the API key provided is invalid.	Use a valid API key.
402	Insufficient credits.	Contact your account representative.
429	Requests are exceeding the rate limit.	Reduce the number of requests per second.
500	Something broke on the server. The `errors` property may not be present, and the response object itself may not be returned.	Retry the request, then contact customer service.

Notes and limits

US-only. Non-US records return zero results rather than an error.
One input record per request; there is no multi-record mode on this endpoint.
Consumer phone results are mobile-only.
Each request runs several internal lookups in sequence, so it is slower than a single-source append. Allow generous client-side timeout headroom.
Email validation runs as part of every request, and consumer email candidates are ranked deliverable-first.
Consumer email, consumer address, and mobile phone are derived from the crosswalked consumer identity, so they depend on the consumer match succeeding — a business email can match while all three consumer outputs come back empty.