Kickserv APIv2 - tasks

This documentation is neither written nor endorsed by Kickserv. Use at your own risk.

/tasks.json

GET POST

GET paginated tasks for the account. Tasks generally contain glue records for the job, customer, primary contact (if defined for the customer), and employees assigned to the task.

POST a new task. See /jobs/{id}/tasks.json for a detailed description of creating a new task.

Ex. GET /tasks.json retrieves paginated tasks for the entire account.

Ex. GET /tasks.json?job_id=34769012 retrieves tasks only for job ID 34769012.

Ex. GET /tasks.json?from=2021-02-17&to=2021-02-18 retrieves tasks between February 17, 2021 and February 18, 2021.

Note that the from and to arguments don't seem to be inclusive. If you're asking for tasks between August 10 and August 15 and one job has an event that starts on August 15 it will NOT be included in the return. In this case, you would need to set the end date to August 16.

Ex. GET /tasks.json?from=2021-08-13&to=2021-08-14&mapping=true&employee_number=4 retrieves the tasks for that employee, for that date range as they would be shown on the map.

Ex. POST See /jobs/{id}/tasks.json for a detailed example. Testing has not shown any difference between creating new tasks using /tasks.json or /jobs/{id}/tasks.json.

/tasks/{id}.json

GET PUT DELETE

GET a specific task as defined by the supplied task ID. Tasks generally contain glue records for the job, customer, primary contact (if defined for the customer), and employees assigned to the task.

PUT a change to a specific task as defined by the supplied task ID. Multiple changes can be made in a single query. Returns a task object containing a job and a customer glue record.

DELETE a specific task as defined by the supplied task ID. The task's object containing 'job' and 'customer' glue records is returned.

Ex. GET /tasks/2357911.json retrieves task 2357911.

Ex. PUT {task:{description:"A new description", ends_at: “2021-03-05T12:15:00-05:00”}} /tasks/2357911.json changes the description and end time of task 2357911.

Ex. DELETE /tasks/2357911.json deletes task 2357911 and returns it.

Changing the duration of a task will not change the ends_at field of a task, but changing the ends_at will change the duration. Attempting to change the duration will silently fail.

/tasks/{id}/notify.json

POST

POST a notification for a task defined by the supplied task ID.

Ex. POST /tasks/123654789/notify.json notifies the employee assigned to task 123654789.

Ex. POST {notification_type:"details"} /tasks/123654789/notify.json sends an event reminder to the customer for the job associated with task 123654789.

Ex. POST {notification_type:"on_the_way"} /tasks/123654789/notify.json sends a notification to the customer of the job associated with task 123654789 that the employee assigned to the task is on the way.

This endpoint requires the "notify customer" permission. If a customer has had an email bounce they will not receive it unless the email address is reactivated first. SMS notifications are sent to the number recorded in the customer’s notification_phone_number field.

/tasks/job_list.json

GET

GET a shortened list of all active jobs/opps for a customer.

Ex. GET /tasks/job_list.json?customer_id=13579 gets a shortened list of active opps/jobs for customer with ID 13579.

An example return:

[
  {
    "id": 1122334455,
    "name": "Opportunity #24601: Tracking",
    "status": "new"
  },
  {
    "id": 1122334466,
    "name": "Opportunity #1701: Exploration",
    "status": "estimate_viewed"
  }
]
Note that this endpoint expects the customer ID, not the customer number. Jobs/opps that are returned are only marked as 'Opportunity' or 'Job' in the 'name' key. Otherwise, look at the status and determine that way which type it is.
Moving along, the next section is...the rest!