API:Appointment:New

API » Create Appointment (Check-In)

Base URL

https://app.callproof.com

Endpoint

/api/appts/new/

Purpose

Starts a new in-progress appointment (check-in) for the authenticated API user against a specific contact. Use this to begin an onsite or mobile appointment visit. Only one in-progress appointment can be active for the user at a time.

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 appointments. 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.
appointment_data	object	Yes	Appointment creation payload.
appointment_data.contact_id	integer	Yes	Unique identifier of the contact for the appointment. Must belong to your company.
appointment_data.start_time	datetime string	No	Appointment start date/time. If omitted or invalid, the current date/time is used.
appointment_data.latitude	string or number	No	Geographic latitude for the check-in location.
appointment_data.longitude	string or number	No	Geographic longitude for the check-in location.

cURL Example

curl -X POST "https://app.callproof.com/api/appts/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "appointment_data": {
      "contact_id": 789,
      "start_time": "2024-06-15 14:30:00",
      "latitude": "30.2672",
      "longitude": "-97.7431"
    }
  }'

Successful Response (200)

Indicates the in-progress appointment was created successfully. The response returns the new appointment details.

Field	Type	Description
results	object	Newly created appointment details.
results.id	integer	Unique identifier for the appointment.
results.rep_id	integer	User ID of the sales representative assigned to the appointment.
results.rep	string	Display name of the assigned sales representative.
results.rep_email	string	Email address of the assigned sales representative.
results.contact_id	integer	Associated contact identifier.
results.contact	string	Contact display name.
results.start	string	Appointment start date/time (YYYY-MM-DD HH:MM:SS).
results.stop	string	Appointment end date/time, or empty while the appointment is still in progress.
results.updated	string	Date and time the appointment was last updated.
results.created	string	Date and time the appointment was created.
results.latitude	string	Geographic latitude for the appointment location.
results.longitude	string	Geographic longitude for the appointment location.
results.distance	number or string	Distance in miles from the appointment location, when available.
results.duration	integer	Appointment duration. Typically 0 while the appointment is still in progress.
results.notes	string	Appointment notes.
results.title	string	Appointment title.
results.address	string	Appointment address.
results.scheduled	string	0 for an in-progress check-in appointment; 1 for a scheduled appointment.
errors	object	Empty object when the request succeeds.
code	integer	HTTP-style 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 14:30:00",
    "created": "2024-06-15 14:30:00",
    "latitude": "30.2672",
    "longitude": "-97.7431",
    "distance": "",
    "duration": 0,
    "notes": "",
    "title": "",
    "address": "",
    "scheduled": "0"
  },
  "errors": {},
  "code": 200
}

Notes

• This endpoint starts an in-progress appointment check-in; it does not create a future scheduled appointment.
• Only one in-progress appointment can be active for the authenticated user at a time.
• If an in-progress appointment already exists, the request is rejected.
• The contact must belong to your company.
• If start_time is omitted or invalid, the current date/time is used.
• Latitude and longitude are optional. When valid location values are provided, they are stored with the appointment.
• Creating the appointment updates the contact’s last-contacted time and associates the authenticated user as a sales representative on the contact when applicable.
• Use /api/appts/end/ to complete an in-progress appointment.

Error Responses

Status Code	Meaning
400	Bad Request – The JSON is invalid, the contact is invalid, the appointment could not be saved, or an appointment is already running for the user.
401	Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create appointments.
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 examples:

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

{
  "results": [],
  "errors": ["Invalid 'contact' field"],
  "code": 400
}

{
  "results": [],
  "errors": ["Appointment is already running"],
  "code": 400
}

401 response body example:

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

405 response body example:

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