Retrieve Opportunity based on widgets filters

Mobile_API »Get Opportunities Widget (Filtered)

Base URL

https://apimobile.callproof.com

Endpoint

/api/opportunities-widget

Purpose

Retrieves opportunity widget data filtered by stage and optional owner. Returns totals (count, closing value, derived value). When a specific stage is selected, also returns up to 5 matching opportunities ordered by close date, plus whether more records remain.

HTTP Method

POST

Headers

Header	Required	Description
Authorization	Yes	Bearer access token

Security

• Yes – Requires Bearer Token authentication.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

Parameter	Type	Required	Description
stage_id	integer	No	Opportunity stage filter. Use a specific stage ID to return that stage’s opportunities (max 5). Use 0 (or omit) to calculate totals across all company stages without returning the opportunity list
user_id	integer	No	Filters opportunities to a specific owner/rep

cURL Example for Android

 curl --location 'https://apimobile.callproof.com/api/opportunities-widget' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "stage_id": 0, "user_id": "" }' 

cURL Example for iOS

 curl --location 'https://apimobile.callproof.com/api/opportunities-widget' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "stage_id": 0, "user_id": "" }' 

Successful Response (200)

Returns opportunity widget totals and, when a specific stage is selected, a limited opportunity list.

Field	Type	Description
clientStatusCode	integer	Status indicator for the client (for example, 200)
user_id	integer	Identifier of the authenticated user
company_id	integer	Identifier of the authenticated user’s company
data	object	Widget payload
uri	string	Requested resource URI

data

Field	Type	Description
opportunities	array	Opportunity records for the selected stage (included only when stage_id is a specific stage, not 0). Limited to 5 records
more_data	boolean	true when more than 5 matching opportunities exist (specific stage only)
remaining_count_of_records	integer	Count of opportunities beyond the first 5 (or 0 when none remain)
total_number_opportunities	integer	Total matching opportunity count
total_closing	number/string	Sum of opportunity values (for example, 0.00 when empty)
total_derived_values	string	Weighted total: sum of value * probability / 100, formatted to 2 decimal places

data.opportunities[]

Field	Type	Description
id	integer	Opportunity identifier
company_id	integer	Company identifier
user_id	integer	Owner/rep user identifier
contact_id	integer	Related contact identifier
opp_name	string	Opportunity name
opp_stage_id	integer	Stage identifier
stage_name	string	Stage display name
company_name	string	Company display name
opp_type_id	integer	Opportunity type identifier
probability	number	Win probability (0–100)
value	number	Opportunity value
close_date	string	Expected close date formatted as m-d-Y (empty string when not set)
notes	string	Opportunity notes
created	string/datetime	Created timestamp
updated	string/datetime	Updated timestamp

Error Responses

Status Code	Meaning
200	Validation failed – response body uses clientStatusCode 401 with the first validation error message
400	Bad Request – opportunities could not be retrieved
401	Unauthorized – missing, invalid, or expired Bearer token

• Validation (HTTP 200, clientStatusCode 401) – Invalid stage_id (must be an integer when provided).
• 400 – An error occurred while retrieving opportunities (for example, "Error while retrieving the Opportunities").
• 401 – Authentication failed or the access token is missing/expired.