JSON-over-HTTPS integration surface for the Conversica Platform. A customer system posts Lead objects to a single Conversica endpoint using HTTP Basic authentication, and Conversica posts Message objects, Lead Update objects and optional Website Chat lead-creation payloads back to endpoints the customer provides. Credentials are issued by a Conversica technical account manager and applications must be approved by Conversica before they are enabled.
openapi: 3.1.0
info:
title: Conversica Integrations API
version: '7.2'
summary: Post Lead data into the Conversica Platform and receive Message and Lead Update callbacks.
description: |
The Conversica Integrations API lets a customer system (CRM or marketing automation
platform) transport Lead data into the Conversica Platform, and receive Lead Update
and Message data back from the Conversica Platform. All traffic is JSON-encoded
POST over HTTPS with HTTP Basic access authentication.
Direction of travel:
* Customer System -> Conversica: `POST https://integrations-api.conversica.com/json/`
with a Lead object.
* Conversica -> Customer System: Conversica POSTs Message objects and Lead Update
objects to two endpoints the customer provides (see the `webhooks` section). The
Website Chat lead-creation webhook is a third, optional customer endpoint.
Credentials are issued by a Conversica technical account manager; there is no
self-serve signup for this API. Applications must be tested and approved by
Conversica before they are enabled.
contact:
name: Conversica Support
email: support@conversica.com
url: https://help.conversica.com/hc/en-us/sections/360012154451-Conversica-API
termsOfService: https://www.conversica.com/legal-info/conversica-api-terms-of-service
x-provenance:
method: generated
generated: '2026-08-01'
note: >-
Faithfully transcribed from Conversica's published API Integration Manual and the
Website Chat lead-creation webhook article. Conversica publishes no machine-readable
spec; every path, field, type, requiredness, status code and example below is taken
verbatim from those documents. Nothing was invented.
x-evidence:
fetched: '2026-08-01'
sources:
- url: https://help.conversica.com/hc/en-us/articles/360048601712-Conversica-API-Integration-Manual
title: Conversica API Integration Manual
http_status: 200
note: retrieved via the Zendesk Help Center API (the HTML page returns 403 to non-browser clients)
doc_updated: '2025-11-26'
- url: https://help.conversica.com/hc/en-us/articles/38828763556635-Implementing-a-Conversica-API-Lead-Creation-Webhook-for-Website-Chat
title: Implementing a Conversica API Lead Creation Webhook for Website Chat
http_status: 200
- url: https://integrations-api.conversica.com/json/
http_status: 405
note: live probe - GET returns 405 Method Not Allowed, confirming the documented POST-only endpoint
servers:
- url: https://integrations-api.conversica.com
description: Conversica production integrations endpoint
security:
- basicAuth: []
tags:
- name: Leads
description: Posting Lead object data into the Conversica Platform.
paths:
/json/:
post:
operationId: postLead
summary: Post a Lead to the Conversica Platform
description: |
Sends a Lead object to Conversica so a Conversica Assistant can begin (or continue)
a conversation with that Lead. The endpoint accepts a JSON object; keys with a
`datetime` type must be UTC values following RFC 3339, and keys with a `boolean`
type must be `true` or `false`.
tags:
- Leads
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Lead'
examples:
minimalLead:
summary: Minimal Lead (from the integration manual)
value:
apiVersion: '7.2'
id: '12345'
conversationId: My Big Event 2019
firstName: Sally
email: sally@email.com
leadSource: Big Events
leadStatus: New
optOut: false
repId: '98765'
repName: John
automotiveLead:
summary: Automotive Lead with industry-specific keys (from the integration manual)
value:
apiVersion: '7.2'
id: '12345'
clientId: '67890'
firstName: Sally
lastName: Jones
email: sally@email.com
homePhone: '3609483728'
leadType: Internet
leadStatus: New
leadSource: www.leadsource.com
date: '2017-01-10T15:19:21+00:00'
repName: John Doe
repId: '23254'
repEmail: john@dealershipname.com
bdcRepName: Sheila Smith
bdcRepId: '20582'
bdcRepEmail: sheila@dealershipname.com
serviceRepName: Billy Brown
serviceRepId: '20143'
serviceRepEmail: billy@dealershipname.com
year: '2019'
make: Volkswagen
model: Atlas SEL
vin: 1N4AL2APXBC154449
appointmentStatus: Scheduled
appointmentDate: '2017-01-10T15:19:21+00:00'
optOut: false
smsOptOut: true
stopMessaging: false
skipToFollowup: true
responses:
'200':
description: OK - the request was successful.
'400':
description: Bad Request - the request could not be understood due to an error.
'401':
description: Unauthorized - the request could not be processed due to authentication.
webhooks:
message:
post:
operationId: receiveMessage
summary: Receive a Message object from Conversica
description: |
Conversica POSTs a Message object to the customer-provided message endpoint each
time the Assistant sends a message to a Lead or receives a response from a Lead.
The customer endpoint must use HTTPS and HTTP Basic access authentication with the
single username/password pair the customer shares with Conversica. Documented
example endpoint forms: `https://api.customername.com/conversicaMessage/` or
`https://api.customername.com/conversica/message`.
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples:
sent:
summary: Message sent by the Assistant
value:
apiVersion: '7.2'
id: '12345'
clientId: '67890'
action: sent
date: '2019-05-10T05:57:44+00:00'
subject: Your online request
body: |-
Hi Sally,
Thanks for reaching out to us online. Would you like to schedule a demo with one of our representatives to learn more about our product?
Sincerely,
John
received:
summary: Message received from the Lead
value:
apiVersion: '7.2'
id: '12345'
clientId: '67890'
action: received
date: '2019-05-10T05:57:44+00:00'
subject: 'Re: Your online request'
body: |-
Hi John
Sure, I have some time tomorrow after 3 pm Pacific, if that works?
Thanks,
Sally
responses:
'200':
description: Message accepted by the customer system.
leadUpdate:
post:
operationId: receiveLeadUpdate
summary: Receive a Lead Update object from Conversica
description: |
Conversica POSTs a Lead Update object to the customer-provided lead endpoint when
the state of a Lead or Conversation changes. Other than `apiVersion`, `id` and
`clientId`, only keys with updated values are sent per request - not every field
appears in every update. Documented example endpoint forms:
`https://api.customername.com/conversicaLead/` or
`https://api.customername.com/conversica/lead`.
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LeadUpdate'
examples:
engagementUpdate:
summary: Engagement / hot lead update
value:
apiVersion: '7.2'
id: '12345'
clientId: '67890'
dateAdded: '2019-05-24T19:14:55+00:00'
firstMessageDate: '2019-05-24T19:24:55+00:00'
lastMessageDate: '2019-05-24T19:27:55+00:00'
lastResponseDate: '2019-05-25T12:06:55+00:00'
hotLead: true
hotLeadDate: '2019-05-25T12:06:55+00:00'
discoveredPhone1: '5558675309'
doNotEmail: false
smsOptIn: true
stageUpdate:
summary: Conversation stage / status update
value:
apiVersion: '7.2'
id: '12345'
clientId: '67890'
leadStatus: None
leadStatusDate: '2019-05-24T19:24:30+00:00'
conversationStage: Messaging
conversationStageDate: '2019-05-24T19:24:30+00:00'
conversationStatus: Sent Message
conversationStatusDate: '2019-05-24T19:24:30+00:00'
responses:
'200':
description: Lead Update accepted by the customer system.
chatLeadCreated:
post:
operationId: receiveChatLead
summary: Receive a Website Chat lead-creation callback from Conversica
description: |
Optional webhook for Conversica Website Chat. When the chat agent captures a
visitor, Conversica POSTs the captured lead plus the chat transcript to a
publicly accessible customer endpoint over HTTPS with HTTP Basic authentication.
Documented example endpoint forms:
`https://api.customername.com/conversicaCreate/` or
`https://api.customername.com/conversica/create`.
The endpoint must reply with a JSON object carrying `status` and `message`.
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatLead'
examples:
chatLead:
summary: Website Chat lead (from the webhook article)
value:
firstName: John
lastName: Doe
email: john.doe@example.com
conversationHistory: |-
2025-05-23T11:40:07 John Doe: I'm interested in your product.
2025-05-23T11:40:11 Conversica (Assistant): Great! Let me get some details...
responses:
'200':
description: Lead received successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookAck'
examples:
ok:
value:
status: '200'
message: Lead received successfully
'400':
description: Invalid request data.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookAck'
examples:
badRequest:
value:
status: '400'
message: 'Missing required field: email'
'401':
description: Invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookAck'
'500':
description: An error occurred on the server.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookAck'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: |
HTTPS basic access authentication. Conversica issues a username and password for
the Conversica endpoint; the customer issues a single username/password pair that
Conversica uses for both customer endpoints. API usernames have a five-character
minimum. Credentials are obtained from a Conversica technical account manager.
schemas:
Lead:
type: object
title: Lead
description: >-
Data containing relevant information for communication by the Conversica Assistant
with a customer's prospects. Depending on the Conversation and Assistant in use, a
Lead may be a lead, contact, customer, account, prospect, or other related entity.
Automotive-specific keys are included and apply only to Automotive Assistants.
required:
- apiVersion
- id
- conversationId
- firstName
- email
- leadSource
- repName
properties:
apiVersion:
type: string
description: The version number of the Conversica API in use.
examples:
- '7.2'
id:
type: string
description: The Lead's unique ID in the customer's system (Source ID).
conversationId:
type: string
description: >-
For a particular Conversation, a list or filtered set of Leads (e.g. "campaign"
in some CRMs) for the purpose of tailoring messaging to a more specific
audience or use case.
firstName:
type: string
description: The Lead's first name, used in messaging.
email:
type: string
description: The Lead's primary email address for messaging.
leadSource:
type: string
description: >-
The source of the Lead, as indicated in the customer's system and as used by
Conversica for reporting on Lead Source performance or other customizations.
leadStatus:
type: string
description: >-
The status of the Lead, as indicated in the customer's system and as used by
Conversica for intelligent Conversation management (e.g. "New", "Sold", "Lost").
optOut:
type: boolean
description: Whether the Lead has opted out of all methods of marketing and contact (global opt-out).
repId:
type: string
description: The Salesperson's (Lead owner) unique ID in the customer's system.
repName:
type: string
description: The Salesperson's (Lead owner) name, used in messaging.
repEmail:
type: string
description: The Salesperson's (Lead owner) email address.
clientId:
type: string
description: >-
Unique ID for the customer in the customer's system. Required if the API
integration will be used for multiple Conversica customers.
lastName:
type: string
description: The Lead's last name.
homePhone:
type: string
description: The Lead's primary phone number.
workPhone:
type: string
description: The Lead's work phone number.
cellPhone:
type: string
description: The Lead's cell phone number. Required for SMS.
address:
type: string
description: The Lead's street address.
city:
type: string
description: The Lead's city.
state:
type: string
description: The Lead's state.
zip:
type: string
description: The Lead's zip code.
leadType:
type: string
description: The type of the Lead, as indicated in the customer's system (e.g. "Internet", "Web Form", "Phone-In").
date:
type: string
format: date-time
description: The date and time the Lead was created in the customer's system (UTC, RFC 3339).
smsOptOut:
type: boolean
description: Whether the Lead has opted out of being contacted by SMS text messaging. Required for SMS Conversations.
smsOptIn:
type: boolean
description: Whether the Lead has accepted being contacted by SMS text messaging. Required for SMS Conversations.
stopMessaging:
type: boolean
description: If true, the Assistant stops listening for responses and will no longer message the Lead.
skipToFollowup:
type: boolean
description: If true, the Assistant waits a few days before sending a follow-up message.
leadSubStatus:
type: string
description: Automotive - the sub-status of the Lead, as indicated in the customer's system.
appointmentStatus:
type: string
description: Automotive - the current appointment status/stage for the Lead in the customer's system (e.g. "Scheduled").
appointmentDate:
type: string
format: date-time
description: Automotive - the date and time the Lead entered into the current appointment status.
bdcRepId:
type: string
description: Automotive - the BDC representative's unique ID in the customer's system.
bdcRepName:
type: string
description: Automotive - the BDC representative's name, used in messaging.
bdcRepEmail:
type: string
description: Automotive - the BDC representative's email address.
serviceRepId:
type: string
description: Automotive - the service advisor's unique ID in the customer's system.
serviceRepName:
type: string
description: Automotive - the service advisor's name, used in messaging.
serviceRepEmail:
type: string
description: Automotive - the service advisor's email address.
year:
type: string
description: Automotive - the year of the vehicle of interest or primary vehicle associated with the Lead.
make:
type: string
description: Automotive - the make of the vehicle of interest or primary vehicle associated with the Lead.
model:
type: string
description: Automotive - the model of the vehicle of interest or primary vehicle associated with the Lead.
vin:
type: string
description: Automotive - the vehicle identification number of the vehicle associated with the Lead.
Message:
type: object
title: Message
description: >-
The communication between the Conversica Assistant and the Lead, including
communication both sent to and received from the Lead. All keys are required.
required:
- apiVersion
- id
- clientId
- action
- date
- subject
- body
properties:
apiVersion:
type: string
description: Version number of the Conversica API in use.
id:
type: string
description: The Lead's unique ID in the customer's system.
clientId:
type: string
description: Unique ID for the customer in the customer's system.
action:
type: string
description: Whether the message was sent by the Assistant or received from the Lead.
enum:
- sent
- received
date:
type: string
format: date-time
description: The date and time the message was sent or received.
subject:
type: string
description: The subject of the message sent or received.
body:
type: string
description: The body of the message sent or received.
LeadUpdate:
type: object
title: LeadUpdate
description: >-
Updates about the Lead and Conversation. Other than apiVersion, id and clientId,
only keys with updated values are sent per request.
required:
- apiVersion
- id
- clientId
properties:
apiVersion:
type: string
description: Version number of the Conversica API in use.
id:
type: string
description: The Lead's unique ID in the customer's system.
clientId:
type: string
description: Unique ID for the customer in the customer's system.
dateAdded:
type: string
format: date-time
description: The date and time the Lead was added to Conversica.
firstMessageDate:
type: string
format: date-time
description: The date and time the Assistant sent their first message to the Lead.
lastMessageDate:
type: string
format: date-time
description: The date and time the Assistant last sent a message to the Lead.
lastResponseDate:
type: string
format: date-time
description: The date and time the Assistant last received a response from the Lead.
hotLead:
type: boolean
description: If true, the Lead has expressed interest and is ready to be contacted by the Salesperson.
hotLeadDate:
type: string
format: date-time
description: The date and time the Lead became a Hot Lead.
leadAtRisk:
type: boolean
description: If true, the Lead was interested but has yet to be contacted by the Salesperson.
leadAtRiskDate:
type: string
format: date-time
description: The date and time the Lead became a Lead at Risk.
actionRequired:
type: boolean
description: >-
If true, the Lead's response requires review by the Salesperson and the
Assistant has stopped messaging.
actionRequiredDate:
type: string
format: date-time
description: The date and time the Lead was set as Action Required.
discoveredPhone1:
type: string
description: A new and unique phone number detected by the Assistant while messaging the Lead.
discoveredPhone2:
type: string
description: A new and unique phone number detected by the Assistant while messaging the Lead.
discoveredEmail1:
type: string
description: A new and unique email detected by the Assistant while messaging the Lead.
discoveredEmail2:
type: string
description: A new and unique email detected by the Assistant while messaging the Lead.
leadStatus:
type: string
description: >-
An actionable Status for the Lead, either during or after engagement with the
Assistant. See vocabulary/conversica-conversation-vocabulary.yml.
leadStatusDate:
type: string
format: date-time
description: The date and time the Lead entered into the current Conversica Lead Status.
conversationStage:
type: string
description: The current Stage of the Conversation. See vocabulary/conversica-conversation-vocabulary.yml.
conversationStageDate:
type: string
format: date-time
description: The date and time the Conversation entered into the current Stage.
conversationStatus:
type: string
description: The current Status of the Conversation. See vocabulary/conversica-conversation-vocabulary.yml.
conversationStatusDate:
type: string
format: date-time
description: The date and time the Conversation entered into the current Status.
doNotEmail:
type: boolean
description: If true, the Lead has requested to no longer be contacted by email.
smsOptIn:
type: boolean
description: If true, the Lead has accepted being contacted by SMS text messaging.
smsOptOut:
type: boolean
description: If true, the Lead has requested to not be contacted by SMS/text messaging.
ChatLead:
type: object
title: ChatLead
description: Lead captured by Conversica Website Chat, delivered to the customer's lead-creation webhook.
required:
- firstName
- lastName
- email
- conversationHistory
properties:
firstName:
type: string
description: First name of the lead.
lastName:
type: string
description: Last name of the lead.
email:
type: string
description: Email address of the lead.
conversationHistory:
type: string
description: Transcript of the chat conversation.
clientId:
type: string
description: ID of the client in the partner's system. Sent only for provider-style integrations.
WebhookAck:
type: object
title: WebhookAck
description: >-
Acknowledgement envelope the customer's Website Chat lead-creation webhook must
return: a JSON object containing status and message.
required:
- status
- message
properties:
status:
type: string
description: The HTTP status code, as a string.
enum:
- '200'
- '400'
- '401'
- '500'
message:
type: string
description: Human-readable result message.
ⓘWhere this information came from
This is an independent, third-party profile of Conversica Integrations API, published by
API Evangelist. We do not operate, host, resell, or
support these APIs, and we are not affiliated with or endorsed by the company unless stated above.
Everything here is built from publicly available information — the company's own site,
developer portal, documentation, public repositories, and the specifications it publishes for public use.
Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's
public API artifacts, scored against a published rubric. They are not certifications,
endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and
you do not need to justify the request. A removed company is recorded as unrated, never scored
zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy → On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.