Kickserv APIv2 - customers

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

/customers.json

GET
Returns an array of customers in bulk, paginated. Can be filtered with additional parameters such as, but not limited to:
  • customer_number=380
  • name=Weasels%20Inc
  • service_address=123%20Main%20Street%20SE (note that it’s URL-encoded)
  • q=ilf
  • customer_source_id=12345
  • begins_with=A
Parameters must be exact-match; wildcards are not permitted. To search by partial name use ?q= parameter. To search by a partial name or address see /customers/filter.json. Purely to validate a full name exists, see /customers/customer_validation.json.

Ex. GET /customers.json?service_state=MI returns all customers (paginated) in the state of Michigan

Ex. GET /customers.json?q=ilf returns all customers with 'ilf' in the name (name only)

Ex. GET /customers.json?customer_source_id=12345 returns paginated customers by customer source 12345

Ex. GET /customers.json?begins_with=C&customers_page=6 returns page 6 of paginated customers whose name begins with 'C' (case-insensitive)

/customers/{id}.json

GET PUT DELETE
A specific customer, as defined by their customer number. This is the number seen in the web UI near a customer’s name. Unlike some DELETE operations, the customer record is NOT returned from this operation.

Ex. GET /customers/380.json returns customer number 380

Ex. PUT {customer:{name: "Samantha"} /customers/380.json changes customer 380’s name to Samantha

Ex. DELETE /customers/380.json deletes customer 380 and returns {message: "Customer successfully deleted"}

/customers/{id}/notes.json

GET POST
The customer-level notes for a specific customer. These are viewable from the customer’s page under the 'Notes & Files' tab and are always invisible to the customer, despite having a 'public' setting. Note objects at the job and customer level are indistinguishable except for one key, the noteable_type key. That key will be either 'Customer' or 'Job'. For job-level notes, see /jobs/{id}/notes.json.

Ex. GET /customers/380/notes.json returns an array of paginated notes for customer 380

Ex. POST {note:{note: "All sales NET-30"}} /customers/380/notes.json adds a note to customer 380. Notice that the payload is a 'note' object which contains another key named 'note' which is the actual text of the note itself. POST reply includes an employee object for the note’s creator under the 'creator' key.

/customers/{id}/notes/{id}.json

GET PUT DELETE
A specific note for a specific customer, as defined by their customer number and the note ID.

Ex. GET /customers/380/notes/24601.json returns note 24601 for customer 380

Ex. PUT {note:{note:"A new note body"} /customers/380/notes/24601.json changes the note body for notes 24601, which belongs to customer 380. The response to PUT is larger than a GET for the same note, and includes an employee object for the note’s creator under the ‘creator’ key.

Ex. DELETE /customers/380/notes/24601.json deletes note 24601 from customer 380

When DELETEing a note, the customer number does not have to match the customer for the note (e.g., in DELETE /customers/6/notes/5161.json, note 5161 wouldn’t have to belong to customer 6 and would still be deleted successfully even if another customer number was supplied). This is likely an oversight and will be corrected at some point. It should not be relied on.

/customers/{id}/payments.json

GET POST
Returns an array of all payments for a specific customer, as defined by their customer number.
Ex. /customers/380/payments.json returns all payments (paginated) for customer number 380
To retrieve payments for a specific job only, see /jobs/{id}/payments.json. To modify or delete existing payments see /jobs/{id}/payments/{id}.json. Payments can only be created using the /jobs/{id}/payments.json endpoint. A critical portion of the payment object, payment_application_ids, is automatically created if that endpoint is used, but it is not created if this one is used. The structure of the payment object suggests that it’s possible to apply a payment to more than one job, though that has not been tested.

/customers/{id}/payments/{id}.json

GET PUT DELETE
A specific payment for a specific customer, as defined by their customer number and the ID of the payment.
Ex. DELETE /customers/380/payments/24601.json deletes payment number 24601 belonging to customer number 380 and returns it
GET for this endpoint returns HTTP/204 No Content even if the payment exists, and HTTP/404 Not Found if it doesn’t. This behavior is different from other endpoints. Pagination follows the v3 methodology, and is contained inside a meta object. The structure of the payment object suggests that it’s possible to apply a payment to more than one job, though that has not been tested.

/customers/customer_validation.json

POST
Returns the customer whose name is the value supplied in the 'name' parameter. Case-sensitive. Note that since a customer's name is unique across your instance of Kickserv, it is not possible to have more than one match. This is NOT a way to search for customers whose name CONTAINS the search string. To search customers by name or substring of name, see /customers/filter.json.

Ex. POST {name : "Clarence"} /customers/customer_validation.json returns the customer whose name is 'Clarence'

On failure (no match) returns:

{status:"not found"}

On success (one match) returns:

{
    "status":"exist",
    "customer_url":"/SLUG/customers/14907",
    "customer_name":"Clarence",
    "customer":"{CUSTOMER OBJECT}
}

/customers/filter.json

GET
Returns an array of customers whose name contains, or is an exact match of, the 'name' parameter. Case-insensitive.

Ex. GET /customers/filter.json?name=obert returns all customers whose name contains 'obert'

On failure (no matches) returns an array with a empty customer object:

{
  "customers": [
    {
      "customer_number": null,
       ...truncated customer object...
    }
  ]
}

On success (one or more matches) returns:

"customers": [ one or more customer objects ]

The array contains a final empty customer object. If a query returns an array with size of 3, the customer at array index 2 will be effectively null and can be ignored.

/customers/{id}/jobs.json

GET POST
GET a paginated array of all jobs for a specific customer, as defined by their customer number. A 'status' or 'status[ ]' parameter will allow results to be filtered by one or more statuses.
POST to this endpoint to create a job for this customer. The 'job_type_id' field is the only required field for job creation, but other fields may be supplied as desired.

Ex. GET /customers/380/jobs.json returns all jobs for customer number 380

Ex. GET /customers/380/jobs.json?status=unscheduled returns all unscheduled jobs for customer number 380

Ex. GET /customers/380/jobs.json?status[]=unscheduled&status[]=complete returns all unscheduled or complete jobs for customer number 380

Ex. POST {job:{job_type_id:61, description: "Test job"}} /customers/6/jobs.json creates a job for customer 6 of type 61, with a description of 'Test Job'. Returns the newly-created job.

This endpoint is only for jobs, not opportunities. See /opportunities.json for retrieving opportunities, though the capabilities are not identical. Pulling opportunities for a specific customer requires the use of APIv3. See /jobs.json for another way to create jobs.

/customers/{id}/jobs/{id}.json

GET PUT DELETE
A specific job for a specific customer, as defined by their customer number and the job number. This can be used to retrieve either jobs or opportunities. To retrieve a job or opportunity without having to know the customer number, see /jobs/{id}.json.

Ex. GET /customers/380/jobs/617.json returns job number 617 belonging to customer number 380

Ex. PUT {job:{description:"A new description"}} /customers/380/jobs/617.json modifies the description of job number 617 belonging to customer number 380. Returns the updated job.

Ex. DELETE /customers/380/jobs/617.json will delete the job, and return it.

GET and PUT return objects with slightly different formats.
Ready to move on? Next we have jobs