--- updatedAt: 2026-08-24T19:17:09.000Z agentTools: projectIndex: https://api-documentation.versium.com/llms.txt --- # 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 ```json { "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": "JANE.DOE@EXAMPLECORP.COM" } ], "PhoneJSONB2C": [ { "Phone": "5551234567", "LineType": "Mobile", "Carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS - NE", "CarrierParent": "Verizon" } ], "EmailAddrJSONB2C": [ { "EmailAddr": "JANE.DOE@EXAMPLE.COM" } ], "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`. ```json { "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. ```json { "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.