Difference between revisions of "API:People:Update"

From docs
Jump to: navigation, search
(Created page with "== API » Update Personnel Details HTML == '''URL:''' <nowiki>https://app.callproof.com/api/contact/personnel/update/</nowiki> '''Method:''' POST '''Required Fields...")
 
 
Line 1: Line 1:
−
== [[API]] &#187; Update Personnel Details HTML ==
+
== [[API]] &#187;Update Contact Personnel ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact/personnel/update/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/contact/personnel/update/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Updates an existing person (personnel record) under a contact in your CallProof company. Use this to change details such as name, email, title, notes, or to enable/disable the personnel record.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''personnel[id]''''' - Personnel ID
 
  
 +
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
'''Optional Fields:'''
+
=== Security ===
−
* '''''personnel[first_name]''''' - First name of personnel
+
* '''Yes''' – Requires a valid API key and secret with permission to update contacts. Credentials are sent in the request body.
−
* '''''personnel[last_name]''''' - Last name of personnel
 
−
* '''''personnel[email]''''' - Email of personnel
 
−
* '''''personnel[notes]''''' - Notes of personnel
 
−
* '''''personnel[title]''''' - Title of personnel
 
−
* '''''personnel[disable]''''' - '1' to disable the personnel or '0' to active the personnel
 
  
 +
=== Parameters ===
  
 +
==== Path Parameters ====
 +
None.
  
−
'''Data Returned:'''
+
==== Query Parameters ====
 +
None.
  
−
* '''''results''''' - Array containing updated Personnel details
+
==== Request Body ====
−
* '''''errors''''' - Array of errors produced by the request
+
{| class="wikitable"
−
* '''''code''''' - HTTP request status
+
! Parameter !! Type !! Required !! Description
 +
|-
 +
| api_key || object || Yes || Authentication credentials object.
 +
|-
 +
| api_key.key || string || Yes || Public API key assigned to your CallProof account.
 +
|-
 +
| api_key.secret || string || Yes || Private API secret paired with the API key.
 +
|-
 +
| personnel || object || Yes || Personnel update payload.
 +
|-
 +
| personnel.id || integer || Yes || Unique identifier of the personnel record to update. Must belong to your company.
 +
|-
 +
| personnel.first_name || string || No || Updated first name. Applied only when a non-empty value is provided.
 +
|-
 +
| personnel.last_name || string || No || Updated last name.
 +
|-
 +
| personnel.email || string || No || Updated email address.
 +
|-
 +
| personnel.title || string || No || Updated job title.
 +
|-
 +
| personnel.notes || string || No || Updated free-text notes about the person.
 +
|-
 +
| personnel.disable || integer || No || Set to <code>1</code> to disable the personnel record; <code>0</code> to keep it enabled.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/contact/personnel/update/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "personnel": {
 +
      "id": 55,
 +
      "title": "Director of Purchasing",
 +
      "email": "sarah.jones@acme.com"
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the personnel record was updated successfully. The response returns the updated personnel details.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Updated personnel details.
 +
|-
 +
| 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, 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 || object || Empty object 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": "Director of Purchasing",
 +
    "last_contacted": "2024-06-15 14:30:00",
 +
    "role": "Decision Maker",
 +
    "email": "sarah.jones@acme.com",
 +
    "updated": "2024-06-15 14:35:00"
 +
  },
 +
  "errors": {},
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* The <code>id</code> parameter is the personnel record ID, not the contact ID.
 +
* The personnel record must belong to your company.
 +
* Only the fields you provide are updated; omitted fields are left unchanged.
 +
* <code>first_name</code> is applied only when a non-empty value is supplied.
 +
* <code>disable</code> controls whether the personnel record is active: <code>1</code> disables it and <code>0</code> keeps it enabled.
 +
* Field-level validation issues are returned in the <code>errors</code> object with HTTP <code>200</code>.
 +
* Invalid JSON in the request body returns HTTP <code>400</code>.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 200 || Validation issue – The personnel ID is missing, the personnel record was not found, or the record could not be saved. Details are provided in the <code>errors</code> object.
 +
|-
 +
| 400 || Bad Request – The JSON payload is invalid.
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to update contacts.
 +
|-
 +
| 405 || Method Not Allowed – A method other than POST was used.
 +
|-
 +
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
 +
|}
 +
 
 +
'''400 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid json data"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
'''200 validation response examples:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": {
 +
    "personnel_id": ["Personnel ID required"]
 +
  },
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": {
 +
    "personnel_id": ["Personnel not found"]
 +
  },
 +
  "code": 200
 +
}
 +
</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:24, 17 July 2026

API »Update Contact Personnel

Base URL

https://app.callproof.com

Endpoint

/api/contact/personnel/update/

Purpose

Updates an existing person (personnel record) under a contact in your CallProof company. Use this to change details such as name, email, title, notes, or to enable/disable the personnel record.

HTTP Method

POST

Headers

Header Required Description
Content-Type Yes Must be application/json.

Security

  • Yes – Requires a valid API key and secret with permission to update contacts. Credentials are sent in the request body.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

Parameter Type Required Description
api_key object Yes Authentication credentials object.
api_key.key string Yes Public API key assigned to your CallProof account.
api_key.secret string Yes Private API secret paired with the API key.
personnel object Yes Personnel update payload.
personnel.id integer Yes Unique identifier of the personnel record to update. Must belong to your company.
personnel.first_name string No Updated first name. Applied only when a non-empty value is provided.
personnel.last_name string No Updated last name.
personnel.email string No Updated email address.
personnel.title string No Updated job title.
personnel.notes string No Updated free-text notes about the person.
personnel.disable integer No Set to 1 to disable the personnel record; 0 to keep it enabled.

cURL Example

curl -X POST "https://app.callproof.com/api/contact/personnel/update/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "personnel": {
      "id": 55,
      "title": "Director of Purchasing",
      "email": "sarah.jones@acme.com"
    }
  }'

Successful Response (200)

Indicates the personnel record was updated successfully. The response returns the updated personnel details.

Field Type Description
results object Updated personnel details.
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, 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 object Empty object 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": "Director of Purchasing",
    "last_contacted": "2024-06-15 14:30:00",
    "role": "Decision Maker",
    "email": "sarah.jones@acme.com",
    "updated": "2024-06-15 14:35:00"
  },
  "errors": {},
  "code": 200
}

Notes

  • The id parameter is the personnel record ID, not the contact ID.
  • The personnel record must belong to your company.
  • Only the fields you provide are updated; omitted fields are left unchanged.
  • first_name is applied only when a non-empty value is supplied.
  • disable controls whether the personnel record is active: 1 disables it and 0 keeps it enabled.
  • Field-level validation issues are returned in the errors object with HTTP 200.
  • Invalid JSON in the request body returns HTTP 400.

Error Responses

Status Code Meaning
200 Validation issue – The personnel ID is missing, the personnel record was not found, or the record could not be saved. Details are provided in the errors object.
400 Bad Request – The JSON payload is invalid.
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to update contacts.
405 Method Not Allowed – A method other than POST was used.
500 Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

400 response body example: 

{
  "results": [],
  "errors": ["Invalid json data"],
  "code": 400
}

200 validation response examples: 

{
  "results": [],
  "errors": {
    "personnel_id": ["Personnel ID required"]
  },
  "code": 200
}

{
  "results": [],
  "errors": {
    "personnel_id": ["Personnel not found"]
  },
  "code": 200
}

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:Update&oldid=2292"