Difference between revisions of "API:Contacts:Created"

From docs
Jump to: navigation, search
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
 
+
== [[API]] » Get Contacts Created ==
−
== [[API]] » Created Contacts ==
 
−
 
 
−
== Get Contacts Created ==
 
  
 
=== Base URL ===
 
=== Base URL ===
Line 31: Line 28:
  
 
==== Query Parameters ====
 
==== Query Parameters ====
−
 
 
{| class="wikitable"
 
{| class="wikitable"
 
! Parameter !! Type !! Required !! Description
 
! Parameter !! Type !! Required !! Description
Line 39: Line 35:
 
| secret || string || Yes || Private API secret paired with the API key.
 
| secret || string || Yes || Private API secret paired with the API key.
 
|-
 
|-
−
| after || datetime string || Yes || Return only contacts created on or after this date/time.
+
| after || datetime string || Yes || Return only contacts created on or after this date/time. Invalid or missing values cause a validation error.
 
|-
 
|-
−
| before || datetime string || No || Return only contacts created on or before this date/time.
+
| before || datetime string || No || Return only contacts created on or before this date/time. If omitted, no upper date limit is applied.
 
|-
 
|-
−
| offset || integer || No || Starting position for paginated results. Defaults to <code>0</code>.
+
| offset || integer || No || Starting position for paginated results. Defaults to <code>0</code> if omitted or invalid.
 
|}
 
|}
  
Line 53: Line 49:
  
 
=== cURL Example ===
 
=== cURL Example ===
−
 
 
<pre>
 
<pre>
 
curl -X GET "https://app.callproof.com/api/contacts/created/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&after=2024-01-01"
 
curl -X GET "https://app.callproof.com/api/contacts/created/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&after=2024-01-01"
Line 59: Line 54:
  
 
=== Successful Response (200) ===
 
=== Successful Response (200) ===
−
 
 
Returns a paginated list of contacts created within the requested date range. Up to 100 contacts are returned per request. If more matching contacts exist, <code>more</code> is set to <code>1</code> so the caller can request the next page using <code>offset</code>.
 
Returns a paginated list of contacts created within the requested date range. Up to 100 contacts are returned per request. If more matching contacts exist, <code>more</code> is set to <code>1</code> so the caller can request the next page using <code>offset</code>.
  
Line 67: Line 61:
 
| results || array || List of contact objects (maximum 100 per response).
 
| results || array || List of contact objects (maximum 100 per response).
 
|-
 
|-
−
| more || integer || <code>1</code> if additional contacts remain; otherwise <code>0</code>.
+
| results[].id || integer || Unique identifier for the contact.
 
|-
 
|-
−
| offset || integer || Offset used for this response.
+
| results[].company || string || Name of the contact company associated with the contact.
 
|-
 
|-
−
| errors || array || Empty when the request succeeds.
+
| results[].contact_phones || array || Phone numbers associated with the contact.
 
|-
 
|-
−
| code || integer || HTTP-style status code (<code>200</code> on success).
+
| results[].created_by || string || Display name of the user who created the contact.
−
|}
 
−
 
 
−
==== Contact Object Fields ====
 
