API:Followup:Create

API » Create Follow-Up

Base URL

https://app.callproof.com

Endpoint

/api/followup/new/

Purpose

Creates a new follow-up activity for a contact in your CallProof company. Use this to schedule a future task or reminder for a sales representative, with optional notes and completion status.

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 follow-ups. 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.
followup	object	Yes	Follow-up creation payload.
followup.contact_id	integer	Yes	Unique identifier of the contact for the follow-up. Must belong to your company.
followup.start_datetime	datetime string	Yes	Date and time when the follow-up should begin.
followup.notes	string	No	Follow-up notes. Certain special characters are removed.
followup.duration	integer	No	Follow-up duration in minutes. Defaults to 30 minutes if omitted or invalid.
followup.completed	integer	No	Set to 1 to create the follow-up as completed; otherwise it is created as incomplete.
followup.rep_id	integer	No	User ID of the sales representative to assign. Applied only when the authenticated API user is a manager. Otherwise the authenticated user is assigned.

cURL Example

curl -X POST "https://app.callproof.com/api/followup/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "followup": {
      "contact_id": 789,
      "start_datetime": "2024-06-20 10:00:00",
      "duration": 30,
      "notes": "Call to discuss proposal",
      "completed": 0
    }
  }'

Successful Response (200)

Indicates the follow-up was created successfully. The response returns the new follow-up details.

Field	Type	Description
results	object	Newly created follow-up details.
results.id	integer	Unique identifier for the follow-up.
results.rep	object	Sales representative associated with the follow-up.
results.rep.id	integer	Rep profile identifier.
results.rep.email	string	Rep email address.
results.rep.user_id	integer	Associated user account identifier.
results.rep.name	string	Rep display name.
results.rep.title	string	Rep job title.
results.rep.updated	string	Date and time the rep profile was last updated.
results.contact_id	integer	Associated contact identifier.
results.contact	string	Contact display name.
results.start_date	string	Follow-up start date/time (YYYY-MM-DD HH:MM:SS).
results.duration	number	Follow-up duration in minutes.
results.completed	string	1 if completed; otherwise 0.
results.notes	string	Follow-up notes.
results.created	string	Date and time the follow-up was created (YYYY-MM-DD HH:MM:SS).
results.updated	string	Date and time the follow-up was last updated (YYYY-MM-DD HH:MM:SS).
errors	object	Empty object when the request succeeds.
code	integer	HTTP-style status value; 200 on success.

Example response:

{
  "results": {
    "id": 7001,
    "rep": {
      "id": 123,
      "email": "rep@example.com",
      "user_id": 456,
      "name": "Jane Smith",
      "title": "Account Executive",
      "updated": "2024-06-01 10:00:00"
    },
    "contact_id": 789,
    "contact": "John Doe",
    "start_date": "2024-06-20 10:00:00",
    "duration": 30.0,
    "completed": "0",
    "notes": "Call to discuss proposal",
    "id": 7001,
    "created": "2024-06-15 14:30:00",
    "updated": "2024-06-15 14:30:00"
  },
  "errors": {},
  "code": 200
}

Notes

• contact_id and start_datetime are required.
• The contact must belong to your company.
• Non-manager users are always assigned as the follow-up owner; managers may assign another sales representative via rep_id.
• duration is supplied in minutes and returned in minutes. Internally, the stored follow-up duration is converted from minutes.
• If duration is omitted or invalid, it defaults to 30 minutes.
• completed=1 creates the follow-up as completed; all other values create it as incomplete.
• Creating a follow-up associates the authenticated user with the contact when applicable.
• Field-level validation failures typically return HTTP 200 with details in the errors object and an empty results object.
• Invalid JSON in the request body returns HTTP 400.

Error Responses

Status Code	Meaning
200	Validation issue – The contact ID or start date/time is missing or invalid. Details are provided in the errors object.
400	Bad Request – The JSON payload is invalid or required follow-up data is missing.
401	Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create follow-ups.
405	Method Not Allowed – A method other than POST was used.
500	Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

400 response body example:

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

200 validation response example:

{
  "results": {},
  "errors": {
    "contact_id": "Invalid 'contact' field",
    "start": "Invalid 'start datetime' field"
  },
  "code": 200
}

401 response body example:

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

405 response body example:

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