Authentication

All Kimoby API need to be authenticated using Basic Authentication and must be sent over HTTPS. Calls made over plain HTTP will fail. API request without authentication will also fail.

$ curl -s https://api.kimoby.com/v1/customers \
  -X GET \
  -H 'Accept:application/json' \
  -u {api_key}:{api_secret}

Errors

The API uses HTTP status code to indicate success or otherwise of API calls. The codes listed below are often used, and the API may use others. In most cases, status codes in the 2xx range indicate success, 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Kimoby’s servers.

All 4xx errors will return JSON in the format on the right.

Code Description
200 OK
201 Created
400 Bad request
401 Unauthorized
404 Not Found
429 Rate Limit Exceeded (API usage limit exceeded)
500, 502, 503, 504 Server Errors. Something went wrong on Kimoby’s end.
{
  "message": "error message here"
}

Date Format

Every date sent to the API must be formatted in RFC 3339 specification.

We recommend that you always send the date with time in UTC. The API can also take other time zones.

The API will always return dates in UTC.

2016-06-22T16:20:00+00:00

Pagination

Parameters
page
integer (greater than 0)
per_page
integer (greater than 0 and less or equals to 50)

Collection of resources are paginated. By default, 25 items per page are shown.

To browse different pages, or change the number of items per page (up to 50), use the page and per_page query parameters.

$ curl -s https://api.kimoby.com/v1/customers?page=1&per_page=25 \
  -X GET \
  -H 'Accept:application/json' \
  -u {api_key}:{api_secret}
{
  "customers": [
    "..."
  ],
  "pagination": {
    "page": 1,
    "pages": 1,
    "items": 10,
    "per_page": 25
  }
}

JSON Schemas

All API responses are matching a particular JSON Schema. You are using the draft version 4.

If you are new to JSON Schema a great place to start is website understanding-json-schema.

Customer Model

A customer object contains the following attributes. It matches the customer JSON schema.

Attribute Type Description
id String Unique string identifier. It is generated by Kimoby.
reference String Unique string identifier used in your system. It is case sensitive.
name String The name of the customer. It is required.
cell_phone_number String The cell phone number of the customer. It is required and must be in E.164 format.
email String The email of the customer. Must be a valid email address.
address String The address of the customer.
city String The city of the customer.
state String The state of the customer.
zipcode String The zipcode of the customer.
country String The country of the customer in ISO 3166-1 format.
is_unsubscribed Boolean The unsubscribed status of the customer. See unsubscribed Status section.
phones Object The phones of the customer. See Phones Model section.
custom_attributes Object The custom attributes of the customer. See Custom Attributes Model section.
created_at String The creation date of the customer. Date with time in RFC 3339 format.
updated_at String The last update date of the customer. Date with time in RFC 3339 format.
{
  "id": "cueeadfbacc5d64682bd20ac077d592e83",
  "reference": "CU000001",
  "name": "John Doe",
  "cell_phone_number": "+14182031234",
  "email": "johndoe@site.com",
  "address": "633 Saint-joseph E.",
  "city": "Quebec",
  "state": "QC",
  "zipcode": "G1K 3C1",
  "country": "CA",
  "is_unsubscribed": false,
  "phones": {
    "home": "5149873473",
    "work": "+1 (877) 247-9367",
    "other": "(418) 394-1928 x19119"
  },
  "custom_attributes": {
    "vehicle": "Audi",
    "vehicle_year": "2012",
    "last_visit_date": "2013-02-12T00:00:00+00:00",
    "product_names_array": [
      "Premium",
      "Lite"
    ]
  },
  "created_at": "2016-06-28T15:26:58+00:00",
  "updated_at": "2016-06-28T15:26:58+00:00"
  }      

Phones Model

A customer can have 3 types of phone numbers: home, work and an other.

It can’t be greater than 30 characters, apart from that, there is no validation, so you can store them as you want.

{
  "home": "5149873473",
  "work": "+1 (877) 247-9367",
  "other": "(418) 394-1928 x19119"
}

Unsubscribed Status

The attribute is_unsubscribed indicate if you can communicate with the customer by text message in Kimoby. This status can be change when the customer text Kimoby. When he texts "START" or "REPRISE" his unsubscribed status will be set to false. When he texts "STOP" or "ARRETE" the status will be set to true. The last way you it can be modified is if you set it to true when you update the customer with the API or within the Kimoby application.

Warning, once it’s set to true, you cannot set it back to false.

Note the keyword that the customer send to change is unsubscribed status are case-insensitive and accent-insensitive.

/customers

Create a Customer

To create a customer send the customer attributes in JSON in the payload of the request. Only the name is required, all other attributes of the Customer Model are optionals.

If there is a validation error it will be returns in JSON as mention Error Section, otherwise the customer will be return.

