Lead Injection

post

https://api.vcita.biz/v1/partners/leads

Overview

Inject a lead into a business account under your directory.

Available for Directory tokens only.

Authentication

Uses HTTP Token authentication. Format: Authorization: Token token="{DIRECTORY_TOKEN}"

The token must be a Doorkeeper OAuth token with directory scope.

Conditional Requirements

When identifier_type is "email", the email field is required.
When identifier_type is "unique_id", the unique_id field is required.
At least one of request_data or system_message must be provided. Omitting both will result in a 422 error.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

business_id

string

required

A unique identifier of the business. Can be the our business_uid or external_id

notifications

string

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

identifier_type

string

enum

required

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

Allowed:

string

Lead email address. Unique per lead. Required when identifier_type is "email"

unique_id

string

Lead unique id. Unique per business. Required when identifier_type is "unique_id"

phone

string

Lead phone number

first_name

string

required

Lead first name. Mandatory for a new lead

last_name

string

Lead last name

opt_in

string

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

request_title

string

required

Request title. Will also be the created conversation title

request_data

string

required

system_message

string

A message displayed to the business owner to introduce the lead. May contain links. At least one of request_data or system_message must be provided.

source

string

Will be displayed to the business owner as the lead source

source_url

string

The URL of the page where the lead was created

address

string

Lead's address

Headers

Authorization

string

required

HTTP Token authentication. Format: Token token="{DIRECTORY_TOKEN}". The token must have directory scope.

Responses

201Lead created successfully. Returns the conversation UID for the newly created lead.

401Unauthorized - Invalid or missing directory token.

422Unprocessable Entity - Validation error. Common causes: missing required fields, missing both request_data and system_message, or invalid identifier.