Difference between revisions of "API:ContactPhone:New"

From docs
Jump to: navigation, search
 
Line 1: Line 1:
  
−
== [[API]] » New Contact Phone ==
+
== [[API]] » Create Contact Phone ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact_phone/new/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/contact_phone/new/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Creates a new phone number for an existing contact in your CallProof company. Use this to add phone details such as number, type, extension, status flags, eligibility dates, and related attributes.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''contact_phone[contact_id]''''' - Contact ID
 
−
* '''''contact_phone[phone_number]''''' - Contact Phone phone number (unique per contact)
 
−
* '''''contact_phone[phone_type]''''' - Contact Phone type (cell, home, office, fax, headquarters, other)
 
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
* '''''contact_phone[ext]''''' - Contact Phone extension (e.g. 123)
+
=== Security ===
−
* '''''contact_phone[dealer_store]''''' - Contact Phone dealer store name (https://app.callproof.com/stores/)
+
* '''Yes''' – Requires a valid API key and secret with permission to create contact phones. Credentials are sent in the request body.
−
* '''''contact_phone[call_result]''''' - Contact Phone last call result (https://app.callproof.com/call_results/)
 
−
* '''''contact_phone[unknown]''''' - Set to '1' if Contact Phone is unknown
 
−
* '''''contact_phone[hidden]''''' - Set to '1' if Contact Phone is hidden
 
−
* '''''contact_phone[do_not_call]''''' - Set to '1' if Contact phone is on DO NOT CALL list
 
−
* '''''contact_phone[last_contacted]''''' - Contact Phone last contacted date/time (e.g. '2014-08-10 12:34:56')
 
−
* '''''contact_phone[eligible]''''' - Contact Phone eligible for upgrade date/time (e.g. '2014-08-10 12:34:56')
 
−
* '''''contact_phone[activated]''''' - Contact Phone eligible for upgrade date/time (e.g. '2014-08-10 12:34:56')
 
−
* '''''contact_phone[model]''''' - Contact Phone model name
 
  
−
'''Data Returned:'''
+
=== Parameters ===
  
−
* '''''results''''' - Contact Phone
+
==== 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_phone || object || Yes || Contact phone creation payload.
 +
|-
 +
| contact_phone.contact_id || integer || Yes || Unique identifier of the contact that will own the new phone number. Must belong to your company.
 +
|-
 +
| contact_phone.phone_number || string || Yes || Phone number digits. Must resolve to a valid 10-digit number after normalization.
 +
|-
 +
| contact_phone.phone_type || string || Yes || Phone type name (for example, Mobile or Office). Must match a recognized phone type.
 +
|-
 +
| contact_phone.ext || string || No || Phone extension. Digits only; maximum 6 characters.
 +
|-
 +
| contact_phone.unknown || integer || No || Set to <code>1</code> to mark as unknown; otherwise <code>0</code>. Defaults to not unknown when omitted.
 +
|-
 +
| contact_phone.hidden || integer || No || Set to <code>1</code> to hide the phone; otherwise <code>0</code>. Defaults to not hidden when omitted.
 +
|-
 +
| contact_phone.do_not_call || integer || No || Set to <code>1</code> to enable do-not-call; otherwise <code>0</code>. Defaults to not do-not-call when omitted.
 +
|-
 +
| contact_phone.last_contacted || datetime string || No || Date and time this phone was last contacted.
 +
|-
 +
| contact_phone.eligible || datetime string || No || Eligibility date/time.
 +
|-
 +
| contact_phone.activated || datetime string || No || Activation date/time.
 +
|-
 +
| contact_phone.dealer_store || string || No || Dealer/store name. Applied only when it matches an existing store in your company. Maximum 255 characters.
 +
|-
 +
| contact_phone.model || string || No || Model value. Maximum 255 characters.
 +
|-
 +
| contact_phone.call_result || string || No || Call result name. Applied only when it matches an existing call result in your company. Maximum 255 characters.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/contact_phone/new/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "contact_phone": {
 +
      "contact_id": 789,
 +
      "phone_number": "5551234567",
 +
      "phone_type": "Mobile",
 +
      "do_not_call": 0
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the phone number was created successfully. The response returns the new phone details.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Newly created contact phone details.
 +
|-
 +
| results.id || integer || Unique identifier for the phone number.
 +
|-
 +
| results.last_contacted || string || Date and time this phone was last contacted.
 +
|-
 +
| results.unknown || integer || <code>1</code> if marked unknown; otherwise <code>0</code>.
 +
|-
 +
| results.do_not_call || integer || <code>1</code> if do-not-call is enabled; otherwise <code>0</code>.
 +
|-
 +
| results.contact_id || integer || Associated contact identifier.
 +
|-
 +
| results.contact || string || Contact display name.
 +
|-
 +
| results.phone_type || string || Phone type name.
 +
|-
 +
| results.phone_number || string || Phone number.
 +
|-
 +
| results.ext || string || Phone extension, if any.
 +
|-
 +
| results.activated || string || Activation date/time, if set.
 +
|-
 +
| results.eligible || string || Eligibility date/time, if set.
 +
|-
 +
| results.call_result || string || Last call result, if any.
 +
|-
 +
| results.hidden || integer || <code>1</code> if the phone is hidden; otherwise <code>0</code>.
 +
|-
 +
| results.dealer_store || string || Associated dealer/store name, if any.
 +
|-
 +
| results.model || string || Model value, if any.
 +
|-
 +
| results.updated || string || Date and time the phone record was last updated.
 +
|-
 +
| results.created || string || Date and time the phone record was created.
 +
|-
 +
| errors || array || Empty list when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "results": {
 +
    "id": 1001,
 +
    "last_contacted": "",
 +
    "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-06-15 14:30:00"
 +
  },
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* <code>contact_id</code>, a valid 10-digit <code>phone_number</code>, and a valid <code>phone_type</code> are required.
 +
* The contact must belong to your company.
 +
* Phone numbers are normalized to digits. An 11-digit number starting with <code>1</code> is treated as a U.S./Canada number and reduced to 10 digits.
 +
* A phone number that already exists for the same contact cannot be created again.
 +
* <code>dealer_store</code> and <code>call_result</code> are applied only when they match existing values in your company.
 +
* Creating a phone number also refreshes the parent contact’s last-updated timestamp.
 +
* Field-level validation failures typically return HTTP <code>200</code> with details in the <code>errors</code> array and an empty <code>results</code> object.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 200 || Validation issue – The phone number is missing/invalid, already exists for the contact, or the phone type is missing/invalid.
 +
|-
 +
| 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 create contact phones.
 +
|-
 +
| 405 || Method Not Allowed – A method other than POST was used.
 +
|-
 +
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
 +
|}
 +
 
 +
'''200 validation response examples:'''
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": [
 +
    {"phone_number": "required field"}
 +
  ],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": [
 +
    {"phone_number": "already exists"}
 +
  ],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": [
 +
    {"phone_type": "required field"}
 +
  ],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
'''400 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid 'contact_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 11:43, 17 July 2026

