Difference between revisions of "API:Contact:Files:New"

From docs
Jump to: navigation, search
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
−
== [[API]] » New Contact ==
+
== [[API]] » Add Contact File ==
−
 
 
−
We already covered this earlier; here’s a refreshed version of `api/contact/new/` with the Notes section included.
 
  
 
=== Base URL ===
 
=== Base URL ===
Line 7: Line 5:
  
 
=== Endpoint ===
 
=== Endpoint ===
−
/api/contact/new/
+
/api/contact/files/new/
  
 
=== Purpose ===
 
=== Purpose ===
−
Creates a new contact in your CallProof company. Use this to add a contact with core profile details, a default phone number, company association, contact type, and optional sales representative assignments.
+
Uploads a file and associates it with a specific contact. The file can optionally be shared with selected users in the same CallProof company.
  
 
=== HTTP Method ===
 
=== HTTP Method ===
Line 23: Line 21:
  
 
=== Security ===
 
=== Security ===
−
* '''Yes''' – Requires a valid API key and secret with permission to create contacts. Credentials are sent in the request body.
+
* '''Yes''' – Requires valid API credentials with permission to create contact records.
  
 
=== Parameters ===
 
=== Parameters ===
Line 37: Line 35:
 
! Parameter !! Type !! Required !! Description
 
! Parameter !! Type !! Required !! Description
 
|-
 
|-
−
| api_key || object || Yes || Authentication credentials object.
+
| api_key || object || Yes || Authentication credentials.
 
|-
 
|-
−
| api_key.key || string || Yes || Public API key assigned to your CallProof account.
+
| api_key.key || string || Yes || Public API key assigned to the CallProof account.
 
|-
 
|-
 
| api_key.secret || string || Yes || Private API secret paired with the API key.
 
| api_key.secret || string || Yes || Private API secret paired with the API key.
 
|-
 
|-
−
| contact || object || Yes || Contact creation payload.
+
| files_data || object || Yes || File upload details.
−
|-
 
−
| contact.first_name || string || Yes || Contact first name. Maximum 32 characters.
 
−
|-
 
−
| contact.last_name || string || Yes || Contact last name. Maximum 32 characters.
 
−
|-
 
−
| contact.company_name || string || Yes || Associated company name. Maximum 64 characters. If blank, the contact’s full name may be used.
 
−
|-
 
−
| contact.contact_type || string || Yes || Contact type name. Must match an existing contact type in your company.
 
−
|-
 
−
| contact.default_phone || object || Yes || Default phone number for the contact.
 
−
|-
 
−
| contact.default_phone.phone_number || string || Yes || Phone number digits. Must resolve to a valid number.
 
−
|-
 
−
| contact.default_phone.phone_type || string || No || Phone type name (for example, Mobile or Office). Required for the default phone to be saved.
 
−
|-
 
−
| contact.rep_ids || array of integers || No || User IDs of sales representatives to assign to the contact. Each value must be numeric.
 
−
|-
 
−
| contact.title || string || No || Contact title. Maximum 64 characters.
 
−
|-
 
−
| contact.email || string || No || Contact email address. Maximum 64 characters.
 
−
|-
 
−
| contact.website || string || No || Website URL. Maximum 255 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.
 
−
|-
 
−
| contact.state || string || No || State or province abbreviation (up to 2 characters).
 
−
|-
 
−
| 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.unknown || integer || No || Set to <code>1</code> to mark the contact as unknown; otherwise <code>0</code>.
 
−
|-
 
−
| contact.do_not_sms || integer || No || Set to <code>1</code> to disable SMS for the contact; otherwise <code>0</code>.
 
 
|-
 
|-
−
| contact.latitude || number || No || Geographic latitude.
+
| files_data.contact_id || integer || Yes || Identifier of the contact to associate with the file. The contact must belong to the authenticated company.
 
|-
 
|-
−
| contact.longitude || number || No || Geographic longitude.
+
| files_data.file || string || Yes || Base64-encoded file contents.
 
|-
 
|-
−
| contact.last_contacted || datetime string || No || Date and time of last contact.
+
| files_data.file_name || string || Yes || Name under which the file will be stored.
 
|-
 
|-
−
| contact.full_name || string || No || Full name value used for lead-related integrations. Maximum 32 characters.
+
| files_data.user_ids || array of integers || No || User identifiers with whom the file should be shared. Defaults to an empty list.
−
|-
 
−
| contact.ad_name || string || No || Advertisement name for lead-related integrations. Maximum 64 characters.
 