$ curl -s https://api.kimoby.com/v1/customers \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"CU000001","name":"John Doe","cell_phone_number":"+14182031234","email":"johndoe@site.com","address":"633 Saint-Joseph E.","city":"Quebec","state":"QC","zipcode":"G1K 3C1","country":"CA","is_unsubscribed":false,"phones":{"home":"5149873473","work":"+1 (877) 247-9367","other":"(418) 394-1928 x19119"},"custom_attributes":{"vehicle":"Audi","vehicle_year":"2012","last_visit_date":"2013-02-12T00:00:00+00:00","product_names_array":["Premium","Lite"]},"created_at":"2015-12-24T00:00:00Z","updated_at":"2015-12-24T00:00:00Z"}'
{
  "id": "cueeadfbacc5d64682bd20ac077d592e83",
  "reference": "CU000001",
  "name": "John Doe",
  "cell_phone_number": "+14182031234",
  "email": "johndoe@site.com",
  "address": "633 Saint-joseph E.",
  "city": "Quebec",
  "state": "QC",
  "zipcode": "G1K 3C1",
  "country": "CA",
  "is_unsubscribed": false,
  "phones": {
    "home": "5149873473",
    "work": "+1 (877) 247-9367",
    "other": "(418) 394-1928 x19119"
  },
  "custom_attributes": {
    "vehicle": "Audi",
    "vehicle_year": "2012",
    "last_visit_date": "2013-02-12T00:00:00+00:00",
    "product_names_array": [
      "Premium",
      "Lite"
    ]
  },
  "created_at": "2016-06-28T15:26:58+00:00",
  "updated_at": "2016-06-28T15:26:58+00:00"
}

/customers

Update a Customer

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

cell_phone_number
string

The cell phone number of the customer in E.164 format.

To update a customer, we first need to find the customer. There is two way to do it.

The first way is to add the customer’s id in the URI segment: "https://api.kimoby.com/v1/customers/cueeadfbacc5d64682bd20ac077d592e83"

The second way is add one of the tree parameters in the above tables to the query: "https://api.kimoby.com/v1/customers?id=cueeadfbacc5d64682bd20ac077d592e83" "https://api.kimoby.com/v1/customers?reference=CU000001" "https://api.kimoby.com/v1/customers?cell_phone_number=+14182031234"

You also need to send the customer attributes in JSON in the payload of the request. Only the name is required, all other attributes of the Customer Model are optionals. Only the present attributes will be affect the customer.

If there is a validation error it will be returns in JSON as mention Error Section, otherwise the customer will be return.

$ curl -s https://api.kimoby.com/v1/customers/cueeadfbacc5d64682bd20ac077d592e83 \
 -X PUT \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret} \
 -H 'Content-Type:application/json' \
 --data-raw '{"reference":"CU000001","name":"John Doe","cell_phone_number":"+14182031234","email":null,"address":"633 Saint-Joseph E.","city":"Quebec","state":"QC","zipcode":"G1K 3C1","country":"CA","is_unsubscribed":false,"phones":{"home":null,"work":"+1 (877) 247-9367","other":"(418) 394-1928 x19119"},"custom_attributes":{"vehicle":null,"vehicle_year":"2012","last_visit_date":"2013-02-12T00:00:00+00:00","product_names_array":["Premium","Lite"]},"created_at":"2015-12-24T00:00:00Z","updated_at":"2015-12-24T00:00:00Z"}'

$ curl -s https://api.kimoby.com/v1/customers?id=cueeadfbacc5d64682bd20ac077d592e83 \
 -X PUT \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret} \
 -H 'Content-Type:application/json' \
 --data-raw '{"reference":"CU000001","name":"John Doe","cell_phone_number":"+14182031234","email":null,"address":"633 Saint-Joseph E.","city":"Quebec","state":"QC","zipcode":"G1K 3C1","country":"CA","is_unsubscribed":false,"phones":{"home":null,"work":"+1 (877) 247-9367","other":"(418) 394-1928 x19119"},"custom_attributes":{"vehicle":null,"vehicle_year":"2012","last_visit_date":"2013-02-12T00:00:00+00:00","product_names_array":["Premium","Lite"]},"created_at":"2015-12-24T00:00:00Z","updated_at":"2015-12-24T00:00:00Z"}'

$ curl -s https://api.kimoby.com/v1/customers?reference=CU000001 \
 -X PUT \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret} \
 -H 'Content-Type:application/json' \
 --data-raw '{"reference":"CU000001","name":"John Doe","cell_phone_number":"+14182031234","email":null,"address":"633 Saint-Joseph E.","city":"Quebec","state":"QC","zipcode":"G1K 3C1","country":"CA","is_unsubscribed":false,"phones":{"home":null,"work":"+1 (877) 247-9367","other":"(418) 394-1928 x19119"},"custom_attributes":{"vehicle":null,"vehicle_year":"2012","last_visit_date":"2013-02-12T00:00:00+00:00","product_names_array":["Premium","Lite"]},"created_at":"2015-12-24T00:00:00Z","updated_at":"2015-12-24T00:00:00Z"}'

