Difference between revisions of "API:Contact:Update:Reps"

From docs
Jump to: navigation, search
(Created page with " == API » Update Contact Reps == '''URL:''' <nowiki>https://app.callproof.com/api/contact/update/reps/</nowiki> '''Method:''' POST '''Required Fields:''' * '''''a...")
 
 
(4 intermediate revisions by the same user not shown)
Line 2: Line 2:
 
== [[API]] &#187; Update Contact Reps ==
 
== [[API]] &#187; Update Contact Reps ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact/update/reps/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/contact/update/reps/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Replaces the sales representatives assigned to a contact. Use this when you need to update only assignment ownership without changing other contact profile details. Providing a new list clears the previous assignments and applies the new set. Providing an empty list clears all assigned representatives.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''contact[id]''''' - Contact ID
 
−
* '''''contact[rep_ids][]''''' - Array of Contact Rep IDs (use an empty array [] to remove all reps)
 
  
−
'''Optional Fields:'''
+
=== Headers ===
−
None
+
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
 +
=== Security ===
 +
* '''Yes''' – Requires a valid API key and secret with permission to update contacts. Credentials are sent in the request body.
  
−
'''Data Returned:'''
+
=== Parameters ===
  
−
* '''''results''''' - Contact with newly assigned reps
+
==== 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 assignment payload.
 +
|-
 +
| contact.id || integer || Yes || Unique identifier of the contact whose assigned sales representatives should be updated. Must belong to your company.
 +
|-
 +
| contact.rep_ids || array of integers || No || User IDs of sales representatives to assign to the contact. Replaces the current assignment list. If omitted or empty, all existing assignments are cleared. Only rep IDs belonging to your company are applied.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/contact/update/reps/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "contact": {
 +
      "id": 789,
 +
      "rep_ids": [456]
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
Example to clear all assigned representatives:
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/contact/update/reps/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "contact": {
 +
      "id": 789,
 +
      "rep_ids": []
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the contact’s sales representative assignments were successfully updated. The response returns the full contact profile, including the current assigned representatives.
 +
 
 +
{| 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 currently assigned to the contact.
 +
|-
 +
| results.reps[].id || integer || Rep profile identifier.
 +
|-
 +
| results.reps[].email || string || Rep email address.
 +
|-
 +
| results.reps[].user_id || integer || Associated user account identifier.
 +
|-
 +
| results.reps[].name || string || Rep display name.
 +
|-
 +
| results.reps[].title || string || Rep job title.
 +
|-
 +
| results.reps[].updated || string || Date and time the rep profile was last updated.
 +
|-
 +
| 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, 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 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 'id' 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>
 +
=== Notes ===
 +
 
 +
This endpoint updates only sales representative assignments. Other contact profile fields are not changed.
 +
 
 +
Any existing assignments are removed before the new list is applied.
 +
 
 +
If rep_ids is omitted or empty, all current assignments are cleared.
 +
 
 +
Only sales representatives that belong to your company are applied. Invalid or out-of-company IDs are skipped.
 +
 
 +
If your company is configured for single sales representative mode, only one representative can remain assigned.
 +
 
 +
When at least one valid representative is assigned, the contact is marked as assigned.

Latest revision as of 12:02, 17 July 2026

API » Update Contact Reps

Base URL

https://app.callproof.com

Endpoint

/api/contact/update/reps/

Purpose

Replaces the sales representatives assigned to a contact. Use this when you need to update only assignment ownership without changing other contact profile details. Providing a new list clears the previous assignments and applies the new set. Providing an empty list clears all assigned representatives.

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 assignment payload.
contact.id integer Yes Unique identifier of the contact whose assigned sales representatives should be updated. Must belong to your company.
contact.rep_ids array of integers No User IDs of sales representatives to assign to the contact. Replaces the current assignment list. If omitted or empty, all existing assignments are cleared. Only rep IDs belonging to your company are applied.

cURL Example

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

Example to clear all assigned representatives: 

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

Successful Response (200)

Indicates the contact’s sales representative assignments were successfully updated. The response returns the full contact profile, including the current assigned representatives.

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 currently assigned to the contact.
results.reps[].id integer Rep profile identifier.
results.reps[].email string Rep email address.
results.reps[].user_id integer Associated user account identifier.
results.reps[].name string Rep display name.
results.reps[].title string Rep job title.
results.reps[].updated string Date and time the rep profile was last updated.
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, 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 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 'id' 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
}

Notes

This endpoint updates only sales representative assignments. Other contact profile fields are not changed.

Any existing assignments are removed before the new list is applied.

If rep_ids is omitted or empty, all current assignments are cleared.

Only sales representatives that belong to your company are applied. Invalid or out-of-company IDs are skipped.

If your company is configured for single sales representative mode, only one representative can remain assigned.

When at least one valid representative is assigned, the contact is marked as assigned.

Retrieved from "http://docs.callproof.com/index.php?title=API:Contact:Update:Reps&oldid=2275"