{"info":{"_postman_id":"236d8720-ed1f-4016-a2df-878f6a0657a7","name":"CommVersion Client API v3","description":"

Fetch Lead Details

Retrieves chat lead data with advanced filtering, sorting, and pagination capabilities.

Features

Date Range Filtering: Filter by date_from and date_to (ISO 8601 format, UTC timezone) on:
\n
- chat_start_time
  \n
- chat_end_time
  \n
- chat_dispatched_at
  \n
\n
Dynamic Sorting: Sort results by chat_start_time, chat_end_time, or chat_dispatched_at in ascending or descending order
\n
Pagination: Configurable page size (1-200 records per page, default: 25)
\n
Security: API key authentication
\n
IP Allowlisting (Additional Security): Access to this API can be restricted by specifying one or more allowed IP addresses or IP address ranges (CIDR notation). Only requests originating from the configured IPs or ranges will be permitted; all other requests will be denied.
\n

Query Limits

Maximum Date Range: 90 days (3 months)
\n
Maximum Page Size: 200 records
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Fetch Lead Details","slug":"fetch-lead-details"}],"owner":"32188624","collectionId":"236d8720-ed1f-4016-a2df-878f6a0657a7","publishedId":"2sB3QFQXRy","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-09-30T13:22:19.000Z"},"item":[{"name":"Get Chat Data","event":[{"listen":"prerequest","script":{"id":"e70fab49-d7b7-4d45-991c-52de64c8bbfa","exec":["// Set dynamic timestamp for date filtering","const now = new Date();","const thirtyDaysAgo = new Date(now.getTime() - (30 * 24 * 60 * 60 * 1000));","","pm.collectionVariables.set(\"date_from\", thirtyDaysAgo.toISOString());","pm.collectionVariables.set(\"date_to\", now.toISOString());"],"type":"text/javascript","packages":{},"requests":{}}},{"listen":"test","script":{"id":"40e6219d-6ca8-4cd1-a25e-0573c7afbc55","exec":["pm.test(\"Status code is 200\", function () {"," pm.response.to.have.status(200);","});","","pm.test(\"Response contains data\", function () {"," const jsonData = pm.response.json();"," pm.expect(jsonData).to.have.property('data');"," pm.expect(jsonData.data).to.have.property('total');","});","","pm.test(\"Response time is acceptable\", function () {"," pm.expect(pm.response.responseTime).to.be.below(5000);","});","","pm.test(\"API Key is valid\", function () {"," pm.expect(pm.response.code).to.not.equal(401);","});"],"type":"text/javascript","packages":{},"requests":{}}}],"id":"8c203c77-0c64-4f7b-bbd1-cf18fbf2d34b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Api-Key","value":"your-api-key-here","description":"

The API Key provided to you by CommVersion

\n","type":"text"},{"key":"User-Agent","value":"MyApp/1.0","description":"

You need to pass a User Agent to identify your machine and pass our firewall checks.

\n","type":"text"},{"key":"Content-Type","value":"application/json","description":"

The API accepts JSON body

\n","type":"text"}],"body":{"mode":"raw","raw":"{\n \"date_from\": \"2025-08-01T00:00:00.000Z\",\n \"date_to\": \"2025-08-31T23:59:59.999Z\",\n \"filter_by\": \"chat_start_time\",\n \"sort_key\": \"chat_end_time\",\n \"sort_order\": \"DESC\",\n \"page\": 2,\n \"page_size\": 50\n}","options":{"raw":{"language":"json"}}},"url":"https://client-api.commversion.com/v3/chats","description":"

Request Parameters

All time-related fields use ISO 8601 format in UTC timezone.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description	Example
`date_from`	string (ISO 8601)	Optional	Start date for filtering	`2025-08-01T00:00:00.000Z`
`date_to`	string (ISO 8601)	Optional	End date for filtering	`2025-08-14T23:59:59.999Z`
`filter_by`	string	Optional	Field to apply date range filter on	`chat_start_time`, `chat_end_time`, `chat_dispatched_at`
`sort_key`	string	Optional	Field to sort results by	`chat_start_time`, `chat_end_time`, `chat_dispatched_at`
`sort_order`	string	Optional	Sort direction (default: `DESC`)	`ASC` or `DESC`
`page`	integer	Optional	Page number, 1-based (default: `1`)	`1`
`page_size`	integer	Optional	Records per page, max 200 (default: `25`)	`25`

Constraints

Maximum Date Range: 90 days (3 months)
\n
Maximum Page Size: 200 records per page
\n

Response Format

Top-Level Structure

{\n  \"data\": [ /* Array of chat objects */ ],\n  \"total\": 100\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`data`	array	Array of chat lead objects (see detailed structure below)
`total`	integer	Total number of records available across all pages

Chat Object Structure

Each object in the data array contains the following sections:

{\n  \"basic\": { /* Basic chat information */ },\n  \"client_details\": { /* Client information */ },\n  \"visitor_details\": { /* Visitor information */ },\n  \"tags\": { /* Chat tags and classifications */ },\n  \"additional_data\": { /* Client-specific additional fields */ },\n  \"metadata\": { /* Marketing metadata */ },\n  \"instant_connect\": { /* Instant connect call details */ },\n  \"custom_fields\": { /* Client-specific custom variables */ }\n}\n\n

Response Field Details

`basic` - Basic Chat Information

Contains core chat details including transcript, duration, and timestamps.

Example:

{\n  \"chat_id\": \"T08WVX8HG5\",\n  \"chat_taken_by\": \"John Doe\",\n  \"chat_start_url\": \"https://example.com/pricing\",\n  \"chat_referrer_url\": \"https://google.com\",\n  \"chat_duration_in_seconds\": 528,\n  \"chat_transcript\": \"Visitor: Hi\\nAgent: How can I help you?\",\n  \"chat_summary\": \"Customer inquired about pricing plans\",\n  \"chat_start_time\": \"2025-08-13T03:24:41.517Z\",\n  \"chat_end_time\": \"2025-08-13T03:32:15.859Z\",\n  \"source\": \"CommVersion\"\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`chat_id`	string	Unique identifier of the chat
`chat_taken_by`	string	Name of the operator who handled the chat
`chat_start_url`	string	URL where the chat was initiated
`chat_referrer_url`	string	Referrer URL from where the visitor came
`chat_duration_in_seconds`	number	Duration of the chat in seconds
`chat_transcript`	string	Complete transcript of the chat conversation
`chat_summary`	string	AI-generated summary of the chat
`chat_start_time`	string (ISO 8601, UTC)	Timestamp when the chat started
`chat_end_time`	string (ISO 8601, UTC)	Timestamp when the chat ended
`source`	string	Source platform of the chat

`client_details` - Client Information

Contains information about the client/organization.

Example:

{\n  \"client_name\": \"Acme Corporation\",\n  \"client_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`client_name`	string	Name of the client
`client_id`	string (UUID)	Unique identifier of the client

`visitor_details` - Visitor Information

Contains visitor contact information and location details.

Example:

{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Smith\",\n  \"name\": \"Jane Smith\",\n  \"phone_number\": \"+1234567890\",\n  \"email\": \"jane.smith@example.com\",\n  \"city\": \"Los Angeles\",\n  \"region\": \"California\",\n  \"country\": \"United States\",\n  \"timezone\": \"America/Los_Angeles\"\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`first_name`	string	First name of the visitor
`last_name`	string	Last name of the visitor
`name`	string	Full name of the visitor
`phone_number`	string	Phone number of the visitor
`email`	string	Email address of the visitor
`city`	string	City of the visitor
`region`	string	Region/state of the visitor
`country`	string	Country of the visitor
`timezone`	string	Timezone of the visitor (IANA format)

`tags` - Chat Tags and Classifications

Contains chat classification and categorization tags.

Example:

{\n  \"chat_type\": \"lead\",\n  \"lead_type\": \"viewing\",\n  \"instantconnect\": \"instantconnect\"\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`chat_type`	string	Type of the chat (e.g., \"lead\", \"support\")
`lead_type`	string	Type of lead classification (e.g., \"viewing\", \"inquiry\")

`additional_data` - Additional Custom Fields

Dynamic object containing client-specific additional fields configured in the system. Field names and values vary by client configuration.

Example:

{\n  \"total_no_of_desks\": \"5\",\n  \"office_space\": \"200 sqft\",\n  \"budget_range\": \"$50k-$100k\"\n}\n\n

Note: This is a dynamic object. The fields shown are examples and will differ based on client configuration.

`metadata` - Marketing Metadata

Contains marketing tracking parameters and identifiers.

Example:

{\n  \"utm_source\": \"google\",\n  \"utm_medium\": \"cpc\",\n  \"utm_term\": \"office+space\",\n  \"utm_campaign\": \"summer_2025\",\n  \"gclid\": \"TeSter-123\",\n  \"fbclid\": \"FbClicker-456\"\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`utm_source`	string	UTM source parameter (traffic source)
`utm_medium`	string	UTM medium parameter (marketing medium)
`utm_term`	string	UTM term parameter (keyword)
`utm_campaign`	string	UTM campaign parameter (campaign name)
`gclid`	string	Google Click ID for ad tracking
`fbclid`	string	Facebook Click ID for ad tracking

`instant_connect` - Instant Connect Information

Contains details about instant connect phone calls associated with the chat.

Example:

{\n  \"is_instantconnect_lead\": true,\n  \"call_started\": \"2025-08-13T03:25:00.000Z\",\n  \"call_ended\": \"2025-08-13T03:30:00.000Z\"\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`is_instantconnect_lead`	boolean	Whether this chat resulted in an instant connect call
`call_started`	string (ISO 8601, UTC)	Timestamp when the phone call started
`call_ended`	string (ISO 8601, UTC)	Timestamp when the phone call ended

`custom_fields` - Custom Variables

Dynamic object containing client-specific custom variables configured in the live chat system. Field names and values vary by client configuration.

Example:

{\n  \"landing_page\": \"https://www.example.com/pricing\",\n  \"postalCode\": \"94102\",\n  \"property_type\": \"commercial\"\n}\n\n

Note: This is a dynamic object. The fields shown are examples and will differ based on client configuration.

Important Notes

All time fields are in UTC timezone - You may need to convert to your local timezone for display
\n
Future Compatibility: Additional fields may be introduced in future versions. Existing fields will remain unchanged, but new fields can be added to any section. Ensure your integration handles unexpected fields gracefully
\n
Dynamic Fields: additional_data and custom_fields are client-specific and may contain different fields for different clients
\n
Null Values: Optional fields may be null or omitted if no data is available
\n

\n","urlObject":{"protocol":"https","path":["v3","chats"],"host":["client-api","commversion","com"],"query":[],"variable":[]}},"response":[{"id":"d6a358fc-9f26-49ac-a96e-f4ea35417953","name":"Success Response","originalRequest":{"method":"POST","header":[{"key":"Api-Key","value":"your-api-key-here","description":"The API Key provided to you by CommVersion ","type":"text"},{"key":"User-Agent","value":"MyApp/1.0","description":"You need to pass a User Agent to identify your machine and pass our firewall checks.","type":"text"},{"key":"Content-Type","value":"application/json","description":"The API accepts JSON body","type":"text"}],"body":{"mode":"raw","raw":"{\n \"date_from\": \"2025-08-01T00:00:00.000Z\",\n \"date_to\": \"2025-08-31T23:59:59.999Z\",\n \"filter_by\": \"chat_start_time\",\n \"sort_key\": \"chat_end_time\",\n \"sort_order\": \"DESC\",\n \"page\": 2,\n \"page_size\": 50\n}","options":{"raw":{"language":"json"}}},"url":"https://client-api.commversion.com/v3/chats"},"status":"Ok","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Successfully retrieved chat data\",\n \"data\": {\n \"data\": [\n {\n \"basic\": {\n \"chat_id\": \"T08WVX8HG5\",\n \"chat_taken_by\": \"Alice\",\n \"chat_start_url\": \"https://company.com/pricing/\",\n \"chat_referrer_url\": \"https://www.google.com/?gclid=CjwKCAjw...\",\n \"chat_duration_in_seconds\": 528.342,\n \"chat_transcript\": \"Visitor: Hi\\nAlice: How can I help you?...\",\n \"chat_summary\": \"The user was inquiring about pricing for design services.\",\n \"chat_start_time\": \"2025-08-13T03:24:41.517Z\",\n \"chat_end_time\": \"2025-08-13T03:32:15.859Z\",\n \"source\": \"CommVersion\"\n },\n \"client_details\": {\n \"client_name\": \"Abc Corporation\",\n \"client_id\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\"\n },\n \"visitor_details\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"name\": \"John Doe\",\n \"phone_number\": \"+1 122 23345\" ,\n \"email\": \"john.doe@gmail.com\",\n \"city\": \"Los Angeles\",\n \"region\": \"California\",\n \"country\": \"United States\",\n \"timezone\": \"America/Los_Angeles\"\n },\n \"tags\": {\n \"chat_type\": \"lead\",\n \"lead_type\": \"viewing\"\n },\n \"additional_data\": {\n \"total_no_of_desks\": \"5\",\n \"office_space\": \"Open Plan\"\n // the field list in this section will be dynamic and will be updated based on the chat data\n },\n \"metadata\": {\n \"utm_source\": \"google\",\n \"utm_medium\": \"cpc\",\n \"utm_term\": \"office+space\",\n \"utm_campaign\": \"summer_campaign\",\n \"gclid\": \"CjwKCAjw...\",\n \"fbclid\": \"IwAR3...\"\n },\n \"instant_connect\": {\n \"is_instantconnect_lead\": true,\n \"call_started\": \"2025-08-13T03:25:00.000Z\",\n \"call_ended\": \"2025-08-13T03:30:15.000Z\"\n },\n \"custom_fields\": {\n // the field list in this section will be dynamic and will be updated based on the chat data. Usually this is empty.\n }\n }\n ],\n \"total\": 150\n }\n}"},{"id":"d2d308e4-350d-45b9-b306-b1cb685a0c63","name":"Unauthorized","originalRequest":{"method":"POST","header":[{"key":"Api-Key","value":"invalid-key","type":"text"},{"key":"User-Agent","value":"MyApp/1.0","type":"text"}],"body":{"mode":"raw","raw":"{\n \"date_from\": \"2025-08-01T00:00:00.000Z\",\n \"date_to\": \"2025-08-31T23:59:59.999Z\",\n \"filter_by\": \"chat_start_time\",\n \"sort_key\": \"chat_end_time\",\n \"sort_order\": \"DESC\",\n \"page\": 2,\n \"page_size\": 50\n}","options":{"raw":{"language":"json"}}},"url":"https://client-api.commversion.com/v3/chats"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\",\n \"error\": \"Unauthorized\"\n}"},{"id":"06ec1c42-234f-4cd6-99c4-a848b5f26ccb","name":"Bad Request","originalRequest":{"method":"POST","header":[{"key":"User-Agent","value":"MyApp/1.0","type":"text"}],"body":{"mode":"raw","raw":"{\n \"date_from\": \"2025-08-01T00:00:00.000Z\",\n \"date_to\": \"2025-08-31T23:59:59.999Z\",\n \"filter_by\": \"chat_start_time\",\n \"sort_key\": \"chat_end_time\",\n \"sort_order\": \"DESC\",\n \"page\": 2,\n \"page_size\": 50\n}","options":{"raw":{"language":"json"}}},"url":"https://client-api.commversion.com/v3/chats"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 400,\n \"message\": \"Api-Key header is required\",\n \"error\": \"Bad Request\"\n}"}],"_postman_id":"8c203c77-0c64-4f7b-bbd1-cf18fbf2d34b"}],"event":[{"listen":"prerequest","script":{"id":"0c8105a0-19bd-4eca-8651-619de602c4f0","type":"text/javascript","packages":{},"requests":{},"exec":[""]}},{"listen":"test","script":{"id":"7e522f84-e7d1-4d90-a096-949b133aebaa","type":"text/javascript","packages":{},"requests":{},"exec":[""]}}],"variable":[{"key":"base_url","value":"https://cvhub-api.commversion.com/clients-api"},{"key":"api_key","value":"your-api-key-here"},{"key":"user_agent","value":"MyApp/1.0"}]}

Fetch Lead Details

Features

Query Limits

Request Parameters

Constraints

Response Format

Top-Level Structure

Chat Object Structure

Response Field Details

basic - Basic Chat Information

client_details - Client Information

visitor_details - Visitor Information

tags - Chat Tags and Classifications

additional_data - Additional Custom Fields

metadata - Marketing Metadata

instant_connect - Instant Connect Information

custom_fields - Custom Variables

Important Notes

`basic` - Basic Chat Information

`client_details` - Client Information

`visitor_details` - Visitor Information

`tags` - Chat Tags and Classifications

`additional_data` - Additional Custom Fields

`metadata` - Marketing Metadata

`instant_connect` - Instant Connect Information

`custom_fields` - Custom Variables