The vCita Developer Hub

Welcome to the vCita developer hub. You'll find comprehensive guides and documentation to help you start working with vCita as quickly as possible, as well as support if you get stuck. Let's jump right in!

Lead Injection

Lead Injection API allows directory admins to send new leads or messages to any account in their system. It is usually used to connect existing lead sources such as 3rd party apps or online forms to vCita.


Lead Injection API requires a token that can be provided to partners and directory admins.
To receive a token please contact us at

The token should be added as an HTTP header to every API call, see example below:

curl -H Authorization: Token token="aaaabbbbccccddddeeeeffff11112222"

Injecting a Lead

Lead will be injected to a specific account (identified by the business_id parameter).
When injecting a lead, the system will either create a new client entry for the business or add a message connected to an existing client. A new conversation with a message inside will always be created.


Lead Attributes:


General Information


A unique identifier of the business. Can be the vCita uuid or nickname. REQUIRED


A list of notifications to send after processing of the lead.
Possible values: "auto-reply" (thank you email to the end user), "email" (notify the business owner) or "sms" (text notification to the business owner). None if empty.

Client Information


Defines which unique identifier will be used to search for an existing lead or create a new one. Possible values: "email" or "unique_id" REQUIRED


Lead email address. Unique per business. IMMUTABLE


Lead unique id. Unique per business. IMMUTABLE


Lead phone number. IMMUTABLE


Lead first name. Mandatory for a new lead. IMMUTABLE


Lead last name. IMMUTABLE


Send "true" if lead opted in for promotions.
Make sure the "opt-in" client card field is added to the client card under Settings>Client card.

Message Information


Request title. Will also be the created conversation title. REQUIRED


The information that the end user has provided. (e.g the labels and values of a contact form/client card).

  • Replace {field_name} with the field name/label.
  • Repeat this parameter for every field.
  • Value can be a string, if a date field value is given a string with the format YYYY-MM-DD is expected.

Please note: this information is visible both to the business owner and to the end user. Therefore it should not contain private business information.


A message displayed to the business owner to introduce the lead. May contain links.


Will be displayed to the business owner as the lead source


The URL of the page where the lead was created.


Lead's address

IMMUTABLE Means it is set once per client on creation and can't be changed using the API afterwards.

Return Codes:


201 OK

The lead has been processed correctly. Return Value: {uid: new_engagement_uid}

401 Unauthorized

Failed authenticating with the token. See content for more information

422 Unprocessable Entity

Bad parameter(s). See content for more information.

Usage Example

curl -H 'Authorization: Token token="token"' -i -X POST -d 
'request_title=Contact Request&business_id=business_id&identifier_type=email & source=Law Pages&source_url= contact request from LawPages&request_data[e-mail][name]=John Doe&request_data[Cell Phone]=050-1234567&request_data[Address]=Country rode 19, Arizona&request_data[Message]=Im interested in a good real-estate attorney&notifications[]=email&notifications[]=auto_reply&notifications[]=sms'

Lead Injection

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.