−
 
 
−
{| class="wikitable"
 
−
! Field !! Type !! Description
 
 
|-
 
|-
−
| id || integer || Unique contact identifier.
+
| results[].created_by_id || integer || User ID of the person who created the contact.
 
|-
 
|-
−
| company || string || Company name.
+
| results[].created_by_email || string || Email address of the person who created the contact.
 
|-
 
|-
−
| contact_phones || array || Contact phone records.
+
| results[].contact_type || string || Contact type name.
 
|-
 
|-
−
| created_by || string || User who created the contact.
+
| results[].title || string || Contact title.
 
|-
 
|-
−
| created_by_id || integer || Creator user ID.
+
| results[].first_name || string || Contact first name.
 
|-
 
|-
−
| created_by_email || string || Creator email address.
+
| results[].last_name || string || Contact last name.
 
|-
 
|-
−
| contact_type || string || Contact type.
+
| results[].email || string || Contact email address.
 
|-
 
|-
−
| title || string || Contact title.
+
| results[].address || string || Primary street address.
 
|-
 
|-
−
| first_name || string || First name.
+
| results[].address2 || string || Secondary street address.
 
|-
 
|-
−
| last_name || string || Last name.
+
| results[].city || string || City.
 
|-
 
|-
−
| email || string || Email address.
+
| results[].state || string || State or province name.
 
|-
 
|-
−
| address || string || Street address.
+
| results[].zip || string || Postal/ZIP code.
 
|-
 
|-
−
| address2 || string || Secondary address.
+
| results[].country || string || Country name.
 
|-
 
|-
−
| city || string || City.
+
| results[].website || string || Website URL.
 
|-
 
|-
−
| state || string || State or province.
+
| results[].latitude || string || Geographic latitude.
 
|-
 
|-
−
| zip || string || ZIP/postal code.
+
| results[].longitude || string || Geographic longitude.
 
|-
 
|-
−
| country || string || Country.
+
| results[].last_contacted || string || Date and time of last contact (<code>YYYY-MM-DD HH:MM:SS</code>), or empty if none.
 
|-
 
|-
−
| website || string || Website URL.
+
| results[].default_phone || object || Default phone number details for the contact.
 
|-
 
|-
−
| latitude || string || Latitude.
+
| results[].account || string || Account number or identifier.
 
|-
 
|-
−
| longitude || string || Longitude.
+
| results[].invoice || string || Invoice-related value, if set.
 
|-
 
|-
−
| last_contacted || string || Last contact date/time.
+
| results[].unknown || integer || <code>1</code> if marked unknown; otherwise <code>0</code>.
 
|-
 
|-
−
| default_phone || object || Default phone information.
+
| results[].assigned || integer || <code>1</code> if the contact is assigned; otherwise <code>0</code>.
 
|-
 
|-
−
| account || string || Account identifier.
+
| results[].do_not_sms || integer || <code>1</code> if SMS is disabled for the contact; otherwise <code>0</code>.
 
|-
 
|-
−
| invoice || string || Invoice value.
+
| results[].updated || string || Date and time the contact was last updated (<code>YYYY-MM-DD HH:MM:SS</code>).
 
|-
 
|-
−
| unknown || integer || Unknown contact flag.
+
| results[].created || string || Date and time the contact was created (<code>YYYY-MM-DD HH:MM:SS</code>).
 
|-
 
|-
−
| assigned || integer || Assigned flag.
+
| results[].custom_fields || array || Visible custom field values for the contact.
 
|-
 
|-
−
| do_not_sms || integer || SMS restriction flag.
+
| results[].custom_fields[].id || integer || Custom field identifier.
 
|-
 
|-
−
| updated || string || Last updated date/time.
+
| results[].custom_fields[].name || string || Custom field name.
 
|-
 
|-
−
| created || string || Created date/time.
+
| results[].custom_fields[].value || string || Custom field display value.
 
|-
 
|-
−
| custom_fields || array || Contact custom fields.
+
| results[].custom_fields[].value_id || string || Custom field option/value identifier, when applicable.
 
|-
 
|-
−
| reps || array || Assigned sales representatives.
+
| results[].reps || array || Sales representatives assigned to the contact.
−
|}
 
−
 
 
−
==== Contact Phone Object Fields ====
 
−
 
 
−
{| class="wikitable"
 
−
! Field !! Type !! Description
 
 
|-
 
|-
−
| id || integer || Phone record identifier.
+
| results[].reps[].id || integer || Rep profile identifier.
 
|-
 
|-
−
| last_contacted || string || Last contacted date/time.
+
| results[].reps[].email || string || Rep email address.
 
|-
 
|-
−
| unknown || integer || Unknown phone flag.
+
| results[].reps[].user_id || integer || Associated user account identifier.
 
|-
 
|-
−
| do_not_call || integer || Do Not Call flag.
+
| results[].reps[].name || string || Rep display name.
 
|-
 
|-
−
| contact_id || integer || Contact identifier.
+
| results[].reps[].title || string || Rep job title.
 
|-
 
|-
−
| contact || string || Contact name.
+
| results[].reps[].updated || string || Date and time the rep profile was last updated.
 
|-
 
|-
−
| phone_type || string || Phone type.
+
| more || integer || <code>1</code> if additional matching contacts remain; <code>0</code> if this is the last page.
 
|-
 
|-
−
| phone_number || string || Phone number.
+
| offset || integer || Offset value used for this request.
 
|-
 
|-
−
| ext || string || Extension.
+
| errors || array || Empty list when the request succeeds.
 
|-
 
|-
−
| activated || string || Activation date.
+
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
==== Contact Phone Object Fields ====
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 
|-
 
|-
−
| eligible || string || Eligibility date.
+
| id || integer || Unique identifier for the phone number.
 
|-
 
|-
−
| call_result || string || Last call result.
+
| last_contacted || string || Date and time this phone was last contacted.
 
|-
 
|-
−
| hidden || integer || Hidden flag.
+
| unknown || integer || <code>1</code> if marked unknown; otherwise <code>0</code>.
 
|-
 
|-
−
| dealer_store || string || Dealer/store.
+
| do_not_call || integer || <code>1</code> if do-not-call is enabled; otherwise <code>0</code>.
 
|-
 
|-
−
| model || string || Model.
+
| contact_id || integer || Associated contact identifier.
 
|-
 
|-
−
| updated || string || Updated date/time.
+
| contact || string || Contact display name.
 
|-
 
|-
−
| created || string || Created date/time.
+
| phone_type || string || Phone type name (for example, Mobile or Office).
−
|}
 
