Ashley DeBon: Created page with "== Update Dashboard Widgets == === Base URL === https://apimobile.callproof.com === Endpoint === /api/v1/widgets === Purpose === Updates the authenticated user's dashboard..."

2026-07-15T11:54:51Z

Created page with "== Update Dashboard Widgets == === Base URL === https://apimobile.callproof.com === Endpoint === /api/v1/widgets === Purpose === Updates the authenticated user's dashboard..."

New page

== Update Dashboard Widgets ==

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

=== Endpoint ===
/api/v1/widgets

=== Purpose ===
Updates the authenticated user's dashboard widget preferences.

The API allows a user to:

* Enable or disable dashboard widgets.
* Change the display order of enabled widgets.
* Control the Recommended Follow Up widget.
* Control the Tasks widget.
* Control the Business Card and Business Card Image widgets.

=== HTTP Method ===
PUT

=== 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 authenticated user and associated company account must be active.
* If two-factor authentication is enabled, verification must be completed for the registered device.

=== Parameters ===
==== Request Body Fields ====
{| class="wikitable"
! Parameter !! Type !! Required !! Description
|-
| recommended_followup || integer || Yes || Controls the Recommended Follow Up widget. Use <code>1</code> to enable it or <code>0</code> to disable it.
|-
| task_widget || integer || No || Controls the Tasks widget. Use <code>1</code> to enable it or <code>0</code> to disable it. Defaults to <code>0</code>.
|-
| business_card || integer || No || Controls the Business Card widget. Use <code>1</code> to enable it or <code>0</code> to disable it. Defaults to <code>0</code>.
|-
| business_card_thumbnail || integer || No || Controls the Business Card Image widget. Use <code>1</code> to enable it or <code>0</code> to disable it. Defaults to <code>0</code>.
|-
| widgets || JSON-encoded string || Yes || An array containing the widgets that should be enabled, together with their display positions.
|-
| widgets_available || JSON-encoded string || Yes || An array containing the widgets that should remain disabled and available for selection.
|}

==== Enabled Widget Entry Fields ====
Each object within <code>widgets</code> contains:

{| class="wikitable"
! Field !! Type !! Required !! Description
|-
| id || integer || Yes || The widget type's unique identifier.
|-
| position || integer || Yes || The widget's desired display position.
|}

==== Available Widget Entry Fields ====
Each object within <code>widgets_available</code> contains:

{| class="wikitable"
! Field !! Type !! Required !! Description
|-
| id || integer || Yes || The unique identifier of a widget that should be disabled.
|}

==== Widget Configuration Rules ====
* <code>widgets</code> and <code>widgets_available</code> cannot both be empty.
* A widget must not appear in both collections.
* Every enabled widget must have a corresponding position.
* The number of enabled widget IDs must match the number of supplied positions.
* Widget positions are applied in the same order as entries in the <code>widgets</code> array.

=== Successful Response (200) ===
Confirms that the authenticated user's enabled widgets, disabled widgets, display order, and dedicated widget settings were updated successfully.

{| class="wikitable"
! Response Field !! Type !! Description
|-
| clientStatusCode || integer || Business-level response status. A successful update returns <code>200</code>.
|-
| user_id || integer || The authenticated user's unique identifier.
|-
| company_id || integer || The company associated with the authenticated user.
|-
| message || string || Confirmation message. The successful value is <code>widgets updated successfully</code>.
|-
| uri || string || The URL of the request.
|}

=== Error Responses ===
{| class="wikitable"
! HTTP Status Code !! Client Status Code !! Meaning
|-
| 200 || 401 || Both <code>widgets</code> and <code>widgets_available</code> are empty.
|-
| 200 || 401 || A required enabled or available widget collection is missing.
|-
| 200 || 401 || The number of enabled widgets does not match the number of supplied positions.
|-
| 200 || 401 || The same widget appears in both enabled and available collections.
|-
| 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 access token has expired.
|-
| 401 || 401 || The authenticated user or company account is disabled.
|-
| 401 || 401 || A required client application update must be installed.
|}

==== 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 widget update failure.
|-
| uri || string || The URL of the request.
|}

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

Dashboard Widgets Update Details - Revision history

Ashley DeBon: Created page with "== Update Dashboard Widgets == === Base URL === https://apimobile.callproof.com === Endpoint === /api/v1/widgets === Purpose === Updates the authenticated user's dashboard..."