$ curl -s https://api.kimoby.com/v1/customers?cell_phone_number=+14182031234 \
 -X PUT \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret} \
 -H 'Content-Type:application/json' \
 --data-raw '{"reference":"CU000001","name":"John Doe","cell_phone_number":"+14182031234","email":null,"address":"633 Saint-Joseph E.","city":"Quebec","state":"QC","zipcode":"G1K 3C1","country":"CA","is_unsubscribed":false,"phones":{"home":null,"work":"+1 (877) 247-9367","other":"(418) 394-1928 x19119"},"custom_attributes":{"vehicle":null,"vehicle_year":"2012","last_visit_date":"2013-02-12T00:00:00+00:00","product_names_array":["Premium","Lite"]},"created_at":"2015-12-24T00:00:00Z","updated_at":"2015-12-24T00:00:00Z"}'
{
  "id": "cueeadfbacc5d64682bd20ac077d592e83",
  "reference": "CU000001",
  "name": "John Doe",
  "cell_phone_number": "+14182031234",
  "email": "",
  "address": "633 Saint-joseph E.",
  "city": "Quebec",
  "state": "QC",
  "zipcode": "G1K 3C1",
  "country": "CA",
  "is_unsubscribed": false,
  "phones": {
    "home": "",
    "work": "+1 (877) 247-9367",
    "other": "(418) 394-1928 x19119"
  },
  "custom_attributes": {
    "vehicle_year": "2012",
    "last_visit_date": "2013-02-12T00:00:00+00:00",
    "product_names_array": [
      "Premium",
      "Lite"
    ]
  },
  "created_at": "2016-06-28T15:26:58+00:00",
  "updated_at": "2016-06-28T15:27:04+00:00"
}

/customers

Retrieve a Customer

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

cell_phone_number
string

The cell phone number of the customer in E.164 format.

To retrieve a customer there is two ways.

The first way is to add the customer’s id in the URI segment: "https://api.kimoby.com/v1/customers/cueeadfbacc5d64682bd20ac077d592e83"

The second way is add one of the tree parameters in the above tables to the query: "https://api.kimoby.com/v1/customers?id=cueeadfbacc5d64682bd20ac077d592e83" "https://api.kimoby.com/v1/customers?reference=CU000001" "https://api.kimoby.com/v1/customers?cell_phone_number=+14182031234"

$ curl -s https://api.kimoby.com/v1/customers/cueeadfbacc5d64682bd20ac077d592e83 \
 -X GET \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/customers?id=cueeadfbacc5d64682bd20ac077d592e83 \
 -X GET \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/customers?reference=CU000001 \
 -X GET \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/customers?cell_phone_number=+14182031234 \
 -X GET \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}
{
  "id": "cueeadfbacc5d64682bd20ac077d592e83",
  "reference": "CU000001",
  "name": "John Doe",
  "cell_phone_number": "+14182031234",
  "email": "",
  "address": "633 Saint-joseph E.",
  "city": "Quebec",
  "state": "QC",
  "zipcode": "G1K 3C1",
  "country": "CA",
  "is_unsubscribed": false,
  "phones": {
    "home": "",
    "work": "+1 (877) 247-9367",
    "other": "(418) 394-1928 x19119"
  },
  "custom_attributes": {
    "vehicle_year": "2012",
    "last_visit_date": "2013-02-12T00:00:00+00:00",
    "product_names_array": [
      "Premium",
      "Lite"
    ]
  },
  "created_at": "2016-06-28T15:26:58+00:00",
  "updated_at": "2016-06-28T15:27:04+00:00"
}

/customers

List all customers.

Parameters
page
integer (greater than 0)
per_page
integer (greater than 0 and less or equals to 50)

Get a list of Customer objects. It matches the customers JSON schema.

$ curl -s https://api.kimoby.com/v1/customers?page=1&per_page=25 \
  -X GET \
  -H 'Accept:application/json' \
  -u {api_key}:{api_secret}
{
  "customers": [
    {
      "id": "cueeadfbacc5d64682bd20ac077d592e83",
      "reference": "CU000001",
      "name": "John Doe",
      "cell_phone_number": "+14182031234",
      "email": "",
      "address": "633 Saint-joseph E.",
      "city": "Quebec",
      "state": "QC",
      "zipcode": "G1K 3C1",
      "country": "CA",
      "is_unsubscribed": false,
      "phones": {
        "home": "",
        "work": "+1 (877) 247-9367",
        "other": "(418) 394-1928 x19119"
      },
      "custom_attributes": {
        "vehicle_year": "2012",
        "last_visit_date": "2013-02-12T00:00:00+00:00",
        "product_names_array": [
          "Premium",
          "Lite"
        ]
      },
      "created_at": "2016-06-28T15:26:58+00:00",
      "updated_at": "2016-06-28T15:27:04+00:00"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "pages": 1,
    "items": 10,
    "per_page": 25
  }
}

Delete a Customer

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

cell_phone_number
string

The cell phone number of the customer in E.164 format.

To delete a customer, we first need to find the customer. There is two way to do it.

The first way is to add the customer’s id in the URI segment: "https://api.kimoby.com/v1/customers/cueeadfbacc5d64682bd20ac077d592e83"

The second way is add one of the tree parameters in the above tables to the query: "https://api.kimoby.com/v1/customers?id=cueeadfbacc5d64682bd20ac077d592e83" "https://api.kimoby.com/v1/customers?reference=CU000001" "https://api.kimoby.com/v1/customers?cell_phone_number=+14182031234"

If there is a validation error it will be returns in JSON as mention Error Section, otherwise nothing is returned.

$ curl -s https://api.kimoby.com/v1/customers/cueeadfbacc5d64682bd20ac077d592e83 \
 -X DELETE \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/customers?id=cueeadfbacc5d64682bd20ac077d592e83 \
 -X DELETE \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/customers?reference=CU000001 \
 -X DELETE \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/customers?cell_phone_number=+14182031234 \
 -X DELETE \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}

