Difference between revisions of "API:Contact Phones:Updated"

From docs
Jump to: navigation, search
(Created page with " == Updated Contact Phones == '''URL:''' <nowiki>https://app.callproof.com/api/contact_phones/updated/</nowiki> '''Method:''' GET '''Required Fields:''' * '''''key''''' - ...")
 
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  
−
== Updated Contact Phones ==
+
== [[API]] &#187; Get Contact Phones Updated ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact_phones/updated/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' GET
+
=== Endpoint ===
 +
/api/contact_phones/updated/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Retrieves contact phone numbers that were updated within a specified date range for your CallProof company. Supports pagination so large volumes of phone-number changes can be synced in batches. Typically used to keep external systems in sync with phone profile updates.
  
−
* '''''key''''' - API Key
+
=== HTTP Method ===
−
* '''''secret''''' - API Key Secret
+
GET
−
* '''''after''''' - Date/Time Contact Phones were updated after (e.g. '2014-08-10 12:34:56')
 
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
No required headers.
  
−
* '''''before''''' - Date/Time Contact Phones were updated after (e.g. '2014-08-10 12:34:56')
+
{| class="wikitable"
−
* '''''offset''''' - Only 10 Contact Phones are returned per request, this field must be used to pull additional results when more are available
+
! Header !! Required !! Description
 +
|-
 +
| — || — || No headers are required for this endpoint. Authentication is provided via query parameters.
 +
|}
  
−
'''Data Returned:'''
+
=== Security ===
 +
* '''Yes''' – Requires a valid API key and secret with permission to read contact phones.
  
−
* '''''results''''' - Array of Contact Phones
+
=== Parameters ===
−
* '''''more''''' - This field will be set if additional results are available
+
 
−
* '''''offset''''' - Current offset of the request
+
==== Query Parameters ====
−
* '''''errors''''' - Array of errors produced by the request
+
{| class="wikitable"
−
* '''''code''''' - HTTP request status
+
! 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.
 +
|-
 +
| after || datetime string || Yes || Return only phone numbers updated on or after this date/time. Invalid or missing values cause a validation error.
 +
|-
 +
| before || datetime string || No || Return only phone numbers updated on or before this date/time. If omitted, no upper date limit is applied.
 +
|-
 +
| offset || integer || No || Starting position for paginated results. Defaults to <code>0</code> if omitted or invalid.
 +
|}
 +
 
 +
==== Path Parameters ====
 +
None.
 +
 
 +
==== Request Body ====
 +
None.
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X GET "https://app.callproof.com/api/contact_phones/updated/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&after=2024-01-01"
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Returns a paginated list of contact phone numbers updated within the requested date range. Up to 100 phone records are returned per request. If more matching records exist, <code>more</code> is set to <code>1</code> so the caller can request the next page using <code>offset</code>.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || array || List of contact phone objects (maximum 100 per response).
 +
|-
 +
| results[].id || integer || Unique identifier for the phone number.
 +
|-
 +
| results[].last_contacted || string || Date and time this phone was last contacted (<code>YYYY-MM-DD HH:MM:SS</code>), or empty if none.
 +
|-
 +
| results[].unknown || integer || <code>1</code> if marked unknown; otherwise <code>0</code>.
 +
|-
 +
| results[].do_not_call || integer || <code>1</code> if do-not-call is enabled; otherwise <code>0</code>.
 +
|-
 +
| results[].contact_id || integer || Associated contact identifier.
 +
|-
 +
| results[].contact || string || Contact display name.
 +
|-
 +
| results[].phone_type || string || Phone type name (for example, Mobile or Office).
 +
|-
 +
| results[].phone_number || string || Phone number.
 +
|-
 +
| results[].ext || string || Phone extension, if any.
 +
|-
 +
| results[].activated || string || Activation date/time, if set.
 +
|-
 +
| results[].eligible || string || Eligibility date/time, if set.
 +
|-
 +
| results[].call_result || string || Last call result, if any.
 +
|-
 +
| results[].hidden || integer || <code>1</code> if the phone is hidden; otherwise <code>0</code>.
 +
|-
 +
| results[].dealer_store || string || Associated dealer/store name, if any.
 +
|-
 +
| results[].model || string || Model value, if any.
 +
|-
 +
