Difference between revisions of "API:Contact:Update"

From docs
Jump to: navigation, search
 
(One intermediate revision by the same user not shown)
Line 2: Line 2:
 
== [[API]] » Update Contact ==
 
== [[API]] » Update Contact ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact/update/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/contact/update/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Updates an existing contact in your CallProof company. Use this to change contact profile details such as name, address, email, company association, contact type, phone numbers, assigned sales representatives, and related attributes. Only the fields you supply are applied; the updated contact profile is returned on success.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''contact[id]''''' - Contact ID
 
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
* '''''contact[rep_ids][]''''' - Array of Contact Rep IDs (use an empty array [] to remove all reps)
+
=== Security ===
−
* '''''contact[contact_phones][]''''' - Array of Contact Phones
+
* '''Yes''' – Requires a valid API key and secret with permission to update contacts. Credentials are sent in the request body.
−
* '''''contact[contact_type]''''' - Contact custom contact type (https://app.callproof.com/contact_types/)
 
−
* '''''contact[company_name]''''' - Contact company name
 
−
* '''''contact[first_name]''''' - Contact first name
 
−
* '''''contact[last_name]''''' - Contact last name
 
−
* '''''contact[title]''''' - Contact title (e.g. CEO)
 
−
* '''''contact[email]''''' - Contact email address (e.g. fred@aol.com)
 
−
* '''''contact[account]''''' - Contact account number (e.g. 123456)
 
−
* '''''contact[invoice]''''' - Contact invoice number (e.g. 123456)
 
−
* '''''contact[website]''''' - Contact website URL (e.g. <nowiki>http://example.com/</nowiki>)
 
−
* '''''contact[address]''''' - Contact address
 
−
* '''''contact[address2]''''' - Contact address2
 
−
* '''''contact[city]''''' - Contact city
 
−
* '''''contact[state]''''' - Contact two letter state name (e.g. TN, FL, CA)
 
−
* '''''contact[zip]''''' - Contact zip code
 
−
* '''''contact[country]''''' - Contact country
 
−
* '''''contact[latitude]''''' - Contact latitude
 
−
* '''''contact[longitude]''''' - Contact longitude
 
−
* '''''contact[unknown]''''' - Set to '1' if Contact is unknown
 
−
* '''''contact[do_not_sms]''''' - Set to '1' if Contact should not be sent SM messages
 
−
* '''''contact[last_contacted]''''' - Contact last contacted date/time (e.g. '2014-08-10 12:34:56')
 
−
* '''''contact[default_phone][phone_number]''''' - Contact default phone number (e.g. 6158675309)
 
−
* '''''contact[default_phone][phone_type]''''' - Contact default phone type (cell, home, office, fax, headquartes, other)
 
  
−
'''Data Returned:'''
+
=== Parameters ===
  
−
* '''''results''''' - Contact as provided
+
==== Path Parameters ====
−
* '''''errors''''' - Array of errors produced by the request
+
None.
−
* '''''code''''' - HTTP request status
+
 
 +
==== Query Parameters ====
 +
None.
 +
 
 +
==== Request Body ====
 +
{| class="wikitable"
 +
! 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.
 +
|-
 +
| contact || object || Yes || Contact update payload.
 +
|-
 +
| contact.id || integer || Yes || Unique identifier of the contact to update. Must belong to your company.
 +
|-
 +
| contact.title || string || No || Contact title. Maximum 64 characters.
 +
|-
 +
| contact.first_name || string || No || Contact first name. Maximum 32 characters.
 +
|-
 +
| contact.last_name || string || No || Contact last name. Maximum 32 characters.
 +
|-
 +
| contact.email || string || No || Contact email address. Maximum 64 characters.
 +
|-
 +
| contact.website || string || No || Website URL. Maximum 255 characters.
 +
|-
 +
| contact.company_name || string || No || Associated company name. When provided, a new company association is created for the contact. Maximum 64 characters.
 +
|-
 +
| contact.address || string || No || Primary street address. Maximum 80 characters.
 +
|-
 +
| contact.address2 || string || No || Secondary street address. Maximum 80 characters.
 +
|-
 +
| contact.city || string || No || City. Maximum 64 characters.
 +
|-
 +
| contact.state || string || No || State or province abbreviation (up to 2 characters). Must match a recognized abbreviation.
 +
|-
 +
| contact.zip || string || No || Postal/ZIP code. Maximum 10 characters.
 +
|-
 +
| contact.country || string || No || Country name. Must match a recognized country.
 +
|-
 +
| contact.account || string || No || Account number or identifier. Maximum 80 characters.
 +
|-
 +
| contact.invoice || string || No || Invoice-related value. Maximum 64 characters.
 +
|-
 +
| contact.contact_type || string || No || Contact type name. Must match an existing contact type in your company.
 +
|-
 +
| contact.unknown || integer || No || Set to <code>1</code> to mark the contact as unknown; otherwise <code>0</code>. If omitted, defaults to not unknown.
 +
|-
 +
| contact.do_not_sms || integer || No || Set to <code>1</code> to disable SMS for the contact; otherwise <code>0</code>. If omitted, defaults to SMS allowed.
 +
|-
 +
| contact.latitude || number || No || Geographic latitude.
 +
|-
 +
| contact.longitude || number || No || Geographic longitude.
 +
|-
 +
| contact.last_contacted || datetime string || No || Date and time of last contact.
 +
|-
 +
| contact.default_phone || object || No || Default phone number to create or update for the contact.
 +
|-
 +
| contact.default_phone.phone_number || string || No || Default phone number digits. A valid number is required for the default phone to be applied.
 +
|-
 +
| contact.default_phone.phone_type || string || No || Phone type name (for example, Mobile or Office). Required for the default phone to be saved.
 +
|-
 +
| contact.contact_phones || array || No || Additional phone numbers to create or update for the contact.
 +
|-
 +
| contact.contact_phones[].phone_type || string || Yes* || Phone type name. Required for each phone entry to be processed.
 +
|-
 +
| contact.contact_phones[].phone_number || string || Yes* || Phone number. Must resolve to a valid 10-digit number.
 +
|-
 +
| contact.contact_phones[].ext || string || No || Phone extension.
 +
|-
 +
| contact.contact_phones[].unknown || integer || No || <code>1</code> if marked unknown; otherwise <code>0</code>.
 +
|-
 +
| contact.contact_phones[].do_not_call || integer || No || <code>1</code> if do-not-call is enabled; otherwise <code>0</code>.
 +
|-
 +
| contact.contact_phones[].hidden || integer || No || <code>1</code> if the phone is hidden; otherwise <code>0</code>.
 +
|-
 +
| contact.contact_phones[].last_contacted || datetime string || No || Date and time this phone was last contacted.
 +
|-
 +
| contact.contact_phones[].eligible || datetime string || No || Eligibility date/time.
 +
|-
 +
| contact.contact_phones[].activated || datetime string || No || Activation date/time.
 +
|-
 +
| contact.contact_phones[].model || string || No || Model value. Maximum 255 characters.
 +
|-
 +
| contact.contact_phones[].dealer_store || string || No || Dealer/store name. Must match an existing store in your company.
 +
|-
 +
| contact.contact_phones[].call_result || string || No || Call result name. Must match an existing call result in your company.
 +
|-
 +
| contact.rep_ids || array of integers || No || User IDs of sales representatives to assign to the contact. Replaces the current assignment list when provided. Each value must be numeric.
 +
|}
 +
 
 +
\* For each phone entry in <code>contact_phones</code>, both a valid phone type and a valid 10-digit phone number are required for that entry to be processed.
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/contact/update/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "contact": {
 +
      "id": 789
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
Example with common update fields:
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/contact/update/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "contact": {
 +
      "id": 789,
 +
      "first_name": "John",
 +
      "last_name": "Doe",
 +
      "email": "john@acme.com",
 +
      "city": "Austin",
 +
      "state": "TX",
 +
      "contact_type": "Prospect",
 +
      "rep_ids": [456]
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the contact was successfully updated. The response returns the full updated contact profile.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Updated contact details.
 +
|-
 +
| results.id || integer || Unique identifier for the contact.
 +
|-
 +
| results.company || string || Name of the contact company associated with the contact.
 +
|-
 +
| results.contact_phones || array || Phone numbers associated with the contact.
 +
|-
 +
| results.created_by || string || Display name of the user who created the contact.
 +
|-
 +
| results.created_by_id || integer || User ID 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 name.
 +
|-
 +
| 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 || Secondary street address.
 +
|-
 +
| results.city || string || City.
 +
|-
 +
| results.state || string || State or province name.
 +
|-
 +
| results.zip || string || Postal/ZIP code.
 +
|-
 +
| results.country || string || Country name.
 +
|-
 +
| results.website || string || Website URL.
 +
|-
 +
| results.latitude || string || Geographic latitude.
 +
|-
 +
| results.longitude || string || Geographic longitude.
 +
|-
 +
| results.last_contacted || string || Date and time of last contact (<code>YYYY-MM-DD HH:MM:SS</code>), or empty if none.
 +
|-
 +
| results.default_phone || object || Default phone number details for the contact.
 +
|-
 +
| results.account || string || Account number or identifier.
 +
|-
 +
| results.invoice || string || Invoice-related value, if set.
 +
|-
 +
| results.unknown || integer || <code>1</code> if marked unknown; otherwise <code>0</code>.
 +
|-
 +
| results.assigned || integer || <code>1</code> if the contact is assigned; otherwise <code>0</code>.
 +
|-
 +
| results.do_not_sms || integer || <code>1</code> if SMS is disabled for the contact; otherwise <code>0</code>.
 +
|-
 +
| results.updated || string || Date and time the contact was last updated (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| results.created || string || Date and time the contact was created (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| results.custom_fields || array || Visible custom field values for the contact.
 +
|-
 +
| results.reps || array || Sales representatives assigned to the contact.
 +
|-
 +
| errors || array || Empty list when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "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": [
 +
      {
 +
        "id": 123,
 +
        "email": "rep@example.com",
 +
        "user_id": 456,
 +
        "name": "Jane Smith",
 +
        "title": "Account Executive",
 +
        "updated": "2024-06-01 10:00:00"
 +
      }
 +
    ]
 +
  },
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 400 || Bad Request – The contact ID is missing/invalid, the contact was not found in your company, or one or more rep IDs are not valid numbers.
 +
|-
 +
| 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 examples:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid 'id' field"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Rep IDs must be valid numeric value"],
 +
  "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:02, 17 July 2026

API » Update Contact

Base URL

https://app.callproof.com

Endpoint

/api/contact/update/

Purpose

Updates an existing contact in your CallProof company. Use this to change contact profile details such as name, address, email, company association, contact type, phone numbers, assigned sales representatives, and related attributes. Only the fields you supply are applied; the updated contact profile is returned on success.

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.
contact object Yes Contact update payload.
contact.id integer Yes Unique identifier of the contact to update. Must belong to your company.
contact.title string No Contact title. Maximum 64 characters.
contact.first_name string No Contact first name. Maximum 32 characters.
contact.last_name string No Contact last name. Maximum 32 characters.
contact.email string No Contact email address. Maximum 64 characters.
contact.website string No Website URL. Maximum 255 characters.
contact.company_name string No Associated company name. When provided, a new company association is created for the contact. Maximum 64 characters.
contact.address string No Primary street address. Maximum 80 characters.
contact.address2 string No Secondary street address. Maximum 80 characters.
contact.city string No City. Maximum 64 characters.
contact.state string No State or province abbreviation (up to 2 characters). Must match a recognized abbreviation.
contact.zip string No Postal/ZIP code. Maximum 10 characters.
contact.country string No Country name. Must match a recognized country.
contact.account string No Account number or identifier. Maximum 80 characters.
contact.invoice string No Invoice-related value. Maximum 64 characters.
contact.contact_type string No Contact type name. Must match an existing contact type in your company.
contact.unknown integer No Set to 1 to mark the contact as unknown; otherwise 0. If omitted, defaults to not unknown.
contact.do_not_sms integer No Set to 1 to disable SMS for the contact; otherwise 0. If omitted, defaults to SMS allowed.
contact.latitude number No Geographic latitude.
contact.longitude number No Geographic longitude.
contact.last_contacted datetime string No Date and time of last contact.
contact.default_phone object No Default phone number to create or update for the contact.
contact.default_phone.phone_number string No Default phone number digits. A valid number is required for the default phone to be applied.
contact.default_phone.phone_type string No Phone type name (for example, Mobile or Office). Required for the default phone to be saved.
contact.contact_phones array No Additional phone numbers to create or update for the contact.
contact.contact_phones[].phone_type string Yes* Phone type name. Required for each phone entry to be processed.
contact.contact_phones[].phone_number string Yes* Phone number. Must resolve to a valid 10-digit number.
contact.contact_phones[].ext string No Phone extension.
contact.contact_phones[].unknown integer No 1 if marked unknown; otherwise 0.
contact.contact_phones[].do_not_call integer No 1 if do-not-call is enabled; otherwise 0.
contact.contact_phones[].hidden integer No 1 if the phone is hidden; otherwise 0.
contact.contact_phones[].last_contacted datetime string No Date and time this phone was last contacted.
contact.contact_phones[].eligible datetime string No Eligibility date/time.
contact.contact_phones[].activated datetime string No Activation date/time.
contact.contact_phones[].model string No Model value. Maximum 255 characters.
contact.contact_phones[].dealer_store string No Dealer/store name. Must match an existing store in your company.
contact.contact_phones[].call_result string No Call result name. Must match an existing call result in your company.
contact.rep_ids array of integers No User IDs of sales representatives to assign to the contact. Replaces the current assignment list when provided. Each value must be numeric.

\* For each phone entry in contact_phones, both a valid phone type and a valid 10-digit phone number are required for that entry to be processed.

cURL Example

curl -X POST "https://app.callproof.com/api/contact/update/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "contact": {
      "id": 789
    }
  }'

Example with common update fields: 

curl -X POST "https://app.callproof.com/api/contact/update/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "contact": {
      "id": 789,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acme.com",
      "city": "Austin",
      "state": "TX",
      "contact_type": "Prospect",
      "rep_ids": [456]
    }
  }'

Successful Response (200)

Indicates the contact was successfully updated. The response returns the full updated contact profile.

Field Type Description
results object Updated contact details.
results.id integer Unique identifier for the contact.
results.company string Name of the contact company associated with the contact.
results.contact_phones array Phone numbers associated with the contact.
results.created_by string Display name of the user who created the contact.
results.created_by_id integer User ID 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 name.
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 Secondary street address.
results.city string City.
results.state string State or province name.
results.zip string Postal/ZIP code.
results.country string Country name.
results.website string Website URL.
results.latitude string Geographic latitude.
results.longitude string Geographic longitude.
results.last_contacted string Date and time of last contact (YYYY-MM-DD HH:MM:SS), or empty if none.
results.default_phone object Default phone number details for the contact.
results.account string Account number or identifier.
results.invoice string Invoice-related value, if set.
results.unknown integer 1 if marked unknown; otherwise 0.
results.assigned integer 1 if the contact is assigned; otherwise 0.
results.do_not_sms integer 1 if SMS is disabled for the contact; otherwise 0.
results.updated string Date and time the contact was last updated (YYYY-MM-DD HH:MM:SS).
results.created string Date and time the contact was created (YYYY-MM-DD HH:MM:SS).
results.custom_fields array Visible custom field values for the contact.
results.reps array Sales representatives assigned to the contact.
errors array Empty list when the request succeeds.
code integer HTTP-style status value; 200 on success.

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": [
      {
        "id": 123,
        "email": "rep@example.com",
        "user_id": 456,
        "name": "Jane Smith",
        "title": "Account Executive",
        "updated": "2024-06-01 10:00:00"
      }
    ]
  },
  "errors": [],
  "code": 200
}

Error Responses

Status Code Meaning
400 Bad Request – The contact ID is missing/invalid, the contact was not found in your company, or one or more rep IDs are not valid numbers.
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 examples: 

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

{
  "results": [],
  "errors": ["Rep IDs must be valid numeric value"],
  "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:Update&oldid=2274"