Appointment Model

An appointment object contains the following attributes. It matches the appointment JSON schema.

Attribute Type Description
id String Unique string identifier. It is generated by Kimoby.
reference String Unique string identifier used in your system. It is case sensitive.
start_at String Date and time when the appointment start in RFC 3339 format. It is Required.
end_at String Date and time when the appointment end in RFC 3339 format. It is Required and must be after start_at. By default it is set an hour after the start_at
status String The appointment status. Must be one of: "confirmed", "canceled", "not_confirmed".
customer Object The customer of the appointment. See Customer Model section.
custom_attributes Object The custom attributes of the appointment. See Custom Attributes Model section.
created_at String The creation date of the appointment. Date with time in RFC 3339 format.
updated_at String The last update date of the appointment. Date with time in RFC 3339 format.
{
  "id": "apadd4ba3f856c8bf2a72b1cf06c8c546d",
  "reference": "AP000234",
  "start_at": "2016-01-20T14:00:00+00:00",
  "end_at": "2016-01-20T18:00:00+00:00",
  "status": "not_confirmed",
  "custom_attributes": {
    "comment": "Work needs to be done for tomorrow.",
    "num_of_visits": 12.0,
    "last_appt_date": "2015-10-12T14:00:00+00:00",
    "service_required_array": [
      "Oil Change",
      "Wash"
    ]
  },
  "customer": {
    "..."
  },
  "created_at": "2016-06-28T15:27:21+00:00",
  "updated_at": "2016-06-28T15:27:21+00:00"
}

/appointments

Create an Appointment

To create an appointment send the appointment attributes in JSON in the payload of the request. The "start_at" is required and the customer must exists. The customer can’t have two appointment at the same "start_at".

To refer to the customer pass at least one the following customer attribute to a "customer" attribute of your payload: "id", "reference", "cell_phone_number".

All other attributes of the Appointment Model are optionals.

If there is a validation error it will be returns in JSON as mention Error Section, otherwise the appointment will be return.

$ curl -s https://api.kimoby.com/v1/appointments \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"AP000234","start_at":"2016-01-20T14:00:00Z","end_at":"2016-01-20T18:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Work needs to be done for tomorrow.","num_of_visits":12,"last_appt_date":"2015-10-12T14:00:00Z","service_required_array":["Oil Change","Wash"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'
{
  "id": "apadd4ba3f856c8bf2a72b1cf06c8c546d",
  "reference": "AP000234",
  "start_at": "2016-01-20T14:00:00+00:00",
  "end_at": "2016-01-20T18:00:00+00:00",
  "status": "not_confirmed",
  "custom_attributes": {
    "comment": "Work needs to be done for tomorrow.",
    "num_of_visits": 12.0,
    "last_appt_date": "2015-10-12T14:00:00+00:00",
    "service_required_array": [
      "Oil Change",
      "Wash"
    ]
  },
  "customer": {
    "id": "cueeadfbacc5d64682bd20ac077d592e83",
    "reference": "CU000001",
    "name": "John Doe",
    "cell_phone_number": "+14182031234",
    "email": "",
    "address": "633 Saint-joseph E.",
    "city": "Quebec",
    "state": "QC",
    "zipcode": "G1K 3C1",
    "country": "CA",
    "is_unsubscribed": false,
    "phones": {
      "home": "",
      "work": "+1 (877) 247-9367",
      "other": "(418) 394-1928 x19119"
    },
    "custom_attributes": {
      "vehicle_year": "2012",
      "last_visit_date": "2013-02-12T00:00:00+00:00",
      "product_names_array": [
        "Premium",
        "Lite"
      ]
    },
    "created_at": "2016-06-28T15:26:58+00:00",
    "updated_at": "2016-06-28T15:27:04+00:00"
  },
  "created_at": "2016-06-28T15:27:21+00:00",
  "updated_at": "2016-06-28T15:27:21+00:00"
}

/appointments

Update an Appointment.

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

To update an appointment, we first need to find the appointment. There is two way to do it.

