Difference between revisions of "API:Appointment:End"

From docs
Jump to: navigation, search
(Created page with "== API » Appointment End == '''URL:''' <nowiki>https://app.callproof.com/api/appts/end/</nowiki> '''Method:''' POST '''Required Fields:''' * '''''api_key[key]''''...")
 
 
Line 1: Line 1:
−
== [[API]] &#187; Appointment End ==
+
== [[API]] &#187; End Appointment (Check-Out) ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/appts/end/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/appts/end/
  
−
'''Required Fields:'''
+
=== 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.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''end_appointment_data[who]''''' - Who did you meet with? ('contact', 'else')
 
−
* '''''end_appointment_data[contact_type]''''' - Contact custom contact type (https://app.callproof.com/contact_types/)
 
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
* '''''end_appointment_data[first_name]''''' - Contact first name
+
=== Security ===
−
* '''''end_appointment_data[last_name]''''' - Contact last name
+
* '''Yes''' – Requires valid API credentials with permission to create appointments.
−
* '''''end_appointment_data[email]''''' - Contact email address (e.g. fred@aol.com)
 
−
* '''''end_appointment_data[title]''''' - Contact title (e.g. CEO)
 
−
* '''''end_appointment_data[account]''''' - Contact account number (e.g. 123456)
 
−
* '''''end_appointment_data[notes]''''' - Notes for contact and appointment
 
−
* '''''end_appointment_data[phone_number]''''' - Contact phone number
 
−
* '''''end_appointment_data[contact_phone_id]''''' - Contact phone id [[API:Contact Phones:Updated|https://app.callproof.com/api/contact_phones/updated/]]
 
−
* '''''end_appointment_data[latitude]''''' - Latitude for appointment
 
−
* '''''end_appointment_data[longitude]''''' - Longitude for appointment
 
−
* '''''end_appointment_data[followup]''''' - Set to '1' if Followup else '0'
 
−
* '''''end_appointment_data[followup_datetime]''''' -  Followup date time (e.g. '2014-08-10 12:34:56')
 
  
 +
=== Parameters ===
  
−
'''Data Returned:'''
+
==== Path Parameters ====
 +
None.
  
−
* '''''results''''' - Appointment details
+
==== Query Parameters ====
−
* '''''errors''''' - Array of errors produced by the request
+
None.
−
* '''''code''''' - HTTP request status
+
 
 +
==== Request Body ====
 +
{| class="wikitable"
 +
! 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 <code>contact</code> 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 <code>1</code> 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 <code>1</code> 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 <code>followup</code> is <code>1</code>.
 +
|-
 +
| end_appointment_data.calendar || integer || No || Set to <code>1</code> to send the created follow-up to the connected calendar.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
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."
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the active appointment was completed successfully. The response returns the completed appointment, including its calculated duration and check-out details.
 +
 
 +
{| class="wikitable"
 +
! 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 || <code>0</code> for a check-in appointment; <code>1</code> for a scheduled appointment.
 +
|-
 +
| errors || object || Empty object when the request succeeds.
 +
|-
 +
| code || integer || Response status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "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
 +
}
 +
</pre>
 +
 
 +
=== 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 <code>who=contact</code> updates the existing contact. Other values may create a new contact under the appointment’s associated company.
 +
* When <code>cmpy_wide</code> is <code>1</code>, the note is also added to other contacts associated with the same company.
 +
* A follow-up is created only when <code>followup</code> is <code>1</code> and <code>followup_datetime</code> is valid.
 +
* The check-out location is recorded when latitude and longitude are provided.
 +
* The response may leave <code>stop</code> empty even though the appointment has been completed; duration and updated time indicate completion.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! 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:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid json data"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["None appointment found running"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
'''401 response example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid API Key"],
 +
  "code": 401
 +
}
 +
</pre>
 +
 
 +
'''405 response example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Method not allowed"],
 +
  "code": 405
 +
}
 +
</pre>

Latest revision as of 13:28, 17 July 2026

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
}
Retrieved from "http://docs.callproof.com/index.php?title=API:Appointment:End&oldid=2321"