−
 
 
−
==== Custom Field Object Fields ====
 
−
 
 
−
{| class="wikitable"
 
−
! Field !! Type !! Description
 
 
|-
 
|-
−
| id || integer || Custom field identifier.
+
| phone_number || string || Phone number.
 
|-
 
|-
−
| name || string || Custom field name.
+
| ext || string || Phone extension, if any.
 
|-
 
|-
−
| value || string || Display value.
+
| activated || string || Activation date/time, if set.
 
|-
 
|-
−
| value_id || string || Selected option identifier.
+
| eligible || string || Eligibility date/time, if set.
−
|}
 
−
 
 
−
==== Rep Object Fields ====
 
−
 
 
−
{| class="wikitable"
 
−
! Field !! Type !! Description
 
 
|-
 
|-
−
| id || integer || Rep identifier.
+
| call_result || string || Last call result, if any.
 
|-
 
|-
−
| email || string || Rep email.
+
| hidden || integer || <code>1</code> if the phone is hidden; otherwise <code>0</code>.
 
|-
 
|-
−
| user_id || integer || Associated user ID.
+
| dealer_store || string || Associated dealer/store name, if any.
 
|-
 
|-
−
| name || string || Rep name.
+
| model || string || Model value, if any.
 
|-
 
|-
−
| title || string || Rep title.
+
| updated || string || Date and time the phone record was last updated.
 
|-
 
|-
−
| updated || string || Last updated date/time.
+
| created || string || Date and time the phone record was created.
 
|}
 
|}
  
−
==== Example Response ====
+
Example response:
−
 
 
 
<pre>
 
<pre>
 
{
 
{
Line 224: Line 198:
 
       "id": 789,
 
       "id": 789,
 
       "company": "Acme Corp",
 
       "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"
 +
        }
 +
      ]
 
     }
 
     }
 
   ],
 
   ],
Line 235: Line 273:
  
 
=== Error Responses ===
 
=== Error Responses ===
−
 
 
{| class="wikitable"
 
{| class="wikitable"
 
! Status Code !! Meaning
 
! Status Code !! Meaning
 
|-
 
|-
−
| 400 || Bad Request – The required <code>after</code> parameter is missing or invalid.
+
| 400 || Bad Request – The required <code>after</code> parameter is missing or cannot be interpreted as a valid date/time.
 
|-
 
|-
−
| 401 || Unauthorized – Invalid or missing API credentials.
+
| 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 – Only GET is supported.
+
| 405 || Method Not Allowed – A method other than GET was used.
 
|-
 
|-
−
| 500 || Internal Server Error – Unexpected server error.
+
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
 
|}
 
|}
  
 
'''400 response body example:'''
 
'''400 response body example:'''
−
 
 
<pre>
 
<pre>
 
{
 
{
Line 259: Line 295:
  
 
'''401 response body example:'''
 
'''401 response body example:'''
−
 
 
<pre>
 
<pre>
 
{
 
{
Line 269: Line 304:
  
 
'''405 response body example:'''
 
'''405 response body example:'''
−
 
 
<pre>
 
<pre>
 
{
 
{

Latest revision as of 12:01, 17 July 2026

API » Get Contacts Created

Base URL

https://app.callproof.com

Endpoint

/api/contacts/created/

Purpose

Retrieves contacts created within a specified date range for your CallProof company. Supports pagination so large volumes of contacts can be synced in batches. Typically used to keep external systems in sync with newly created contacts, including phone numbers, assigned reps, 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.
after datetime string Yes Return only contacts created on or after this date/time. Invalid or missing values cause a validation error.
before datetime string No Return only contacts created on or before this date/time. If omitted, no upper date limit is applied.
offset integer No Starting position for paginated results. Defaults to 0 if omitted or invalid.

Path Parameters

None.

Request Body

None.

cURL Example

curl -X GET "https://app.callproof.com/api/contacts/created/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&after=2024-01-01"

Successful Response (200)

Returns a paginated list of contacts created within the requested date range. Up to 100 contacts are returned per request. If more matching contacts exist, more is set to 1 so the caller can request the next page using offset.

Field Type Description
results array List of contact objects (maximum 100 per response).
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.
more integer 1 if additional matching contacts remain; 0 if this is the last page.
offset integer Offset value used for this request.
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: 

{
  "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"
        }
      ]
    }
  ],
  "more": 0,
  "offset": 0,
  "errors": [],
  "code": 200
}

Error Responses

Status Code Meaning
400 Bad Request – The required after parameter is missing or cannot be interpreted as a valid date/time.
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 'after' 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:Contacts:Created&oldid=2270"