API:Contacts:Find

API » Find Contacts

Base URL

https://app.callproof.com

Endpoint

/api/contacts/find/

Purpose

Searches contacts belonging to your CallProof company using optional criteria such as name, company, telephone number, email address, location, contact type, assignment status, or account identifier. Results are paginated for efficient retrieval.

HTTP Method

GET

Headers

No headers are required.

Security

• Yes – Requires a valid API key and secret with permission to read contacts.

Parameters

Path Parameters

None.

Query Parameters

Parameter	Type	Required	Description
key	string	Yes	Public API key assigned to your CallProof account.
secret	string	Yes	Private API secret paired with the API key.
query	string	No	Search text matched against company name, telephone number, first name, last name, email address, and street address.
contact_type	string	No	Exact contact type name used to filter results.
assigned	boolean	No	Filters contacts by assignment status. Use t for assigned or f for unassigned.
city	string	No	City used to filter contacts.
state	string	No	State or province abbreviation used to filter contacts.
zip	string	No	Full or partial postal/ZIP code.
account	string	No	Exact account identifier used to filter contacts.
offset	integer	No	Starting position for paginated results. Defaults to 0 if omitted or invalid.

Request Body

None.

cURL Example

curl -X GET "https://app.callproof.com/api/contacts/find/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"

Example with search criteria:

curl -X GET "https://app.callproof.com/api/contacts/find/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&query=Acme&city=Austin&state=TX&assigned=t"

Successful Response (200)

Returns up to 100 contacts matching the supplied criteria. If no search criteria are supplied, contacts are returned without additional filtering. When more matches are available, more is set to 1 and the next page can be requested using offset.

Field	Type	Description
results	array	Contacts matching the supplied search criteria.
results[].id	integer	Unique contact identifier.
results[].company	string	Name of the company associated with the contact.
results[].contact_phones	array	Telephone numbers associated with the contact.
results[].created_by	string	Name of the person who created the contact.
results[].created_by_id	integer	User identifier of the person who created the contact.
results[].created_by_email	string	Email address of the person who created the contact.
results[].contact_type	string	Contact type.
results[].title	string	Contact title.
results[].first_name	string	Contact first name.
results[].last_name	string	Contact last name.
results[].email	string	Contact email address.
results[].address	string	Primary street address.
results[].address2	string	Additional street address information.
results[].city	string	City.
results[].state	string	State or province.
results[].zip	string	Postal/ZIP code.
results[].country	string	Country.
results[].website	string	Website address.
results[].latitude	string	Geographic latitude.
results[].longitude	string	Geographic longitude.
results[].last_contacted	string	Date and time the contact was last contacted.
results[].default_phone	object	Default telephone number details.
results[].account	string	Account identifier.
results[].invoice	string	Invoice-related value, when available.
results[].unknown	integer	1 when marked as unknown; otherwise 0.
results[].assigned	integer	1 when assigned; otherwise 0.
results[].do_not_sms	integer	1 when text messaging is disabled; otherwise 0.
results[].updated	string	Date and time the contact was last updated.
results[].created	string	Date and time the contact was created.
results[].custom_fields	array	Custom field values associated with the contact.
results[].reps	array	Sales representatives assigned to the contact.
more	integer	1 when additional results are available; otherwise 0.
offset	integer	Starting position used for this result page.
errors	array	Empty list when the request succeeds.
code	integer	Response status value; 200 on success.

Contact Phone Fields

Field	Type	Description
id	integer	Unique telephone number identifier.
last_contacted	string	Date and time this number was last contacted.
unknown	integer	1 when marked as unknown; otherwise 0.
do_not_call	integer	1 when calling is prohibited; otherwise 0.
contact_id	integer	Associated contact identifier.
contact	string	Associated contact name.
phone_type	string	Telephone number type.
phone_number	string	Telephone number.
ext	string	Telephone extension.
activated	string	Activation date and time, when available.
eligible	string	Eligibility date and time, when available.
call_result	string	Most recent call result, when available.
hidden	integer	1 when hidden; otherwise 0.
dealer_store	string	Associated dealer or store, when available.
model	string	Associated model value, when available.
updated	string	Date and time the telephone record was last updated.
created	string	Date and time the telephone record was created.

Custom Field Fields

Field	Type	Description
id	integer	Custom field identifier.
name	string	Custom field name.
value	variable	Custom field value.
value_id	variable	Selected value identifier, when applicable.

Assigned Rep Fields

Field	Type	Description
id	integer	Rep profile identifier.
email	string	Rep email address.
user_id	integer	Rep user identifier.
fullname	string	Rep full name.
title	string	Rep job title.
updated	string	Date and time the rep profile was last updated.

Example response:

{
  "results": [
    {
      "id": 789,
      "company": "Acme Corp",
      "contact_phones": [],
      "created_by": "Jane Smith",
      "created_by_id": 456,
      "created_by_email": "rep@example.com",
      "contact_type": "Prospect",
      "title": "Manager",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acme.com",
      "address": "123 Main St",
      "address2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "78701",
      "country": "United States",
      "website": "https://acme.com",
      "latitude": "30.2672",
      "longitude": "-97.7431",
      "last_contacted": "2024-06-15 14:30:00",
      "default_phone": {},
      "account": "ACC-100",
      "invoice": "",
      "unknown": 0,
      "assigned": 1,
      "do_not_sms": 0,
      "updated": "2024-06-15 14:30:00",
      "created": "2024-01-10 09:00:00",
      "custom_fields": [],
      "reps": []
    }
  ],
  "more": 0,
  "offset": 0,
  "errors": [],
  "code": 200
}

Error Responses

Status Code	Meaning
401	Unauthorized – The API credentials are missing, invalid, inactive, associated with a disabled account, or lack permission to read contacts.
405	Method Not Allowed – A method other than GET was used.
500	Internal Server Error – An unexpected problem prevented the search from being completed. Not specified in Swagger.

401 response example:

{
  "results": [],
  "errors": ["Invalid API Key"],
  "code": 401
}

405 response example:

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}