The first way is to add the appointment’s id in the URI segment: "https://api.kimoby.com/v1/appointments/apadd4ba3f856c8bf2a72b1cf06c8c546d"

The second way is add one of the two parameters in the above tables to the query: "https://api.kimoby.com/v1/appointments?id=apadd4ba3f856c8bf2a72b1cf06c8c546d" "https://api.kimoby.com/v1/appointments?reference=AP000234"

You also need to send the appointment attributes in JSON in the payload of the request.

The "start_at" is required and the customer must exists. The customer can’t have two appointment at the same "start_at".

To refer to the customer pass at least one of the following customer attribute to a "customer" attribute in your payload: "id", "reference", "cell_phone_number".

All other attributes of the Appointment Model are optionals.

If there is a validation error, the errors will be returned in JSON, otherwise the appointment will be returned.

$ curl -s https://api.kimoby.com/v1/appointments/ap46bd1619kj6d9ca31i39da1m2kl1fa17 \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"AP000234","start_at":"2016-01-20T10:00:00Z","end_at":"2016-01-20T11:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Work needs to be done for tomorrow.","num_of_visits":13,"last_appt_date":"2015-10-12T14:00:00Z","service_required_array":["Oil Change"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'

$ curl -s https://api.kimoby.com/v1/appointments?id=ap46bd1619kj6d9ca31i39da1m2kl1fa17 \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"AP000234","start_at":"2016-01-20T10:00:00Z","end_at":"2016-01-20T11:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Work needs to be done for tomorrow.","num_of_visits":13,"last_appt_date":"2015-10-12T14:00:00Z","service_required_array":["Oil Change"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'

$ curl -s https://api.kimoby.com/v1/appointments?reference=AP000234 \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"AP000234","start_at":"2016-01-20T10:00:00Z","end_at":"2016-01-20T11:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Work needs to be done for tomorrow.","num_of_visits":13,"last_appt_date":"2015-10-12T14:00:00Z","service_required_array":["Oil Change"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'
{
  "id": "apadd4ba3f856c8bf2a72b1cf06c8c546d",
  "reference": "AP000234",
  "start_at": "2016-01-20T10:00:00+00:00",
  "end_at": "2016-01-20T11:00:00+00:00",
  "status": "not_confirmed",
  "custom_attributes": {
    "comment": "Work needs to be done for tomorrow.",
    "num_of_visits": 13.0,
    "last_appt_date": "2015-10-12T14:00:00+00:00",
    "service_required_array": [
      "Oil Change"
    ]
  },
  "customer": {
    "id": "cueeadfbacc5d64682bd20ac077d592e83",
    "reference": "CU000001",
    "name": "John Doe",
    "cell_phone_number": "+14182031234",
    "email": "",
    "address": "633 Saint-joseph E.",
    "city": "Quebec",
    "state": "QC",
    "zipcode": "G1K 3C1",
    "country": "CA",
    "is_unsubscribed": false,
    "phones": {
      "home": "",
      "work": "+1 (877) 247-9367",
      "other": "(418) 394-1928 x19119"
    },
    "custom_attributes": {
      "vehicle_year": "2012",
      "last_visit_date": "2013-02-12T00:00:00+00:00",
      "product_names_array": [
        "Premium",
        "Lite"
      ]
    },
    "created_at": "2016-06-28T15:26:58+00:00",
    "updated_at": "2016-06-28T15:27:04+00:00"
  },
  "created_at": "2016-06-28T15:27:21+00:00",
  "updated_at": "2016-06-28T15:27:27+00:00"
}

/appointments/:id

Retrieve an Appointment

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

To retrieve an appointment there is two ways.

The first way is to add the appointment’s id in the URI segment: "https://api.kimoby.com/v1/appointments/apadd4ba3f856c8bf2a72b1cf06c8c546d"

The second way is add one of the two parameters in the above tables to the query: "https://api.kimoby.com/v1/appointments?id=apadd4ba3f856c8bf2a72b1cf06c8c546d" "https://api.kimoby.com/v1/appointments?reference=AP000234"

$ curl -s https://api.kimoby.com/v1/appointments/apadd4ba3f856c8bf2a72b1cf06c8c546d \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/appointments?id=apadd4ba3f856c8bf2a72b1cf06c8c546d \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/appointments?reference=AP000234 \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}
{
  "id": "apadd4ba3f856c8bf2a72b1cf06c8c546d",
  "reference": "AP000234",
  "start_at": "2016-01-20T10:00:00+00:00",
  "end_at": "2016-01-20T11:00:00+00:00",
  "status": "not_confirmed",
  "custom_attributes": {
    "comment": "Work needs to be done for tomorrow.",
    "num_of_visits": 13.0,
    "last_appt_date": "2015-10-12T14:00:00+00:00",
    "service_required_array": [
      "Oil Change"
    ]
  },
  "customer": {
    "id": "cueeadfbacc5d64682bd20ac077d592e83",
    "reference": "CU000001",
    "name": "John Doe",
    "cell_phone_number": "+14182031234",
    "email": "",
    "address": "633 Saint-joseph E.",
    "city": "Quebec",
    "state": "QC",
    "zipcode": "G1K 3C1",
    "country": "CA",
    "is_unsubscribed": false,
    "phones": {
      "home": "",
      "work": "+1 (877) 247-9367",
      "other": "(418) 394-1928 x19119"
    },
    "custom_attributes": {
      "vehicle_year": "2012",
      "last_visit_date": "2013-02-12T00:00:00+00:00",
      "product_names_array": [
        "Premium",
        "Lite"
      ]
    },
    "created_at": "2016-06-28T15:26:58+00:00",
    "updated_at": "2016-06-28T15:27:04+00:00"
  },
  "created_at": "2016-06-28T15:27:21+00:00",
  "updated_at": "2016-06-28T15:27:27+00:00"
}

