Difference between revisions of "API:People:Phones:Get"

From docs
Jump to: navigation, search
 
Line 1: Line 1:
−
== [[API]] » Get Personnel Phone ==
+
== [[API]] » Get Contact Personnel Phones ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact/personnel/phones/get/<personnel_id>/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' GET
+
=== Endpoint ===
 +
/api/contact/personnel/phones/get/&lt;personnel_id&gt;/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Retrieves the phone numbers associated with a specific contact personnel record in your CallProof company. Use this to obtain phone details for an individual linked to a contact account, including type, number, extension, and related status information.
  
−
* '''''key''''' - API Key
+
=== HTTP Method ===
−
* '''''secret''''' - API Key Secret
+
GET
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
No required headers.
  
−
None
+
{| class="wikitable"
 +
! 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 contacts.
  
−
* '''''results''''' - Details of personnel's contact numbers
+
=== Parameters ===
−
* '''''errors''''' - Array of errors produced by the request
+
 
−
* '''''code''''' - HTTP request status
+
==== Path Parameters ====
 +
{| class="wikitable"
 +
! Parameter !! Type !! Required !! Description
 +
|-
 +
| personnel_id || integer || Yes || Unique identifier of the personnel record whose phone numbers should be retrieved. Must belong to your company.
 +
|}
 +
 
 +
==== Query Parameters ====
 +
{| class="wikitable"
 +
! 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.
 +
|}
 +
 
 +
==== Request Body ====
 +
None.
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X GET "https://app.callproof.com/api/contact/personnel/phones/get/55/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Returns the phone numbers linked to the specified personnel record.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || array || List of phone numbers associated with the personnel record.
 +
|-
 +
| 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 for this personnel association, 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>).
 +
|-
 +
| 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": "123",
 +
      "activated": "",
 +
      "eligible": "",
 +
      "call_result": "",
 +
      "hidden": 0,
 +
      "dealer_store": "",
 +
      "model": "",
 +
      "updated": "2024-06-15 14:30:00",
 +
      "created": "2024-01-10 09:00:00"
 +
    }
 +
  ],
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* <code>personnel_id</code> is provided in the URL path.
 +
* The personnel record must belong to your company.
 +
* If the personnel record exists but has no associated phone numbers, the response returns an empty <code>results</code> list with status <code>200</code>.
 +
* When a personnel-specific extension exists for a phone number, that extension is returned in <code>ext</code>.
 +
* This endpoint does not support pagination or date-range filtering.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 400 || Bad Request – The personnel ID is missing, invalid, or does not match a personnel record in your company.
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to read contacts.
 +
|-
 +
| 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 contact people id."],
 +
  "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 12:27, 17 July 2026

API » Get Contact Personnel Phones

Base URL

https://app.callproof.com

Endpoint

/api/contact/personnel/phones/get/<personnel_id>/

Purpose

Retrieves the phone numbers associated with a specific contact personnel record in your CallProof company. Use this to obtain phone details for an individual linked to a contact account, including type, number, extension, and related status information.

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 contacts.

Parameters

Path Parameters

Parameter Type Required Description
personnel_id integer Yes Unique identifier of the personnel record whose phone numbers should be retrieved. Must belong to your company.

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.

Request Body

None.

cURL Example

curl -X GET "https://app.callproof.com/api/contact/personnel/phones/get/55/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"

Successful Response (200)

Returns the phone numbers linked to the specified personnel record.

Field Type Description
results array List of phone numbers associated with the personnel record.
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 for this personnel association, 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).
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": "123",
      "activated": "",
      "eligible": "",
      "call_result": "",
      "hidden": 0,
      "dealer_store": "",
      "model": "",
      "updated": "2024-06-15 14:30:00",
      "created": "2024-01-10 09:00:00"
    }
  ],
  "errors": [],
  "code": 200
}

Notes

  • personnel_id is provided in the URL path.
  • The personnel record must belong to your company.
  • If the personnel record exists but has no associated phone numbers, the response returns an empty results list with status 200.
  • When a personnel-specific extension exists for a phone number, that extension is returned in ext.
  • This endpoint does not support pagination or date-range filtering.

Error Responses

Status Code Meaning
400 Bad Request – The personnel ID is missing, invalid, or does not match a personnel record in your company.
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to read contacts.
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 contact people id."],
  "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:People:Phones:Get&oldid=2294"