Difference between revisions of "API:Contact:Get"

From docs
Jump to: navigation, search
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  
−
== [[API]] » Get Contacts ==
+
== [[API]] » Get Contact Details ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contacts/get/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' GET
+
=== Endpoint ===
 +
/api/contact/get/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Retrieves the full details of a single contact by contact ID for your CallProof company. Use this when you need the complete profile for one known contact, including phone numbers, assigned sales representatives, and custom field values.
  
−
* '''''key''''' - API Key
+
=== HTTP Method ===
−
* '''''secret''''' - API Key Secret
+
GET
−
* '''''id''''' - Contact ID
 
  
−
'''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
+
=== Parameters ===
−
* '''''errors''''' - Array of errors produced by the request
+
 
−
* '''''code''''' - HTTP request status
+
==== 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.
 +
|-
 +
| id || integer || Yes || Unique identifier of the contact to retrieve. Must belong to your company.
 +
|}
 +
 
 +
==== Path Parameters ====
 +
None.
 +
 
 +
==== Request Body ====
 +
None.
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X GET "https://app.callproof.com/api/contact/get/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&id=789"
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Returns the full contact profile when the contact is found. If the contact ID is valid in format but no matching contact exists in your company, the request still succeeds with an empty <code>results</code> object.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Contact details object, or empty object if the contact was not found.
 +
|-
 +
| 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.custom_fields[].id || integer || Custom field identifier.
 +
|-
 +
| results.custom_fields[].name || string || Custom field name.
 +
|-
 +
| results.custom_fields[].value || string || Custom field display value.
 +
|-
 +
| results.custom_fields[].value_id || string || Custom field option/value identifier, when applicable.
 +
|-
 +
| results.reps || array || Sales representatives 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.
 +
|}
 +
 
 +
==== Contact Phone Object Fields ====
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| id || integer || Unique identifier for the phone number.
 +
|-
 +
| last_contacted || string || Date and time this phone was last contacted.
 +
|-
 +
| unknown || integer || <code>1</code> if marked unknown; otherwise <code>0</code>.
 +
|-
 +
| do_not_call || integer || <code>1</code> if do-not-call is enabled; otherwise <code>0</code>.
 +
|-
 +
| contact_id || integer || Associated contact identifier.
 +
|-
 +
| contact || string || Contact display name.
 +
|-
 +
| phone_type || string || Phone type name (for example, Mobile or Office).
 +
|-
 +
| phone_number || string || Phone number.
 +
|-
 +
| ext || string || Phone extension, if any.
 +
|-
 +
| activated || string || Activation date/time, if set.
 +
|-
 +
| eligible || string || Eligibility date/time, if set.
 +
|-
 +
| call_result || string || Last call result, if any.
 +
|-
 +
| hidden || integer || <code>1</code> if the phone is hidden; otherwise <code>0</code>.
 +
|-
 +
| dealer_store || string || Associated dealer/store name, if any.
 +
|-
 +
| model || string || Model value, if any.
 +
|-
 +
| updated || string || Date and time the phone record was last updated.
 +
|-
 +
| created || string || Date and time the phone record was created.
 +
|}
 +
 
 +
Example response (contact found):
 +
<pre>
 +
{
 +
  "results": {
 +
    "id": 789,
 +
    "company": "Acme Corp",
 +
    "contact_phones": [
 +
      {
 +
        "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": "",
 +
        "activated": "",
 +
        "eligible": "",
 +
        "call_result": "",
 +
        "hidden": 0,
 +
        "dealer_store": "",
 +
        "model": "",
 +
        "updated": "2024-06-15 14:30:00",
 +
        "created": "2024-01-10 09:00:00"
 +
      }
 +
    ],
 +
    "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": [
 +
      {
 +
        "id": 12,
 +
        "name": "Industry",
 +
        "value": "Manufacturing",
 +
        "value_id": "3"
 +
      }
 +
    ],
 +
    "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>
 +
 
 +
Example response (contact not found):
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 400 || Bad Request – The required <code>id</code> parameter is missing or cannot be interpreted as a valid integer.
 +
|-
 +
| 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 '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>

Latest revision as of 12:02, 17 July 2026

API » Get Contact Details

Base URL

https://app.callproof.com

Endpoint

/api/contact/get/

Purpose

Retrieves the full details of a single contact by contact ID for your CallProof company. Use this when you need the complete profile for one known contact, including phone numbers, assigned sales representatives, and custom field values.

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

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.
id integer Yes Unique identifier of the contact to retrieve. Must belong to your company.

Path Parameters

None.

Request Body

None.

cURL Example

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

Successful Response (200)

Returns the full contact profile when the contact is found. If the contact ID is valid in format but no matching contact exists in your company, the request still succeeds with an empty results object.

Field Type Description
results object Contact details object, or empty object if the contact was not found.
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.custom_fields[].id integer Custom field identifier.
results.custom_fields[].name string Custom field name.
results.custom_fields[].value string Custom field display value.
results.custom_fields[].value_id string Custom field option/value identifier, when applicable.
results.reps array Sales representatives 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.

Contact Phone Object Fields

Field Type Description
id integer Unique identifier for the phone number.
last_contacted string Date and time this phone was last contacted.
unknown integer 1 if marked unknown; otherwise 0.
do_not_call integer 1 if do-not-call is enabled; otherwise 0.
contact_id integer Associated contact identifier.
contact string Contact display name.
phone_type string Phone type name (for example, Mobile or Office).
phone_number string Phone number.
ext string Phone extension, if any.
activated string Activation date/time, if set.
eligible string Eligibility date/time, if set.
call_result string Last call result, if any.
hidden integer 1 if the phone is hidden; otherwise 0.
dealer_store string Associated dealer/store name, if any.
model string Model value, if any.
updated string Date and time the phone record was last updated.
created string Date and time the phone record was created.

Example response (contact found): 

{
  "results": {
    "id": 789,
    "company": "Acme Corp",
    "contact_phones": [
      {
        "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": "",
        "activated": "",
        "eligible": "",
        "call_result": "",
        "hidden": 0,
        "dealer_store": "",
        "model": "",
        "updated": "2024-06-15 14:30:00",
        "created": "2024-01-10 09:00:00"
      }
    ],
    "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": [
      {
        "id": 12,
        "name": "Industry",
        "value": "Manufacturing",
        "value_id": "3"
      }
    ],
    "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
}

Example response (contact not found): 

{
  "results": {},
  "errors": [],
  "code": 200
}

Error Responses

Status Code Meaning
400 Bad Request – The required id parameter is missing or cannot be interpreted as a valid integer.
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 '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
}
Retrieved from "http://docs.callproof.com/index.php?title=API:Contact:Get&oldid=2273"