/appointments

List appointments.

Parameters
date_start
DateTime (RFC 3339 format)
date_end
DateTime (RFC 3339 format)
page
integer (greater than 0)
per_page
integer (greater than 0 and less or equals to 50)

Get a list of Appointment objects. It matches the appointments JSON schema.

The date_start and date_end are both required if used as params. They can’t be used separately.

$ curl -s https://api.kimoby.com/v1/appointments?page=1&per_page=25 \
 -X GET \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}
{
  "appointments": [
    {
      "id": "apadd4ba3f856c8bf2a72b1cf06c8c546d",
      "reference": "AP000234",
      "start_at": "2016-01-20T10:00:00+00:00",
      "end_at": "2016-01-20T11:00:00+00:00",
      "status": "not_confirmed",
      "custom_attributes": {
        "comment": "Work needs to be done for tomorrow.",
        "num_of_visits": 13.0,
        "last_appt_date": "2015-10-12T14:00:00+00:00",
        "service_required_array": [
          "Oil Change"
        ]
      },
      "customer": {
        "id": "cueeadfbacc5d64682bd20ac077d592e83",
        "reference": "CU000001",
        "name": "John Doe",
        "cell_phone_number": "+14182031234",
        "email": "",
        "address": "633 Saint-joseph E.",
        "city": "Quebec",
        "state": "QC",
        "zipcode": "G1K 3C1",
        "country": "CA",
        "is_unsubscribed": false,
        "phones": {
          "home": "",
          "work": "+1 (877) 247-9367",
          "other": "(418) 394-1928 x19119"
        },
        "custom_attributes": {
          "vehicle_year": "2012",
          "last_visit_date": "2013-02-12T00:00:00+00:00",
          "product_names_array": [
            "Premium",
            "Lite"
          ]
        },
        "created_at": "2016-06-28T15:26:58+00:00",
        "updated_at": "2016-06-28T15:27:04+00:00"
      },
      "created_at": "2016-06-28T15:27:21+00:00",
      "updated_at": "2016-06-28T15:27:27+00:00"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "pages": 1,
    "items": 1,
    "per_page": 25
  }
}

Delete an Appointment

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

To delete an appointment there is two ways.

The first way is to add the appointment’s id in the URI segment: "https://api.kimoby.com/v1/appointments/apadd4ba3f856c8bf2a72b1cf06c8c546d"

The second way is add one of the two parameters in the above tables to the query: "https://api.kimoby.com/v1/appointments?id=apadd4ba3f856c8bf2a72b1cf06c8c546d" "https://api.kimoby.com/v1/appointments?reference=AP000234"

If there is a validation error it will be returns in JSON as mention Error Section, otherwise nothing is returned.

$ curl -s https://api.kimoby.com/v1/appointments/apadd4ba3f856c8bf2a72b1cf06c8c546d \
-X DELETE \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/appointments?id=apadd4ba3f856c8bf2a72b1cf06c8c546d \
-X DELETE \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/appointments?reference=AP000234 \
-X DELETE \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

Event Model

An event object contains the following attributes. It matches the event JSON schema.

Attribute Type Description
id String Unique string identifier. It is generated by Kimoby.
name String The name of your event. This attribute is required and it is case insensitive.
reference String Unique string identifier used in your system. It is case sensitive.
happened_at String Date and time when the event happened in RFC 3339 format. It is Required.
customer Object The customer of the event. See Customer Model section.
custom_attributes Object The custom attributes of the event. See Custom Attributes Model section.
created_at String The creation date of the event. Date with time in RFC 3339 format.
updated_at String The last update date of the event. Date with time in RFC 3339 format.
{
  "id": "ev5c298c73d9bc81e94a16535bd8e770d8",
  "reference": "EV000088",
  "name": "completed-repair",
  "happened_at": "2016-01-20T14:00:00+00:00",
  "customer": {
    "..."
  },
  "custom_attributes": {
    "comment": "Will need another appointment for tire change.",
    "repair_total": 210.11,
    "customer_since_date": "2013-09-10T10:00:00+00:00",
    "completed_work_array": [
      "Oil Change",
      "Wash",
      "02P03"
    ]
  },
  "created_at": "2016-06-28T15:27:50+00:00",
  "updated_at": "2016-06-28T15:27:50+00:00"
}

/events

Create an Event.

To create an event send the event attributes in JSON in the payload of the request. The "happened_at" is required and the customer must exists. An event is unique with the combination of the following attributes: the customer, the event name and the event happened at.

The event name is case insensitive, Completed-Repair and completed-repair will be considered the same event in your application. Dollars, periods and spaces will be replaced with hyphens. We recommend that you submit lower case event names that contains hyphens.

To refer to the customer pass at least one the following customer attribute to a "customer" attribute of your payload: "id", "reference", "cell_phone_number".

All other attributes of the Event Model are optionals.

If there is a validation error it will be returns in JSON as mention Error Section, otherwise the event will be return.

$ curl -s https://api.kimoby.com/v1/events \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"EV000088","name":"completed-repair","happened_at":"2016-01-20T14:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Will need another appointment for tire change.","repair_total":210.11,"customer_since_date":"2013-09-10T10:00:00Z","completed_work_array":["Oil Change","Wash","02P03"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'
{
  "id": "ev5c298c73d9bc81e94a16535bd8e770d8",
  "reference": "EV000088",
  "name": "completed-repair",
  "happened_at": "2016-01-20T14:00:00+00:00",
  "customer": {
    "..."
  },
  "custom_attributes": {
    "comment": "Will need another appointment for tire change.",
    "repair_total": 210.11,
    "customer_since_date": "2013-09-10T10:00:00+00:00",
    "completed_work_array": [
      "Oil Change",
      "Wash",
      "02P03"
    ]
  },
  "created_at": "2016-06-28T15:27:50+00:00",
  "updated_at": "2016-06-28T15:27:50+00:00"
}

/events

Update an Event

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

To update an event, we first need to find the event. There is two way to do it.

The first way is to add the event’s id in the URI segment: "https://api.kimoby.com/v1/events/ev5c298c73d9bc81e94a16535bd8e770d8"

The second way is add one of the two parameters in the above tables to the query: "https://api.kimoby.com/v1/events?id=ev5c298c73d9bc81e94a16535bd8e770d8" "https://api.kimoby.com/v1/events?reference=EV000088"

You also need to send the event attributes in JSON in the payload of the request. The "happened_at" is required and the customer must exists. An event is unique with the combination of the following attributes: the customer, the event name and the event happened at.

The event name is case insensitive, Completed-Repair and completed-repair will be considered the same event in your application. Dollars, periods and spaces will be replaced with hyphens. We recommend that you submit lower case event names that contains hyphens.

To refer to the customer pass at least one the following customer attribute to a "customer" attribute of your payload: "id", "reference", "cell_phone_number".

All other attributes of the Event Model are optionals.

If there is a validation error it will be returns in JSON as mention Error Section, otherwise the event will be return.

$ curl -s https://api.kimoby.com/v1/events?reference=EV000088 \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"EV000088","name":"repair","happened_at":"2016-01-20T14:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Will need another appointment for tire change.","repair_total":250.75,"customer_since_date":"2013-09-10T10:00:00Z","completed_work_array":["Oil Change","Wash","02P03"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'

$ curl -s https://api.kimoby.com/v1/events?reference=EV000088 \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"EV000088","name":"repair","happened_at":"2016-01-20T14:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Will need another appointment for tire change.","repair_total":250.75,"customer_since_date":"2013-09-10T10:00:00Z","completed_work_array":["Oil Change","Wash","02P03"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'

$ curl -s https://api.kimoby.com/v1/events?reference=EV000088 \
-X PUT \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"reference":"EV000088","name":"repair","happened_at":"2016-01-20T14:00:00Z","customer":{"reference":"CU000001"},"custom_attributes":{"comment":"Will need another appointment for tire change.","repair_total":250.75,"customer_since_date":"2013-09-10T10:00:00Z","completed_work_array":["Oil Change","Wash","02P03"]},"created_at":"2016-01-07T10:00:00Z","updated_at":"2016-01-07T10:00:00Z"}'
{
  "id": "ev5c298c73d9bc81e94a16535bd8e770d8",
  "reference": "EV000088",
  "name": "repair",
  "happened_at": "2016-01-20T14:00:00+00:00",
  "customer": {
    "..."
  },
  "custom_attributes": {
    "comment": "Will need another appointment for tire change.",
    "repair_total": 250.75,
    "customer_since_date": "2013-09-10T10:00:00+00:00",
    "completed_work_array": [
      "Oil Change",
      "Wash",
      "02P03"
    ]
  },
  "created_at": "2016-06-28T15:27:50+00:00",
  "updated_at": "2016-06-28T15:27:56+00:00"
}