| results[].updated || string || Date and time the phone record was last updated (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| results[].created || string || Date and time the phone record was created (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| more || integer || <code>1</code> if additional matching phone records remain; <code>0</code> if this is the last page.
 +
|-
 +
| offset || integer || Offset value used for this request.
 +
|-
 +
| errors || array || Empty list when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "results": [
 +
    {
 +
      "id": 1001,
 +
      "last_contacted": "2024-06-15 14:30:00",
 +
      "unknown": 0,
 +
      "do_not_call": 0,
 +
      "contact_id": 789,
 +
      "contact": "John Doe",
 +
      "phone_type": "Mobile",
 +
      "phone_number": "5551234567",
 +
      "ext": "",
 +
      "activated": "",
 +
      "eligible": "",
 +
      "call_result": "",
 +
      "hidden": 0,
 +
      "dealer_store": "",
 +
      "model": "",
 +
      "updated": "2024-06-15 14:30:00",
 +
      "created": "2024-01-10 09:00:00"
 +
    }
 +
  ],
 +
  "more": 0,
 +
  "offset": 0,
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* Results are filtered by the phone record’s last-updated timestamp, not by creation date.
 +
* <code>after</code> is required and must be a valid date/time.
 +
* <code>before</code> is optional and can be used to limit the upper end of the date range.
 +
* Results are ordered by most recently updated first.
 +
* Up to 100 records are returned per page. Use <code>offset</code> with <code>more</code> to page through larger result sets.
 +
* Only phone numbers belonging to your company are returned.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 400 || Bad Request – The required <code>after</code> parameter is missing or cannot be interpreted as a valid date/time.
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to read contact phones.
 +
|-
 +
| 405 || Method Not Allowed – A method other than GET was used.
 +
|-
 +
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
 +
|}
 +
 
 +
'''400 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid 'after' field"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
'''401 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid API Key"],
 +
  "code": 401
 +
}
 +
</pre>
 +
 
 +
'''405 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Method not allowed"],
 +
  "code": 405
 +
}
 +
</pre>

Latest revision as of 11:34, 17 July 2026

API » Get Contact Phones Updated

Base URL

https://app.callproof.com

Endpoint

/api/contact_phones/updated/

Purpose

Retrieves contact phone numbers that were updated within a specified date range for your CallProof company. Supports pagination so large volumes of phone-number changes can be synced in batches. Typically used to keep external systems in sync with phone profile updates.

HTTP Method

GET

Headers

No required headers.

Header Required Description
— — No headers are required for this endpoint. Authentication is provided via query parameters.

Security

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

Parameters

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.
after datetime string Yes Return only phone numbers updated on or after this date/time. Invalid or missing values cause a validation error.
before datetime string No Return only phone numbers updated on or before this date/time. If omitted, no upper date limit is applied.
offset integer No Starting position for paginated results. Defaults to 0 if omitted or invalid.

Path Parameters

None.

Request Body

None.

cURL Example

curl -X GET "https://app.callproof.com/api/contact_phones/updated/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&after=2024-01-01"

Successful Response (200)

Returns a paginated list of contact phone numbers updated within the requested date range. Up to 100 phone records are returned per request. If more matching records exist, more is set to 1 so the caller can request the next page using offset.

Field Type Description
results array List of contact phone objects (maximum 100 per response).
results[].id integer Unique identifier for the phone number.
results[].last_contacted string Date and time this phone was last contacted (YYYY-MM-DD HH:MM:SS), or empty if none.
results[].unknown integer 1 if marked unknown; otherwise 0.
results[].do_not_call integer 1 if do-not-call is enabled; otherwise 0.
results[].contact_id integer Associated contact identifier.
results[].contact string Contact display name.
results[].phone_type string Phone type name (for example, Mobile or Office).
results[].phone_number string Phone number.
results[].ext string Phone extension, if any.
results[].activated string Activation date/time, if set.
results[].eligible string Eligibility date/time, if set.
results[].call_result string Last call result, if any.
results[].hidden integer 1 if the phone is hidden; otherwise 0.
results[].dealer_store string Associated dealer/store name, if any.
results[].model string Model value, if any.
results[].updated string Date and time the phone record was last updated (YYYY-MM-DD HH:MM:SS).
results[].created string Date and time the phone record was created (YYYY-MM-DD HH:MM:SS).
more integer 1 if additional matching phone records remain; 0 if this is the last page.
offset integer Offset value used for this request.
errors array Empty list when the request succeeds.
code integer HTTP-style status value; 200 on success.

Example response: 

{
  "results": [
    {
      "id": 1001,
      "last_contacted": "2024-06-15 14:30:00",
      "unknown": 0,
      "do_not_call": 0,
      "contact_id": 789,
      "contact": "John Doe",
      "phone_type": "Mobile",
      "phone_number": "5551234567",
      "ext": "",
      "activated": "",
      "eligible": "",
      "call_result": "",
      "hidden": 0,
      "dealer_store": "",
      "model": "",
      "updated": "2024-06-15 14:30:00",
      "created": "2024-01-10 09:00:00"
    }
  ],
  "more": 0,
  "offset": 0,
  "errors": [],
  "code": 200
}

Notes

  • Results are filtered by the phone record’s last-updated timestamp, not by creation date.
  • after is required and must be a valid date/time.
  • before is optional and can be used to limit the upper end of the date range.
  • Results are ordered by most recently updated first.
  • Up to 100 records are returned per page. Use offset with more to page through larger result sets.
  • Only phone numbers belonging to your company are returned.

Error Responses

Status Code Meaning
400 Bad Request – The required after parameter is missing or cannot be interpreted as a valid date/time.
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to read contact phones.
405 Method Not Allowed – A method other than GET was used.
500 Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

400 response body example: 

{
  "results": [],
  "errors": ["Invalid 'after' field"],
  "code": 400
}

401 response body example: 

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

405 response body example: 

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}
Retrieved from "http://docs.callproof.com/index.php?title=API:Contact_Phones:Updated&oldid=2244"