API:Appointment:End

API » End Appointment (Check-Out)

Base URL

https://app.callproof.com

Endpoint

/api/appts/end/

Purpose

Completes the authenticated user’s active appointment. During check-out, it can update contact details, record notes and location, update a phone number, and optionally schedule a follow-up activity.

HTTP Method

POST

Headers

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

Security

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

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.
end_appointment_data	object	Yes	Appointment check-out details.
end_appointment_data.contact_type	string	Yes	Contact type to apply. Must match an existing contact type in the company.
end_appointment_data.who	string	No	Use contact to update the appointment’s existing contact. Other or omitted values may create a new contact under the same associated company.
end_appointment_data.start	datetime string	No	Date/time recorded as the contact’s last-contacted time. Defaults to the current date/time if omitted or invalid.
end_appointment_data.notes	string	No	Appointment notes. Maximum 1,024 characters.
end_appointment_data.first_name	string	No	Contact first name. Maximum 32 characters.
end_appointment_data.last_name	string	No	Contact last name. Maximum 32 characters.
end_appointment_data.title	string	No	Contact title. Maximum 64 characters.
end_appointment_data.email	string	No	Contact email address.
end_appointment_data.website	string	No	Contact website. Maximum 255 characters.
end_appointment_data.account	string	No	Contact account identifier.
end_appointment_data.contact_phone_id	integer	No	Contact phone reference. Its effect is not specified in Swagger.
end_appointment_data.phone_id	integer	No	Identifier of an existing phone record to update.
end_appointment_data.phone_number	string	No	Phone number to associate with the contact. Non-numeric characters are removed.
end_appointment_data.cmpy_wide	string	No	Set to 1 to add the supplied note to other contacts associated with the same company.
end_appointment_data.latitude	string or number	No	Geographic latitude at check-out.
end_appointment_data.longitude	string or number	No	Geographic longitude at check-out.
end_appointment_data.followup	integer	No	Set to 1 to create a follow-up.
end_appointment_data.followup_datetime	datetime string	Conditional	Follow-up date/time. Required for a follow-up to be created when followup is 1.
end_appointment_data.calendar	integer	No	Set to 1 to send the created follow-up to the connected calendar.

cURL Example

curl -X POST "https://app.callproof.com/api/appts/end/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "end_appointment_data": {
      "contact_type": "Customer",
      "who": "contact",
      "notes": "Completed onsite visit."
    }
  }'

Successful Response (200)

Indicates the active appointment was completed successfully. The response returns the completed appointment, including its calculated duration and check-out details.

Field	Type	Description
results	object	Completed appointment details.
results.id	integer	Unique appointment identifier.
results.rep_id	integer	User ID of the assigned sales representative.
results.rep	string	Sales representative’s name.
results.rep_email	string	Sales representative’s email address.
results.contact_id	integer	Associated contact identifier.
results.contact	string	Contact display name.
results.start	string	Appointment start date/time.
results.stop	string	Appointment stop date/time, when available.
results.updated	string	Date and time the appointment was last updated.
results.created	string	Date and time the appointment was created.
results.latitude	string	Appointment latitude.
results.longitude	string	Appointment longitude.
results.distance	number or string	Calculated distance in miles, when available.
results.duration	integer	Completed appointment duration in seconds.
results.notes	string	Appointment notes.
results.title	string	Appointment title.
results.address	string	Appointment address.
results.scheduled	string	0 for a check-in appointment; 1 for a scheduled appointment.
errors	object	Empty object when the request succeeds.
code	integer	Response status value; 200 on success.

Example response:

{
  "results": {
    "id": 3001,
    "rep_id": 456,
    "rep": "Jane Smith",
    "rep_email": "rep@example.com",
    "contact_id": 789,
    "contact": "John Doe",
    "start": "2024-06-15 14:30:00",
    "stop": "",
    "updated": "2024-06-15 15:15:00",
    "created": "2024-06-15 14:30:00",
    "latitude": "30.2672",
    "longitude": "-97.7431",
    "distance": 2.5,
    "duration": 2700,
    "notes": "Completed onsite visit.",
    "title": "",
    "address": "",
    "scheduled": "0"
  },
  "errors": {},
  "code": 200
}

Notes

• The authenticated user must have an active, unfinished appointment.
• The contact type must match an existing contact type in the company.
• The appointment duration is calculated automatically when the appointment is ended.
• Using who=contact updates the existing contact. Other values may create a new contact under the appointment’s associated company.
• When cmpy_wide is 1, the note is also added to other contacts associated with the same company.
• A follow-up is created only when followup is 1 and followup_datetime is valid.
• The check-out location is recorded when latitude and longitude are provided.
• The response may leave stop empty even though the appointment has been completed; duration and updated time indicate completion.

Error Responses

Status Code	Meaning
400	Bad Request – The payload is invalid, no appointment is currently running, the contact type is invalid, or the appointment could not be completed.
401	Unauthorized – The API credentials are missing, invalid, inactive, associated with a disabled account, or lack permission to create appointments.
405	Method Not Allowed – A method other than POST was used.
500	Internal Server Error – An unexpected problem occurred. Not specified in Swagger.

400 response examples:

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

{
  "results": [],
  "errors": ["None appointment found running"],
  "code": 400
}

401 response example:

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

405 response example:

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