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.
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"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-13The engagement object will include the following fields:
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"
}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-13The impressions_daily object will include the following fields:
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"
}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.
Query the one business basic information.
GET https://api.vcita.com/v1/partners/reports/business?email=user@provider.comThe response will include the following fields:
first_name
The business owner first name
last_name
The business owner last name
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"
}