−
|-
 
−
| contact.adset_name || string || No || Ad set name for lead-related integrations. Maximum 64 characters.
 
−
|-
 
−
| contact.campaign_name || string || No || Campaign name for lead-related integrations. Maximum 64 characters.
 
 
|}
 
|}
  
 
=== cURL Example ===
 
=== cURL Example ===
 
<pre>
 
<pre>
−
curl -X POST "https://app.callproof.com/api/contact/new/" \
+
curl -X POST "https://app.callproof.com/api/contact/files/new/" \
 
   -H "Content-Type: application/json" \
 
   -H "Content-Type: application/json" \
 
   -d '{
 
   -d '{
Line 111: Line 61:
 
       "secret": "YOUR_API_SECRET"
 
       "secret": "YOUR_API_SECRET"
 
     },
 
     },
−
     "contact": {
+
     "files_data": {
−
       "first_name": "John",
+
       "contact_id": 789,
−
       "last_name": "Doe",
+
       "file": "JVBERi0xLjQKJc...",
−
      "company_name": "Acme Corp",
+
       "file_name": "proposal.pdf",
−
      "contact_type": "Prospect",
+
       "user_ids": []
−
       "default_phone": {
 
−
        "phone_number": "5551234567",
 
−
        "phone_type": "Mobile"
 
−
      },
 
−
      "email": "john@acme.com",
 
−
      "city": "Austin",
 
−
      "state": "TX",
 
−
       "rep_ids": [456]
 
 
     }
 
     }
 
   }'
 
   }'
Line 129: Line 71:
  
 
=== Successful Response (200) ===
 
=== Successful Response (200) ===
−
Indicates the contact was created successfully. The response returns the full new contact profile.
+
Indicates that the file was uploaded and associated with the specified contact. The response contains the uploaded file and its sharing details.
  
 
{| class="wikitable"
 
{| class="wikitable"
 
! Field !! Type !! Description
 
! Field !! Type !! Description
 
|-
 
|-
−
| results || object || Newly created contact details.
+
| results || array || Uploaded file records.
 
|-
 
|-
−
| results.id || integer || Unique identifier for the contact.
+
| results[].user_file_id || integer || Unique identifier of the uploaded file.
 
|-
 
|-
−
| results.company || string || Name of the contact company associated with the contact.
+
| results[].name || string || Stored file name.
 
|-
 
|-
−
| results.contact_phones || array || Phone numbers associated with the contact.
+
| results[].rep || object or null || Profile of the user who uploaded the file.
 
|-
 
|-
−
| results.created_by || string || Display name of the user who created the contact.
+
| results[].rep.id || integer || Uploader’s profile identifier.
 
|-
 
|-
−
| results.created_by_id || integer || User ID of the person who created the contact.
+
| results[].rep.email || string || Uploader’s email address.
 
|-
 
|-
−
| results.created_by_email || string || Email address of the person who created the contact.
+
| results[].rep.user_id || integer || Uploader’s user identifier.
 
|-
 
|-
−
| results.contact_type || string || Contact type name.
+
| results[].rep.fullname || string || Uploader’s full name.
 
|-
 
|-
−
| results.title || string || Contact title.
+
| results[].rep.title || string || Uploader’s job title.
 
|-
 
|-
−
| results.first_name || string || Contact first name.
+
| results[].rep.updated || string || Date and time the uploader’s profile was last updated.
 
|-
 
|-
−
| results.last_name || string || Contact last name.
+
| results[].url || string || URL from which the file can be accessed.
 
|-
 
|-
−
| results.email || string || Contact email address.
+
| results[].is_shared || string || <code>1</code> when shared with at least one user; otherwise <code>0</code>.
 
|-
 
|-
−
| results.address || string || Primary street address.
+
| results[].reps || array || Profiles of users with whom the file is shared.
 
|-
 
|-
−
| results.address2 || string || Secondary street address.
+
| results[].updated || string || Date and time the file record was last updated (<code>YYYY-MM-DD HH:MM:SS</code>).
 
|-
 
|-
−
| results.city || string || City.
+
| results[].created || string || Date and time the file record was created (<code>YYYY-MM-DD HH:MM:SS</code>).
 
|-
 
|-
−
| results.state || string || State or province name.
+
| errors || object || Empty object when the request succeeds.
 
|-
 
|-
−
| results.zip || string || Postal/ZIP code.
+
| code || integer || Response status value; <code>200</code> on success.
−
|-
 
−
| 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": [
 +
    {
 +
      "user_file_id": 501,
 +
      "name": "proposal.pdf",
 +
      "rep": {
 +
        "id": 123,
 +
        "email": "rep@example.com",
 +
        "user_id": 456,
 +
        "fullname": "Jane Smith",
 +
        "title": "Account Executive",
 +
        "updated": "2024-06-01 10:00:00"
 +
      },
 +
      "url": "/user_files/ab/cd/ef/gh/abcdef...",
 +
      "is_shared": "0",
 +
      "reps": [],
 +
      "updated": "2024-06-15 14:30:00",
 +
      "created": "2024-06-15 14:30:00"
 +
    }
 +
  ],
 +
  "errors": {},
 +
  "code": 200
 +
}
 +
