Ashley DeBon: Created page with "== Dashboard Details == === Base URL === https://apimobile.callproof.com === Endpoint === /api/v1/dashboard-details === Purpose === Returns a personalized overview of the a..."

2026-07-15T10:52:18Z

Created page with "== Dashboard Details == === Base URL === https://apimobile.callproof.com === Endpoint === /api/v1/dashboard-details === Purpose === Returns a personalized overview of the a..."

New page

== Dashboard Details ==

=== Base URL ===
https://apimobile.callproof.com

=== Endpoint ===
/api/v1/dashboard-details

=== Purpose ===
Returns a personalized overview of the authenticated user's CallProof activity.

The response includes:

* Call, appointment, and email totals for today, yesterday, the current month, and the current year.
* The user's enabled dashboard widgets and their display order.
* Current and previous period comparisons.
* Percentage changes between periods.
* Five-point chart data for calls, appointments, and emails.
* Up to ten recent activity records when the Recent Events widget is enabled.

All date calculations use the authenticated user's configured time zone.

=== HTTP Method ===
POST

=== Headers ===
{| class="wikitable"
! Header !! Required !! Description
|-
| Authorization || Yes || Bearer access token.
|-
| Content-Type || Yes || <code>application/x-www-form-urlencoded</code> or <code>application/json</code>.
|}

=== Security ===
* '''Yes''' – Requires Bearer Token authentication.
* The access token must be active and unexpired.
* The user and associated company account must be active.
* If two-factor authentication is enabled, the user must have completed verification for the registered device.

=== Parameters ===
==== Request Body Fields ====
{| class="wikitable"
! Parameter !! Type !! Required !! Description
|-
| timeframe || string || No || Determines the reporting period used by dashboard widgets. Defaults to <code>1w</code>.
|}

==== Supported Timeframe Values ====
{| class="wikitable"
! Value !! Meaning
|-
| 1w || The most recent seven-day period.
|-
| 4w || The most recent 28-day period.
|-
| 1y || The most recent 365-day period.
|-
| mtd || Month to date.
|-
| qtd || Quarter to date.
|-
| ytd || Year to date.
|-
| all || All activity since the user account was created.
|}

The selected period is compared with the immediately preceding period of the same duration.

=== Successful Response (200) ===
Returns the authenticated user's dashboard activity summary, widget order, enabled widgets, period comparisons, and chart data.

==== Top-Level Response Fields ====
{| class="wikitable"
! Response Field !! Type !! Description
|-
| clientStatusCode || integer || Business-level response status. A successful request returns <code>200</code>.
|-
| user_id || integer || The authenticated user's unique identifier.
|-
| company_id || integer || The company associated with the authenticated user.
|-
| data || object || Contains dashboard events, widget ordering, and widget details.
|-
| uri || string || The URL of the dashboard request.
|}

==== Dashboard Data Fields ====
{| class="wikitable"
! Response Field !! Type !! Description
|-
| data.events || array || Activity totals for today, yesterday, the current month, and the current year.
|-
| data.widgets_order || object || Contains the ordered names of the user's enabled dashboard widgets.
|-
| data.widgets_order.widgets || array of strings || Enabled widget names in their display order.
|-
| data.widgets || array || Dashboard widget content prepared for the authenticated user.
|}

==== Event Summary Fields ====
Each entry in <code>data.events</code> represents today, yesterday, the current month, or the current year.

{| class="wikitable"
! Response Field !! Type !! Description
|-
| day || string || The summary period, such as <code>Today</code>, <code>Yesterday</code>, <code>Month</code>, or <code>Year</code>.
|-
| date || string || The formatted date, month, or year represented by the summary.
|-
| call_count || integer || Total recorded calls during the summary period.
|-
| appointment_count || integer || Total appointments during the summary period.
|-
| email_count || integer || Total email activity during the summary period.
|}

==== Widget Fields ====
{| class="wikitable"
! Response Field !! Type !! Description
|-
| event || string || The widget name, such as <code>Appointments</code>, <code>Calls</code>, <code>Emails</code>, <code>Recent Events</code>, or <code>Opportunity</code>.
|-
| info || array || The information displayed by the widget. Its contents depend on the widget type.
|}

==== Appointment Widget ====
The appointment widget contains one summary titled <code>My Appointments</code>.

