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.

Authentication

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

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

curl https://api.vcita.com/v1/partners/leads -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.

POST https://api.vcita.com/v1/partners/leads

Lead Attributes:

Parameter
Description

General Information

business_id

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

notifications

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

identifier_type

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

email

Lead email address. Unique per business. IMMUTABLE

unique_id

Lead unique id. Unique per business. IMMUTABLE

phone

Lead phone number. IMMUTABLE

first_name

Lead first name. Mandatory for a new lead. IMMUTABLE

last_name

Lead last name. IMMUTABLE

opt_in

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

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

request_data[{field_name}]

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.

system_message

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

source

Will be displayed to the business owner as the lead source

source_url

The URL of the page where the lead was created.

address

Lead's address

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

Return Codes:

Parameter
Description

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 &email=johndoe@gmail.com&first_name=John&last_name=Doe&phone=050-1234567& source=Law Pages&source_url=http://www.lawpages.com&system_message=New contact request from LawPages&request_data[e-mail]=johndoe@gmail.com&request_data[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' https://api.vcita.com/v1/partners/leads

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.