Dashboard Widgets Update Details

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

Header	Required	Description
Authorization	Yes	Bearer access token.
Content-Type	Yes	application/x-www-form-urlencoded or application/json.

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

Parameter	Type	Required	Description
recommended_followup	integer	Yes	Controls the Recommended Follow Up widget. Use 1 to enable it or 0 to disable it.
task_widget	integer	No	Controls the Tasks widget. Use 1 to enable it or 0 to disable it. Defaults to 0.
business_card	integer	No	Controls the Business Card widget. Use 1 to enable it or 0 to disable it. Defaults to 0.
business_card_thumbnail	integer	No	Controls the Business Card Image widget. Use 1 to enable it or 0 to disable it. Defaults to 0.
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 widgets contains:

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 widgets_available contains:

Field	Type	Required	Description
id	integer	Yes	The unique identifier of a widget that should be disabled.

Widget Configuration Rules

• widgets and widgets_available 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 widgets array.

Successful Response (200)

Confirms that the authenticated user's enabled widgets, disabled widgets, display order, and dedicated widget settings were updated successfully.

Response Field	Type	Description
clientStatusCode	integer	Business-level response status. A successful update returns 200.
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 widgets updated successfully.
uri	string	The URL of the request.

Error Responses

HTTP Status Code	Client Status Code	Meaning
200	401	Both widgets and widgets_available 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

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

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.