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!

Reporting

Reporting API allows directory admins to query about activity of their clients' accounts in vCita. Every query will be responded by a JSON response containing a list of items showing the activity in the all the directory accounts.

Authentication

Reporting 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/reports/impressions -H Authorization: Token token="aaaabbbbccccddddeeeeffff11112222"

Engagements Report

Query for a list of all the conversations (a.k.a engagements) for a given date range. Conversations will be sorted by date of creation. The GET request will be answered by a JSON containing an array of engagement objects.

Usage Example:

GET https://api.vcita.com/v1/partners/reports/engagements?fromDate=2014-04-12&toDate=2014-04-13

The engagement object will include the following fields:

field
description

created_at

The creation time of the conversation

business_responded

Whether the conversation includes messages by the business. used to determine whether the business responded to the contact request by a client. Business responded =1, Business didn't respond =0.

engagement_id

An internal vCita ID of the engagement

lead_type

The type of the initial message that started this conversation. e.g. "appointment", "payment", "message", "document"

business_id

An internal vCita ID of the business account

business_nickname

The vCita nickname of the business account

source_type

The source type of the engagement. indicates how the engagement started. (e.g. contact_form, livesite_widget etc)

source

If relevant, the URL the client contacted the business from.

tags

The tag (if exists) that was assigned by the directory to the business account.

title

The engagement title

updated_at

The last time the business or a client responded on this engagement

client_first_name

The first name of the client

client_last_name

The last name of the client

client_id

The vCita client unique id

An example for an engagement object:

"engagement":{
"created_at":"2014-01-16T09:42:52+02:00",
"business_responded":0,
"id":"gxuw6fjw0ojxqunn",
"lead_type":"Expert",
"business_nickname":"righttax",
"business_id":"3e4ada55",
"source":"http://righttax.com/",
"source_type":"contact_form",
"tags":"mytag",
"title":"Contact Request - please call me back",
"updated_at":"2014-04-12T09:29:43+03:00",
"client_first_name":"John",
"client_last_name":"Doe",
"client_id":"dfww6fjw0ojxsfnn"
}

Widget Impressions Report

Query for the number of impressions per day for a given date range. The GET request will answered by a JSON of an array of impressions_daily objects. Each impressions_daily object provides information about the number of impressions vCita had for a specified business account.

Usage Example:

GET https://api.vcita.com/v1/partners/reports/impressions?fromDate=2014-04-12&toDate=2014-04-13

The impressions_daily object will include the following fields:

Field
Description

livesite_widget

Count of daily impressions for livesite_widget

livesite

Count of Livesite portal pages impressions

day

The day this impressions count relates to

business_id

The internal vCita ID of the business account this impressions count relates to

business_nickname

The vCita nickname of the business account this impressions count relates to

tags

The tag (if exists) that was assigned by the directory to the business this impressions count relates to.

An example for an impressions_daily object:

{
"impressions_daily":{
"livesite_widget":43,
"livesite":13,
"day":"2014-04-12",
"business_nickname":"righttax",
"business_id":"3e4ada55",
"tags":"mytag"
}

Return Codes (identical for all reports)

Parameter
Description

201 OK

The query was processed correctly. Return Value: [engagements]

401 Unauthorized

Failed authenticating with the token. See content for more information

422 Unprocessable Entity

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

Business Info

Query the one business basic information.

GET https://api.vcita.com/v1/partners/reports/business?email=user@provider.com

The response will include the following fields:

Field
Description

first_name

The business owner first name

last_name

The business owner last name

email

Business main email adress

business_name

Business name

business_phone

Business main phone number

business_address

Business main address

business_description

free text description of the business

hide_address

Whether or not the business owner chose to hide the business address

login_token

a token that can be used to login as the business owner

{
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@provider.com",
    "business_name": "Test Business",
    "business_phone": "(123) 456-7890",
    "business_address": "1 Fox st. New-York, NY 42101 ",
    "business_description": "My full business descriptions",
    "hide_address": false,
    "login_token": "dfsdfsdfsdfsdffdffff"
}

Reporting


Suggested Edits are limited on API Reference Pages

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