Retrieve all Contact List Details

Retrieve Contact List

Base URL

https://apimobile.callproof.com

Endpoint

/api/contact-list

Purpose

Returns a paginated list of contacts (accounts) available to the authenticated user. Supports filtering by search text, contact type, labels, location, company attributes, custom fields, and assignment, and can sort results by proximity, recency of contact, or company name. Each contact includes address, phone, distance, last contacted information, sales representatives, and related display details for use in the contact list experience.

HTTP Method

POST

Headers

Header	Required	Description
Authorization	Yes	Bearer access token

Security

• Yes – Requires Bearer Token authentication.

Parameters

Path Parameters

None.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for paginated results

Request Body

Parameter	Type	Required	Description
contact_id	integer / string	No	Specific contact ID, or multiple IDs separated by commas, to limit results to those contacts
latitude	string	No	User’s current latitude used to calculate distance to contacts. If omitted, the user’s saved location or last login location may be used
longitude	string	No	User’s current longitude used to calculate distance to contacts. If omitted, the user’s saved location or last login location may be used
parent_company	string	No	Filter by parent company / title text
annual_sales	string	No	Filter by annual sales range
employee_count	string	No	Filter by employee count range
county	string	No	Filter by county
label	string	No	Filter by label IDs (comma-separated)
search	string	No	Search keyword. Used together with select_search_fields
contact_type	string	No	Filter by contact type IDs (comma-separated)
select_search_fields	string	No	Comma-separated list of search field IDs that define which contact attributes are searched. Supported values: 1 = Company Name, 2 = First Name, 3 = Last Name, 4 = Street, 5 = City, 6 = State, 7 = Zip Code, 8 = Email, 9 = Phone, 10 = Account, 11 = Parent Company, 12 = Business Type, 13 = County, 14 = Country, 15 = Region
sort_contacts	string / integer	No	Sort order: 0 = Closest to me, 1 = Farthest away, 2 = Need to contact, 3 = Recently contacted, 4 = Company A–Z, 5 = Company Z–A
custom_field_params	string	No	Custom field filter criteria
only_my_assigned_contact	string	No	When set to 1, returns only contacts assigned to the authenticated user
last_contacted	integer	No	When set to 1, filters contacts by last contacted date using begin_date and end_date
begin_date	string	No	Start date for last-contacted filtering (format: YYYY-MM-DD). Used when last_contacted is 1
end_date	string	No	End date for last-contacted filtering (format: YYYY-MM-DD). Used when last_contacted is 1
is_map_screen	integer	No	When set to 1, adjusts list behavior for map-screen usage

cURL Example for Android

curl --location 'https://apimobile.callproof.com/api/contact-list' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'search=YOUR_SEARCH_TEXT' \
--form 'select_search_fields=1' \
--form 'sort_contacts=0'

cURL Example for iOS

curl --location 'https://apimobile.callproof.com/api/contact-list' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'search=YOUR_SEARCH_TEXT' \
--form 'select_search_fields=1' \
--form 'sort_contacts=0'

Successful Response (200)

Indicates that the contact list was retrieved successfully. The response includes contact records for the current page plus pagination metadata.

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	array	List of contacts for the current page
data[].contact_id	integer	Unique contact identifier
data[].company_name	string	Company / account name
data[].latitude	string	Contact latitude
data[].longitude	string	Contact longitude
data[].address1	string	Primary street address
data[].address2	string	Secondary street address
data[].city	string	City
data[].state	string	State
data[].country	string	Country
data[].zip	string	Postal / ZIP code
data[].message_count	integer	Message count associated with the contact
data[].missedcall_count	integer	Missed call count associated with the contact
data[].phone	string	Primary phone number
data[].phone_id	string	Identifier of the primary phone record
data[].distance	string	Distance from the user’s location (for example, miles), when available
data[].last_contacted	string	Date/time the contact was last contacted, or "Never"
data[].sales_reps	string	Assigned sales representative name(s)
data[].people	string	Associated people / contact persons
data[].ismultiplephonenumber	boolean	Whether the contact has multiple phone numbers
data[].account_id	string	Account identifier / account value
data[].contact_image	string	Image URL for the contact or contact type
data[].is_pinned	boolean	Whether the contact is pinned
data[].position	string	Display / pin position
data[].is_google_place	boolean	Whether the contact originated from a Google Place
firstItemOnPage	integer	Index of the first item on the current page
hasNextPage	boolean	Whether another page of results is available
next_page_url	string	URL for the next page, when available
prev_page_url	string	URL for the previous page, when available
first_page_url	string	URL for the first page
last_page_url	string	URL for the last page
hasPreviousPage	boolean	Whether a previous page exists
isFirstPage	boolean	Whether the current page is the first page
isLastPage	boolean	Whether the current page is the last page
lastItemOnPage	integer	Index of the last item on the current page
pageCount	integer	Total number of pages
pageNumber	integer	Current page number
pageSize	integer	Number of items per page
totalItemCount	integer	Total number of matching contacts
uri	string	Requested resource URI

Error Responses

Status Code	Meaning
400	Bad Request – the contact list could not be retrieved successfully
401	Unauthorized – missing, invalid, or expired Bearer token

• 400 – The service encountered an error while retrieving or filtering the contact list.
• 401 – Authentication failed or the access token is missing/expired.