Difference between revisions of "API:People:Get"

From docs
Jump to: navigation, search
(→‎API » Get People)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
−
== [[API]] » Get People ==
+
== [[API]] » Get Contact Personnel ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact/personnel/get/<contact_id>/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' GET
+
=== Endpoint ===
 +
/api/contact/personnel/get/&lt;contact_id&gt;/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Retrieves the people (personnel) associated with a specific contact in your CallProof company. Use this to obtain role, name, email, title, and last-contacted details for individuals linked to a contact account.
  
−
* '''''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''''' - Contact Notes
+
=== Parameters ===
−
* '''''errors''''' - Array of errors produced by the request
+
 
−
* '''''code''''' - HTTP request status
+
==== Path Parameters ====
 +
{| class="wikitable"
 +
! Parameter !! Type !! Required !! Description
 +
|-
 +
| contact_id || integer || Yes || Unique identifier of the contact whose personnel 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/get/789/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Returns all personnel records associated with the specified contact.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || array || List of personnel associated with the contact.
 +
|-
 +
| results[].id || integer || Unique identifier for the personnel record.
 +
|-
 +
| results[].fullname || string || Full display name of the person.
 +
|-
 +
| results[].first_name || string || First name.
 +
|-
 +
| results[].last_name || string || Last name.
 +
|-
 +
| results[].title || string || Job title.
 +
|-
 +
| results[].last_contacted || string || Date and time this person was last contacted (<code>YYYY-MM-DD HH:MM:SS</code>), or empty if none.
 +
|-
 +
| results[].role || string || Role name associated with the person, or empty if none.
 +
|-
 +
| results[].email || string || Email address.
 +
|-
 +
| results[].updated || string || Date and time the personnel record was last updated (<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": 55,
 +
      "fullname": "Sarah Jones",
 +
      "first_name": "Sarah",
 +
      "last_name": "Jones",
 +
      "title": "Purchasing Manager",
 +
      "last_contacted": "2024-06-15 14:30:00",
 +
      "role": "Decision Maker",
 +
      "email": "sarah@acme.com",
 +
      "updated": "2024-06-15 14:30:00"
 +
    }
 +
  ],
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* <code>contact_id</code> is provided in the URL path.
 +
* The contact must belong to your company.
 +
* All personnel linked to the contact are returned.
 +
* If the contact exists but has no personnel, the response returns an empty <code>results</code> list with status <code>200</code>.
 +
* This endpoint does not support pagination or date-range filtering.
 +
* Phone numbers for personnel are not included in this response. Use the personnel phones endpoint when phone details are needed.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 400 || Bad Request – The contact ID is missing, invalid, or does not match a contact 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 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:19, 17 July 2026

API » Get Contact Personnel

Base URL

https://app.callproof.com

Endpoint

/api/contact/personnel/get/<contact_id>/

Purpose

Retrieves the people (personnel) associated with a specific contact in your CallProof company. Use this to obtain role, name, email, title, and last-contacted details for individuals linked to a contact account.

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
contact_id integer Yes Unique identifier of the contact whose personnel 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/get/789/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"

Successful Response (200)

Returns all personnel records associated with the specified contact.

Field Type Description
results array List of personnel associated with the contact.
results[].id integer Unique identifier for the personnel record.
results[].fullname string Full display name of the person.
results[].first_name string First name.
results[].last_name string Last name.
results[].title string Job title.
results[].last_contacted string Date and time this person was last contacted (YYYY-MM-DD HH:MM:SS), or empty if none.
results[].role string Role name associated with the person, or empty if none.
results[].email string Email address.
results[].updated string Date and time the personnel record was last updated (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": 55,
      "fullname": "Sarah Jones",
      "first_name": "Sarah",
      "last_name": "Jones",
      "title": "Purchasing Manager",
      "last_contacted": "2024-06-15 14:30:00",
      "role": "Decision Maker",
      "email": "sarah@acme.com",
      "updated": "2024-06-15 14:30:00"
    }
  ],
  "errors": [],
  "code": 200
}

Notes

  • contact_id is provided in the URL path.
  • The contact must belong to your company.
  • All personnel linked to the contact are returned.
  • If the contact exists but has no personnel, the response returns an empty results list with status 200.
  • This endpoint does not support pagination or date-range filtering.
  • Phone numbers for personnel are not included in this response. Use the personnel phones endpoint when phone details are needed.

Error Responses

Status Code Meaning
400 Bad Request – The contact ID is missing, invalid, or does not match a contact 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 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:Get&oldid=2285"