API » Create Contact Phone

Base URL

https://app.callproof.com

Endpoint

/api/contact_phone/new/

Purpose

Creates a new phone number for an existing contact in your CallProof company. Use this to add phone details such as number, type, extension, status flags, eligibility dates, and related attributes.

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 create contact phones. 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_phone object Yes Contact phone creation payload.
contact_phone.contact_id integer Yes Unique identifier of the contact that will own the new phone number. Must belong to your company.
contact_phone.phone_number string Yes Phone number digits. Must resolve to a valid 10-digit number after normalization.
contact_phone.phone_type string Yes Phone type name (for example, Mobile or Office). Must match a recognized phone type.
contact_phone.ext string No Phone extension. Digits only; maximum 6 characters.
contact_phone.unknown integer No Set to 1 to mark as unknown; otherwise 0. Defaults to not unknown when omitted.
contact_phone.hidden integer No Set to 1 to hide the phone; otherwise 0. Defaults to not hidden when omitted.
contact_phone.do_not_call integer No Set to 1 to enable do-not-call; otherwise 0. Defaults to not do-not-call when omitted.
contact_phone.last_contacted datetime string No Date and time this phone was last contacted.
contact_phone.eligible datetime string No Eligibility date/time.
contact_phone.activated datetime string No Activation date/time.
contact_phone.dealer_store string No Dealer/store name. Applied only when it matches an existing store in your company. Maximum 255 characters.
contact_phone.model string No Model value. Maximum 255 characters.
contact_phone.call_result string No Call result name. Applied only when it matches an existing call result in your company. Maximum 255 characters.

cURL Example

curl -X POST "https://app.callproof.com/api/contact_phone/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "contact_phone": {
      "contact_id": 789,
      "phone_number": "5551234567",
      "phone_type": "Mobile",
      "do_not_call": 0
    }
  }'

Successful Response (200)

Indicates the phone number was created successfully. The response returns the new phone details.

Field Type Description
results object Newly created contact phone details.
results.id integer Unique identifier for the phone number.
results.last_contacted string Date and time this phone was last contacted.
results.unknown integer 1 if marked unknown; otherwise 0.
results.do_not_call integer 1 if do-not-call is enabled; otherwise 0.
results.contact_id integer Associated contact identifier.
results.contact string Contact display name.
results.phone_type string Phone type name.
results.phone_number string Phone number.
results.ext string Phone extension, if any.
results.activated string Activation date/time, if set.
results.eligible string Eligibility date/time, if set.
results.call_result string Last call result, if any.
results.hidden integer 1 if the phone is hidden; otherwise 0.
results.dealer_store string Associated dealer/store name, if any.
results.model string Model value, if any.
results.updated string Date and time the phone record was last updated.
results.created string Date and time the phone record was created.
errors array Empty list when the request succeeds.
code integer HTTP-style status value; 200 on success.

Example response: 

{
  "results": {
    "id": 1001,
    "last_contacted": "",
    "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-06-15 14:30:00"
  },
  "errors": [],
  "code": 200
}

Notes

  • contact_id, a valid 10-digit phone_number, and a valid phone_type are required.
  • The contact must belong to your company.
  • Phone numbers are normalized to digits. An 11-digit number starting with 1 is treated as a U.S./Canada number and reduced to 10 digits.
  • A phone number that already exists for the same contact cannot be created again.
  • dealer_store and call_result are applied only when they match existing values in your company.
  • Creating a phone number also refreshes the parent contact’s last-updated timestamp.
  • Field-level validation failures typically return HTTP 200 with details in the errors array and an empty results object.

Error Responses

Status Code Meaning
200 Validation issue – The phone number is missing/invalid, already exists for the contact, or the phone type is missing/invalid.
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 create contact phones.
405 Method Not Allowed – A method other than POST was used.
500 Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

200 validation response examples: 

{
  "results": {},
  "errors": [
    {"phone_number": "required field"}
  ],
  "code": 200
}

{
  "results": {},
  "errors": [
    {"phone_number": "already exists"}
  ],
  "code": 200
}

{
  "results": {},
  "errors": [
    {"phone_type": "required field"}
  ],
  "code": 200
}

400 response body example: 

{
  "results": [],
  "errors": ["Invalid 'contact_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:ContactPhone:New&oldid=2247"