{| class="wikitable"
! Response Field !! Type !! Description
|-
| title || string || The appointment summary title.
|-
| progress_total_calls || integer || Total appointments in the selected current period.
|-
| progress_from_date || string || Beginning of the current comparison period.
|-
| progress_to_date || string || End of the current comparison period.
|-
| previous_total_calls || integer || Total appointments in the preceding comparison period.
|-
| previous_from_date || string || Beginning of the preceding comparison period.
|-
| previous_to_date || string || End of the preceding comparison period.
|-
| percentage || integer || Percentage change between the preceding and current periods.
|-
| chart_data.current_data || array of integers || Current-period activity divided into five chart intervals.
|-
| chart_data.previous_data || array of integers || Previous-period activity divided into five chart intervals.
|}

==== Call Widget ====
The call widget provides separate summaries for:

* My Outbound Phone Calls
* My Inbound Phone Calls
* All Calls

Each summary uses the following fields:

{| class="wikitable"
! Response Field !! Type !! Description
|-
| title || string || The call category represented by the summary.
|-
| progress_total_calls || integer || Total calls in the selected current period.
|-
| progress_from_date || string || Beginning of the current comparison period.
|-
| progress_to_date || string || End of the current comparison period.
|-
| previous_total_calls || integer || Total calls in the preceding comparison period.
|-
| previous_from_date || string || Beginning of the preceding comparison period.
|-
| previous_to_date || string || End of the preceding comparison period.
|-
| percentage || integer || Percentage change between the preceding and current periods.
|-
| chart_data.current_data || array of integers || Current-period calls divided into five chart intervals.
|-
| chart_data.previous_data || array of integers || Previous-period calls divided into five chart intervals.
|}

==== Email Widget ====
The email widget provides separate summaries for:

* My Outbound Emails
* My Inbound Emails
* All Email

Each summary uses the following fields:

{| class="wikitable"
! Response Field !! Type !! Description
|-
| title || string || The email category represented by the summary.
|-
| progress_total_calls || integer || Total emails in the selected current period.
|-
| progress_from_date || string || Beginning of the current comparison period.
|-
| progress_to_date || string || End of the current comparison period.
|-
| previous_total_calls || integer || Total emails in the preceding comparison period.
|-
| previous_from_date || string || Beginning of the preceding comparison period.
|-
| previous_to_date || string || End of the preceding comparison period.
|-
| percentage || integer || Percentage change between the preceding and current periods.
|-
| chart_data.current_data || array of integers || Current-period email activity divided into five chart intervals.
|-
| chart_data.previous_data || array of integers || Previous-period email activity divided into five chart intervals.
|}

==== Recent Events Widget ====
Returns up to ten recent activity records for the authenticated user.

The fields within each activity record vary according to the activity type.

==== Opportunity Widget ====
The Opportunity widget is included when enabled, but its <code>info</code> field is currently returned as an empty array.

=== Error Responses ===
{| class="wikitable"
! HTTP Status Code !! Client Status Code !! Meaning
|-
| 200 || 401 || The supplied <code>timeframe</code> value is not supported.
|-
| 200 || 401 || Two-factor authentication is required but has not been completed for the registered device.
|-
| 401 || 401 || The Bearer token is missing or invalid.
|-
| 401 || 401 || The authenticated user or company account is disabled.
|-
| 401 || 401 || The client application version must be updated before continuing.
|-
| 401 || 401 || The access token has expired.
|}

==== Error Response Fields ====
{| class="wikitable"
! Response Field !! Type !! Description
|-
| clientStatusCode || integer || The business-level error status.
|-
| error.code || integer || The business error code.
|-
| error.message || string || A plain-language explanation of the dashboard request failure.
|-
| uri || string || The URL of the dashboard request.
|}

==== Common Error Codes ====
{| class="wikitable"
! Error Code !! Meaning
|-
| 1500 || Authentication, authorization, two-factor verification, or request validation failed.
|-
| 1800 || The user or company account is disabled.
|-
| 8000 || The access token has expired.
|-
| 9000 || A required client application update is available.
|}

Dashboard Details - Revision history

Ashley DeBon: Created page with "== Dashboard Details == === Base URL === https://apimobile.callproof.com === Endpoint === /api/v1/dashboard-details === Purpose === Returns a personalized overview of the a..."