API:Contact:New

API » Create Contact

Base URL

https://app.callproof.com

Endpoint

/api/contact/new/

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.

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 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 creation payload.
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 1 to mark the contact as unknown; otherwise 0.
contact.do_not_sms	integer	No	Set to 1 to disable SMS for the contact; otherwise 0.
contact.latitude	number	No	Geographic latitude.
contact.longitude	number	No	Geographic longitude.
contact.last_contacted	datetime string	No	Date and time of last contact.
contact.full_name	string	No	Full name value used for lead-related integrations. Maximum 32 characters.
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 -X POST "https://app.callproof.com/api/contact/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "contact": {
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Corp",
      "contact_type": "Prospect",
      "default_phone": {
        "phone_number": "5551234567",
        "phone_type": "Mobile"
      },
      "email": "john@acme.com",
      "city": "Austin",
      "state": "TX",
      "rep_ids": [456]
    }
  }'

Successful Response (200)

Indicates the contact was created successfully. The response returns the full new contact profile.

Field	Type	Description
results	object	Newly created 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 assigned to the contact.
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": [
      {
        "id": 1001,
        "phone_type": "Mobile",
        "phone_number": "5551234567",
        "contact_id": 789,
        "contact": "John Doe"
      }
    ],
    "created_by": "Jane Smith",
    "created_by_id": 456,
    "created_by_email": "rep@example.com",
    "contact_type": "Prospect",
    "title": "",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@acme.com",
    "address": "",
    "address2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "",
    "country": "",
    "website": "",
    "latitude": "",
    "longitude": "",
    "last_contacted": "",
    "default_phone": {},
    "account": "",
    "invoice": "",
    "unknown": 0,
    "assigned": 1,
    "do_not_sms": 0,
    "updated": "2024-06-15 14:30:00",
    "created": "2024-06-15 14:30: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
}

Notes

• first_name, last_name, company_name, contact_type, and a valid default_phone.phone_number are required to create a contact.
• If the company name does not already exist, a new company association is created for the contact.
• The contact type must match an existing type in your company.
• A valid default phone number is required. If it is missing, the request returns 401 with Phone Number is required.
• If other required fields are missing, the response may still return 200 with validation details in the errors array and an empty results object.
• If rep_ids is provided, each value must be numeric. Only representatives belonging to your company are applied.
• If your company is configured for single sales representative mode, only one representative can remain assigned.
• For contacts created with the Facebook Leads 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

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 errors array and may return an empty results object.
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.
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 example:

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

401 response body examples:

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

{
  "results": [],
  "errors": ["Phone Number is required."],
  "code": 401
}

405 response body example:

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}