Reporting

{"_id":"55478a479a48800d00c6e537","user":"54d350b5eefae10d0016cfbc","githubsync":"","category":{"_id":"554213dacbc48d0d001544ef","pages":["55421a3f6592e60d00027c19","55421a4a6592e60d00027c1b","55421a776592e60d00027c1e","55421e4d6592e60d00027c24","55478a479a48800d00c6e537","555379d8d402b92300cee2f5"],"project":"54ad7b1d9219922100751796","version":"5505581f728deb23005ec0f4","__v":6,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-30T11:36:58.428Z","from_sync":false,"order":2,"slug":"partners-api","title":"Partners API"},"version":{"_id":"5505581f728deb23005ec0f4","forked_from":"54ad7b1d9219922100751799","project":"54ad7b1d9219922100751796","__v":4,"createdAt":"2015-03-15T09:59:59.748Z","releaseDate":"2015-03-15T09:59:59.748Z","categories":["55055820728deb23005ec0f5","55055820728deb23005ec0f6","554213dacbc48d0d001544ef","55421a598aeff51700a20db6","55a64fe680c8a30d00b325e0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"project":"54ad7b1d9219922100751796","__v":11,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-05-04T15:03:35.896Z","link_external":false,"link_url":"","sync_unique":"","hidden":true,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"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. \n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Authentication\"\n}\n[/block]\nReporting API requires a token that can be provided to partners and directory admins. \n**To receive a token please contact us at partners:::at:::vcita.com.**\n\nThe token should be added as an HTTP header to every API call, see example below:\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl https://api.vcita.com/v1/partners/reports/impressions -H Authorization: Token token=\\\"aaaabbbbccccddddeeeeffff11112222\\\"\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Engagements Report\"\n}\n[/block]\nQuery 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. \n\nUsage Example:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"GET https://api.vcita.com/v1/partners/reports/engagements?fromDate=2014-04-12&toDate=2014-04-13\",\n \"language\": \"http\"\n }\n ]\n}\n[/block]\nThe engagement object will include the following fields:\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"field\",\n \"h-1\": \"description\",\n \"0-0\": \"created_at\",\n \"0-1\": \"The creation time of the conversation\",\n \"1-0\": \"business_responded\",\n \"1-1\": \"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.\",\n \"2-0\": \"engagement_id\",\n \"2-1\": \"An internal vCita ID of the engagement\",\n \"3-0\": \"lead_type\",\n \"3-1\": \"The type of the initial message that started this conversation. e.g. \\\"appointment\\\", \\\"payment\\\", \\\"message\\\", \\\"document\\\"\",\n \"4-0\": \"business_id\",\n \"4-1\": \"An internal vCita ID of the business account\",\n \"6-0\": \"source_type\",\n \"6-1\": \"The source type of the engagement. indicates how the engagement started. (e.g. contact_form, livesite_widget etc)\",\n \"7-0\": \"source\",\n \"7-1\": \"If relevant, the URL the client contacted the business from.\",\n \"8-0\": \"tags\",\n \"8-1\": \"The tag (if exists) that was assigned by the directory to the business account.\",\n \"9-0\": \"title\",\n \"9-1\": \"The engagement title\",\n \"10-0\": \"updated_at\",\n \"10-1\": \"The last time the business or a client responded on this engagement\",\n \"5-0\": \"business_nickname\",\n \"5-1\": \"The vCita nickname of the business account\",\n \"11-0\": \"client_first_name\",\n \"11-1\": \"The first name of the client\",\n \"12-0\": \"client_last_name\",\n \"12-1\": \"The last name of the client\",\n \"13-0\": \"client_id\",\n \"13-1\": \"The vCita client unique id\"\n },\n \"cols\": 2,\n \"rows\": 14\n}\n[/block]\nAn example for an engagement object:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"\\\"engagement\\\":{\\n\\\"created_at\\\":\\\"2014-01-16T09:42:52+02:00\\\",\\n\\\"business_responded\\\":0,\\n\\\"id\\\":\\\"gxuw6fjw0ojxqunn\\\",\\n\\\"lead_type\\\":\\\"Expert\\\",\\n\\\"business_nickname\\\":\\\"righttax\\\",\\n\\\"business_id\\\":\\\"3e4ada55\\\",\\n\\\"source\\\":\\\"http://righttax.com/\\\",\\n\\\"source_type\\\":\\\"contact_form\\\",\\n\\\"tags\\\":\\\"mytag\\\",\\n\\\"title\\\":\\\"Contact Request - please call me back\\\",\\n\\\"updated_at\\\":\\\"2014-04-12T09:29:43+03:00\\\",\\n\\\"client_first_name\\\":\\\"John\\\",\\n\\\"client_last_name\\\":\\\"Doe\\\",\\n\\\"client_id\\\":\\\"dfww6fjw0ojxsfnn\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Widget Impressions Report\"\n}\n[/block]\nQuery 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.\n\nUsage Example:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"GET https://api.vcita.com/v1/partners/reports/impressions?fromDate=2014-04-12&toDate=2014-04-13\",\n \"language\": \"http\"\n }\n ]\n}\n[/block]\nThe impressions_daily object will include the following fields:\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Field\",\n \"h-1\": \"Description\",\n \"0-0\": \"livesite_widget\",\n \"0-1\": \"Count of daily impressions for livesite_widget\",\n \"1-0\": \"livesite\",\n \"1-1\": \"Count of Livesite portal pages impressions\",\n \"2-0\": \"day\",\n \"2-1\": \"The day this impressions count relates to\",\n \"3-0\": \"business_id\",\n \"3-1\": \"The internal vCita ID of the business account this impressions count relates to\",\n \"4-0\": \"business_nickname\",\n \"4-1\": \"The vCita nickname of the business account this impressions count relates to\",\n \"5-0\": \"tags\",\n \"5-1\": \"The tag (if exists) that was assigned by the directory to the business this impressions count relates to.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]\nAn example for an impressions_daily object:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n\\\"impressions_daily\\\":{\\n\\\"livesite_widget\\\":43,\\n\\\"livesite\\\":13,\\n\\\"day\\\":\\\"2014-04-12\\\",\\n\\\"business_nickname\\\":\\\"righttax\\\",\\n\\\"business_id\\\":\\\"3e4ada55\\\",\\n\\\"tags\\\":\\\"mytag\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Return Codes (identical for all reports)\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Parameter\",\n \"h-1\": \"Description\",\n \"0-0\": \"201 OK\",\n \"0-1\": \"The query was processed correctly. Return Value: [engagements]\",\n \"1-0\": \"401 Unauthorized\",\n \"1-1\": \"Failed authenticating with the token. See content for more information\",\n \"2-0\": \"422 Unprocessable Entity\",\n \"2-1\": \"Bad parameter(s). See content for more information.\"\n },\n \"cols\": 2,\n \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"Business Info\"\n}\n[/block]\nQuery the one business basic information. \n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"GET https://api.vcita.com/v1/partners/reports/business?email=user@provider.com\",\n \"language\": \"http\"\n }\n ]\n}\n[/block]\nThe response will include the following fields:\n[block:parameters]\n{\n \"data\": {\n \"2-0\": \"email\",\n \"h-0\": \"Field\",\n \"h-1\": \"Description\",\n \"2-1\": \"Business main email adress\",\n \"0-0\": \"first_name\",\n \"0-1\": \"The business owner first name\",\n \"1-0\": \"last_name\",\n \"1-1\": \"The business owner last name\",\n \"3-0\": \"business_name\",\n \"3-1\": \"Business name\",\n \"4-0\": \"business_phone\",\n \"4-1\": \"Business main phone number\",\n \"5-0\": \"business_address\",\n \"5-1\": \"Business main address\",\n \"6-0\": \"business_description\",\n \"6-1\": \"free text description of the business\",\n \"7-0\": \"hide_address\",\n \"7-1\": \"Whether or not the business owner chose to hide the business address\",\n \"8-0\": \"login_token\",\n \"8-1\": \"a token that can be used to login as the business owner\"\n },\n \"cols\": 2,\n \"rows\": 9\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"first_name\\\": \\\"John\\\",\\n \\\"last_name\\\": \\\"Doe\\\",\\n \\\"email\\\": \\\"user@provider.com\\\",\\n \\\"business_name\\\": \\\"Test Business\\\",\\n \\\"business_phone\\\": \\\"(123) 456-7890\\\",\\n \\\"business_address\\\": \\\"1 Fox st. New-York, NY 42101 \\\",\\n \\\"business_description\\\": \\\"My full business descriptions\\\",\\n \\\"hide_address\\\": false,\\n \\\"login_token\\\": \\\"dfsdfsdfsdfsdffdffff\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]","excerpt":"","slug":"reporting","type":"basic","title":"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. [block:api-header] { "type": "basic", "title": "Authentication" } [/block] 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: [block:code] { "codes": [ { "code": "curl https://api.vcita.com/v1/partners/reports/impressions -H Authorization: Token token=\"aaaabbbbccccddddeeeeffff11112222\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Engagements Report" } [/block] 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: [block:code] { "codes": [ { "code": "GET https://api.vcita.com/v1/partners/reports/engagements?fromDate=2014-04-12&toDate=2014-04-13", "language": "http" } ] } [/block] The engagement object will include the following fields: [block:parameters] { "data": { "h-0": "field", "h-1": "description", "0-0": "created_at", "0-1": "The creation time of the conversation", "1-0": "business_responded", "1-1": "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.", "2-0": "engagement_id", "2-1": "An internal vCita ID of the engagement", "3-0": "lead_type", "3-1": "The type of the initial message that started this conversation. e.g. \"appointment\", \"payment\", \"message\", \"document\"", "4-0": "business_id", "4-1": "An internal vCita ID of the business account", "6-0": "source_type", "6-1": "The source type of the engagement. indicates how the engagement started. (e.g. contact_form, livesite_widget etc)", "7-0": "source", "7-1": "If relevant, the URL the client contacted the business from.", "8-0": "tags", "8-1": "The tag (if exists) that was assigned by the directory to the business account.", "9-0": "title", "9-1": "The engagement title", "10-0": "updated_at", "10-1": "The last time the business or a client responded on this engagement", "5-0": "business_nickname", "5-1": "The vCita nickname of the business account", "11-0": "client_first_name", "11-1": "The first name of the client", "12-0": "client_last_name", "12-1": "The last name of the client", "13-0": "client_id", "13-1": "The vCita client unique id" }, "cols": 2, "rows": 14 } [/block] An example for an engagement object: [block:code] { "codes": [ { "code": "\"engagement\":{\n\"created_at\":\"2014-01-16T09:42:52+02:00\",\n\"business_responded\":0,\n\"id\":\"gxuw6fjw0ojxqunn\",\n\"lead_type\":\"Expert\",\n\"business_nickname\":\"righttax\",\n\"business_id\":\"3e4ada55\",\n\"source\":\"http://righttax.com/\",\n\"source_type\":\"contact_form\",\n\"tags\":\"mytag\",\n\"title\":\"Contact Request - please call me back\",\n\"updated_at\":\"2014-04-12T09:29:43+03:00\",\n\"client_first_name\":\"John\",\n\"client_last_name\":\"Doe\",\n\"client_id\":\"dfww6fjw0ojxsfnn\"\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Widget Impressions Report" } [/block] 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: [block:code] { "codes": [ { "code": "GET https://api.vcita.com/v1/partners/reports/impressions?fromDate=2014-04-12&toDate=2014-04-13", "language": "http" } ] } [/block] The impressions_daily object will include the following fields: [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "livesite_widget", "0-1": "Count of daily impressions for livesite_widget", "1-0": "livesite", "1-1": "Count of Livesite portal pages impressions", "2-0": "day", "2-1": "The day this impressions count relates to", "3-0": "business_id", "3-1": "The internal vCita ID of the business account this impressions count relates to", "4-0": "business_nickname", "4-1": "The vCita nickname of the business account this impressions count relates to", "5-0": "tags", "5-1": "The tag (if exists) that was assigned by the directory to the business this impressions count relates to." }, "cols": 2, "rows": 6 } [/block] An example for an impressions_daily object: [block:code] { "codes": [ { "code": "{\n\"impressions_daily\":{\n\"livesite_widget\":43,\n\"livesite\":13,\n\"day\":\"2014-04-12\",\n\"business_nickname\":\"righttax\",\n\"business_id\":\"3e4ada55\",\n\"tags\":\"mytag\"\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Return Codes (identical for all reports)" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "201 OK", "0-1": "The query was processed correctly. Return Value: [engagements]", "1-0": "401 Unauthorized", "1-1": "Failed authenticating with the token. See content for more information", "2-0": "422 Unprocessable Entity", "2-1": "Bad parameter(s). See content for more information." }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "title": "Business Info" } [/block] Query the one business basic information. [block:code] { "codes": [ { "code": "GET https://api.vcita.com/v1/partners/reports/business?email=user@provider.com", "language": "http" } ] } [/block] The response will include the following fields: [block:parameters] { "data": { "2-0": "email", "h-0": "Field", "h-1": "Description", "2-1": "Business main email adress", "0-0": "first_name", "0-1": "The business owner first name", "1-0": "last_name", "1-1": "The business owner last name", "3-0": "business_name", "3-1": "Business name", "4-0": "business_phone", "4-1": "Business main phone number", "5-0": "business_address", "5-1": "Business main address", "6-0": "business_description", "6-1": "free text description of the business", "7-0": "hide_address", "7-1": "Whether or not the business owner chose to hide the business address", "8-0": "login_token", "8-1": "a token that can be used to login as the business owner" }, "cols": 2, "rows": 9 } [/block] [block:code] { "codes": [ { "code": "{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"user@provider.com\",\n \"business_name\": \"Test Business\",\n \"business_phone\": \"(123) 456-7890\",\n \"business_address\": \"1 Fox st. New-York, NY 42101 \",\n \"business_description\": \"My full business descriptions\",\n \"hide_address\": false,\n \"login_token\": \"dfsdfsdfsdfsdffdffff\"\n}", "language": "json" } ] } [/block]

vCita

Widgets and Website Integration

REST API

Partners API