/events

Retrieve an Event

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

To retrieve an event there is two ways.

The first way is to add the event’s id in the URI segment: "https://api.kimoby.com/v1/events/ev5c298c73d9bc81e94a16535bd8e770d8"

The second way is add one of the two parameters in the above tables to the query: "https://api.kimoby.com/v1/events?id=ev5c298c73d9bc81e94a16535bd8e770d8" "https://api.kimoby.com/v1/events?reference=EV000088"

$ curl -s https://api.kimoby.com/v1/events/ev5c298c73d9bc81e94a16535bd8e770d8 \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/events?id=ev5c298c73d9bc81e94a16535bd8e770d8 \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/events?reference=EV000088 \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}
{
  "id": "ev5c298c73d9bc81e94a16535bd8e770d8",
  "reference": "EV000088",
  "name": "repair",
  "happened_at": "2016-01-20T14:00:00+00:00",
  "customer": {
    "..."
  },
  "custom_attributes": {
    "comment": "Will need another appointment for tire change.",
    "repair_total": 250.75,
    "customer_since_date": "2013-09-10T10:00:00+00:00",
    "completed_work_array": [
      "Oil Change",
      "Wash",
      "02P03"
    ]
  },
  "created_at": "2016-06-28T15:27:50+00:00",
  "updated_at": "2016-06-28T15:27:56+00:00"
}