</pre>
  
 
=== Notes ===
 
=== Notes ===
−
* <code>first_name</code>, <code>last_name</code>, <code>company_name</code>, <code>contact_type</code>, and a valid <code>default_phone.phone_number</code> are required to create a contact.
+
* File contents must be Base64 encoded before being placed in <code>files_data.file</code>.
−
* If the company name does not already exist, a new company association is created for the contact.
+
* The specified contact must belong to the authenticated company.
−
* The contact type must match an existing type in your company.
+
* The authenticated user is recorded as the file uploader.
−
* A valid default phone number is required. If it is missing, the request returns <code>401</code> with <code>Phone Number is required.</code>
+
* <code>user_ids</code> is optional. If omitted, the file is not shared with other users.
−
* If other required fields are missing, the response may still return <code>200</code> with validation details in the <code>errors</code> array and an empty <code>results</code> object.
+
* Only users belonging to the authenticated company are added to the sharing list.
−
* If <code>rep_ids</code> is provided, each value must be numeric. Only representatives belonging to your company are applied.
+
* Invalid, unknown, or out-of-company values in <code>user_ids</code> are skipped without producing an error.
−
* If your company is configured for single sales representative mode, only one representative can remain assigned.
+
* This endpoint accepts one file per request.
−
* For contacts created with the <code>Facebook Leads</code> contact type, additional location and store-assignment behavior may apply based on ZIP code and state.
 
−
* If latitude and longitude are not supplied, location details may be determined automatically for certain lead types.
 
  
 
=== Error Responses ===
 
=== Error Responses ===
Line 218: Line 151:
 
! Status Code !! Meaning
 
! Status Code !! Meaning
 
|-
 
|-
−
| 200 || Validation issue – Required fields such as first name, last name, company name, or contact type are missing or invalid. The response includes an <code>errors</code> array and may return an empty <code>results</code> object.
+
| 400 || Bad Request – The JSON payload is invalid or the required file details are missing or invalid.
 
|-
 
|-
−
| 401 || Unauthorized – The API credentials are missing, invalid, inactive, associated with a disabled account, lack permission to create contacts, or the phone number is missing.
+
| 401 || Unauthorized – The API credentials are missing, invalid, inactive, associated with a disabled account, or lack permission to create contact records.
 
|-
 
|-
 
| 405 || Method Not Allowed – A method other than POST was used.
 
| 405 || Method Not Allowed – A method other than POST was used.
 
|-
 
|-
−
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
+
| 500 || Internal Server Error – The file could not be decoded or saved, or another unexpected problem occurred. Not specified in Swagger.
 
|}
 
|}
  
−
'''200 validation response example:'''
+
'''400 invalid JSON response example:'''
 
<pre>
 
<pre>
 
{
 
{
−
   "results": {},
+
   "results": [],
−
   "errors": [
+
   "errors": ["Invalid json data"],
−
    {"first_name": "required field"},
+
   "code": 400
−
    {"contact_type": "required field"}
 
−
  ],
 
−
   "code": 200
 
 
}
 
}
 
</pre>
 
</pre>
  
−
'''401 response body examples:'''
+
'''200 field-validation response example:'''
 
<pre>
 
<pre>
 
{
 
{
 
   "results": [],
 
   "results": [],
−
   "errors": ["Invalid API Key"],
+
   "errors": {
−
   "code": 401
+
    "contact_id": ["Invalid 'contact' field"],
 +
    "file": ["Invalid 'file' field"]
 +
  },
 +
   "code": 200
 
}
 
}
 
</pre>
 
</pre>
  
 +
'''401 response example:'''
 
<pre>
 
<pre>
 
{
 
{
 
   "results": [],
 
   "results": [],
−
   "errors": ["Phone Number is required."],
+
   "errors": ["Invalid API Key"],
 
   "code": 401
 
   "code": 401
 
}
 
}
 
</pre>
 
</pre>
  
−
'''405 response body example:'''
+
'''405 response example:'''
 
<pre>
 
<pre>
 
{
 
{

Latest revision as of 11:05, 17 July 2026

API » Add Contact File

Base URL

https://app.callproof.com

Endpoint

/api/contact/files/new/

Purpose

Uploads a file and associates it with a specific contact. The file can optionally be shared with selected users in the same CallProof company.

HTTP Method

POST

Headers

Header Required Description
Content-Type Yes Must be application/json.

Security

  • Yes – Requires valid API credentials with permission to create contact records.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

Parameter Type Required Description
api_key object Yes Authentication credentials.
api_key.key string Yes Public API key assigned to the CallProof account.
api_key.secret string Yes Private API secret paired with the API key.
files_data object Yes File upload details.
files_data.contact_id integer Yes Identifier of the contact to associate with the file. The contact must belong to the authenticated company.
files_data.file string Yes Base64-encoded file contents.
files_data.file_name string Yes Name under which the file will be stored.
files_data.user_ids array of integers No User identifiers with whom the file should be shared. Defaults to an empty list.

cURL Example

curl -X POST "https://app.callproof.com/api/contact/files/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "files_data": {
      "contact_id": 789,
      "file": "JVBERi0xLjQKJc...",
      "file_name": "proposal.pdf",
      "user_ids": []
    }
  }'

Successful Response (200)

Indicates that the file was uploaded and associated with the specified contact. The response contains the uploaded file and its sharing details.

Field Type Description
results array Uploaded file records.
results[].user_file_id integer Unique identifier of the uploaded file.
results[].name string Stored file name.
results[].rep object or null Profile of the user who uploaded the file.
results[].rep.id integer Uploader’s profile identifier.
results[].rep.email string Uploader’s email address.
results[].rep.user_id integer Uploader’s user identifier.
results[].rep.fullname string Uploader’s full name.
results[].rep.title string Uploader’s job title.
results[].rep.updated string Date and time the uploader’s profile was last updated.
results[].url string URL from which the file can be accessed.
results[].is_shared string 1 when shared with at least one user; otherwise 0.
results[].reps array Profiles of users with whom the file is shared.
results[].updated string Date and time the file record was last updated (YYYY-MM-DD HH:MM:SS).
results[].created string Date and time the file record was created (YYYY-MM-DD HH:MM:SS).
errors object Empty object when the request succeeds.
code integer Response status value; 200 on success.

Example response: 

{
  "results": [
    {
      "user_file_id": 501,
      "name": "proposal.pdf",
      "rep": {
        "id": 123,
        "email": "rep@example.com",
        "user_id": 456,
        "fullname": "Jane Smith",
        "title": "Account Executive",
        "updated": "2024-06-01 10:00:00"
      },
      "url": "/user_files/ab/cd/ef/gh/abcdef...",
      "is_shared": "0",
      "reps": [],
      "updated": "2024-06-15 14:30:00",
      "created": "2024-06-15 14:30:00"
    }
  ],
  "errors": {},
  "code": 200
}

Notes

  • File contents must be Base64 encoded before being placed in files_data.file.
  • The specified contact must belong to the authenticated company.
  • The authenticated user is recorded as the file uploader.
  • user_ids is optional. If omitted, the file is not shared with other users.
  • Only users belonging to the authenticated company are added to the sharing list.
  • Invalid, unknown, or out-of-company values in user_ids are skipped without producing an error.
  • This endpoint accepts one file per request.

Error Responses

Status Code Meaning
400 Bad Request – The JSON payload is invalid or the required file details are missing or invalid.
401 Unauthorized – The API credentials are missing, invalid, inactive, associated with a disabled account, or lack permission to create contact records.
405 Method Not Allowed – A method other than POST was used.
500 Internal Server Error – The file could not be decoded or saved, or another unexpected problem occurred. Not specified in Swagger.

400 invalid JSON response example: 

{
  "results": [],
  "errors": ["Invalid json data"],
  "code": 400
}

200 field-validation response example: 

{
  "results": [],
  "errors": {
    "contact_id": ["Invalid 'contact' field"],
    "file": ["Invalid 'file' field"]
  },
  "code": 200
}

401 response example: 

{
  "results": [],
  "errors": ["Invalid API Key"],
  "code": 401
}

405 response example: 

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}
Retrieved from "http://docs.callproof.com/index.php?title=API:Contact:Files:New&oldid=2233"