/events

List all events.

Parameters
page
integer (greater than 0)
per_page
integer (greater than 0 and less or equals to 50)

Get a list of Event objects. It matches the events JSON schema.

$ curl -s https://api.kimoby.com/v1/events?page=1&per_page=25 \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}
{
  "events": [
    {
      "id": "ev5c298c73d9bc81e94a16535bd8e770d8",
      "reference": "EV000088",
      "name": "repair",
      "happened_at": "2016-01-20T14:00:00+00:00",
      "customer": {
        "..."
      },
      "custom_attributes": {
        "comment": "Will need another appointment for tire change.",
        "repair_total": 250.75,
        "customer_since_date": "2013-09-10T10:00:00+00:00",
        "completed_work_array": [
          "Oil Change",
          "Wash",
          "02P03"
        ]
      },
      "created_at": "2016-06-28T15:27:50+00:00",
      "updated_at": "2016-06-28T15:27:56+00:00"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "pages": 1,
    "items": 1,
    "per_page": 25
  }
}

Delete an Event

Parameters
id
string

The id generated by Kimoby.

reference
string

Unique string identifier used in your system.

To delete an event there is two ways.

The first way is to add the event’s id in the URI segment: "https://api.kimoby.com/v1/events/apadd4ba3f856c8bf2a72b1cf06c8c546d"

The second way is add one of the two parameters in the above tables to the query: "https://api.kimoby.com/v1/events?id=apadd4ba3f856c8bf2a72b1cf06c8c546d" "https://api.kimoby.com/v1/events?reference=AP000234"

If there is a validation error it will be returns in JSON as mention Error Section, otherwise nothing is returned.

$ curl -s https://api.kimoby.com/v1/events/ev5c298c73d9bc81e94a16535bd8e770d8 \
-X DELETE \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/events?id=ev5c298c73d9bc81e94a16535bd8e770d8 \
-X DELETE \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

$ curl -s https://api.kimoby.com/v1/events?reference=EV000088 \
-X DELETE \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}

/messages

Send a message to a customer.

To send a message, you need the customer and body attribute. Those are the two required fields.

For the customer attribute, you can send a reference, id or cell_phone_number to send a message to an existing customer in Kimoby. If there are any validation errors, they’ll be in the HTTP response.

The body attribute as a maximum length of 1600 characters.

You can also pass a user_reference attribute which would be the ID of the user initiating the message in your app. If the ID is linked to a user in Kimoby, the message will be marked as sent by this user.

{
  "customer": {
    "reference": "abc123" // Can also be `id`, `cell_phone_number` attribute.
  },
  "body": "Hello world!",
  "user_reference": "AM91" // The user reference from your app
}

Custom Attributes Model

Custom Attributes are key/value object associated to a Customer, an Appointment or a Event. With them you can add any important information from your system into Kimoby.

There could only one data type per name, per object (Customer, Appointment or Event).

The name of the custom attribute is formatted in lower case and transform in snake_case. For example: "Vehicle Year" will be "vehicle_year".

To remove a custom attribute for specific object, set the value to null.

You can send String, Number, Date or Array with the following format and restrictions.

NOTE: The custom attribute with data type Number are returned as Float.

Data Types Restriction
String Can't be empty.
Number Must be a float or an integer.
Date The attribute name must end with "_date" to be considered a date, otherwise it will be stored as a string. Date with time in RFC 3339 format. Can't be empty.
Array The attribute name must end with "_array" to be considered an array. Every item of the Array will be considered as a string even if the array contains numbers. Can't be empty.
{
  "vehicle": "Audi",                           // String
  "vehicle_year": 2012,                        // Number
  "last_visit_date": "2015-12-25T00:00:00Z",   // Date
  "product_names_array": ["Premium", "Lite"]   // Array
}