Authentication

All Kimoby API requests need to be authenticated using Basic Authentication and must be sent over HTTPS. Calls made over plain HTTP will fail. API requests 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 errors of API calls. 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.

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

Webhooks

Webhooks are HTTP callbacks sent to your application server via HTTP to notify you of activity in your account.

You can configure your multiple webhooks using the API.

Check the webhooks API reference to create, list, update and delete webhooks.

Format

Webhooks are sent using the POST method to your URL as JSON content-type: application/json.

The format of the request webhook body is the same for any event, it’s an object with properties data and event_name.

It matches the webhook event JSON schema.

Events

Supported events
Event name Trigger
message_created A new message is created. It could be a sent or a received message.
message_updated Any change to the following message fields status error, user_sub_user_id, conversation_id.
customer_unsubscribed When a customer is unsubscribed from receiving messages.
customer_resubscribed When a customer re-subscribed from receiving messages.
Event message_created

A new message is created. It could be a sent or a received message.

Request body example:

{
    "data": {
        "id": 345634563,
        "customer_id": "CUc571a62c0639ef8c30807962698c3",
        "conversation_id": null,
        "user_sub_user_id": null,
        "body": "Test message",
        "element_type": "sent_message",
        "direction": "outgoing",
        "status": "queued",
        "error": null,
        "documents": [],
        "created_at": "2019-02-21T14:38:14-05:00",
        "updated_at": "2019-02-21T14:38:14-05:00"
    },
    "event_name": "message_created"
}
Event message_updated

Any change to the following message fields status error, user_sub_user_id, conversation_id.

Request body example:

{
    "data": {
        "id": 345634563,
        "customer_id": "CUc571a62c0639ef8c30807962698c3",
        "conversation_id": null,
        "user_sub_user_id": null,
        "body": "Test message",
        "element_type": "sent_message",
        "direction": "outgoing",
        "status": "sent",
        "error": null,
        "documents": [],
        "created_at": "2019-02-21T14:38:14-05:00",
        "updated_at": "2019-02-21T14:39:03-05:00"
    },
    "event_name": "message_updated"
}
Event customer_unsubscribed

The body sent will be the customer model.

Event customer_resubscribed

The body sent will be the customer model.

Acceptation

Upon receipt of a webhook, you should accept it by returning an HTTP status 200 OK response as quickly as possible. Sending any other response status (i.e. 500 Internal Server Error, 404 Not Found, etc.) or failing to return a response within approximately 60 seconds will result in automatic retries of the webhooks.

A status 410 Gone will delete the webhook.

Retry

The webhook retries will follow an exponential backoff schedule:

Attempt number Timing
1 As soon as possible after the original event
2 60 seconds after most recent failure
3 10 minutes after most recent failure
4 1 hour after most recent failure
5 3 hours after most recent failure
6 6 hours after most recent failure

Signature authentication

Webhooks are signed with a signature that allows you to validate the authenticity of the request. This signature is sent in the custom HTTP header X-Kimoby-Signature. To validate the authenticity of the request we have to generate the signature and compare it with the signature provided in the request.

Algorithm

The signature is generated by calculating the HMAC of the webhook url and the request body, using the SHA1 hash algorithm and the webhook key_authentication as secret. Then the HMAC is base 64.

Example using the language Ruby:

require 'OpenSSL'
require 'base64'

secret = 'Your webhook key_authentication'
data = url + body
hmac = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha1'), secret, data)
signature = Base64.encode64(hmac)

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 the proprietary 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. The cell phone number is unique by account.
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": "[email protected]",
  "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 changed when the customer text Kimoby. When he texts "START" or "REPRISE", his unsubscribed status will be set to false. When he texts "STOP" or "ARRET" the status will be set to true. You can also change it to true when you update the customer via the API or within the Kimoby application.

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

Note: the keywords that the customer sends to change his 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 optional.

If there is a validation error it will be returned in JSON as mentioned in the Error Section, otherwise, the customer will be returned.

$ 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":"[email protected]","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": "[email protected]",
  "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 are two ways 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 to add one of the tree parameters in the above table 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 optional. Only the present attributes will affect the customer.

If there is a validation error it will be returned in JSON as mentioned in the Error Section, otherwise, the customer will be returned.

$ 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 are 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 to add one of the tree parameters in the above table 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 are two ways 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 to add one of the tree parameters in the above table 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 returned in JSON as mentioned in the 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". Default value is "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 exist. The customer can’t have two appointments 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 optional.

If there is a validation error it will be returned in JSON as mentioned in the Error Section, otherwise, the appointment will be returned.

$ 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 to add one of the two parameters in the above table 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 exist. The customer can’t have two appointments 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 optional.

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 are 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 to add one of the two parameters in the above table 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 are 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 to add one of the two parameters in the above table 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 returned in JSON as mentioned in the 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. The date has to be in the past.
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 exist. An event is unique with the combination of the following attributes: the customer, the event name and the event happened at. An event is also unique with the combination of the following attributes: the customer, the event name and the event reference.

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 contain 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 optional.

$ 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 are two ways 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 to add one of the two parameters in the above table 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 exist. 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 contain 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 optional.

If there is a validation error it will be returned in JSON as mentioned in the Error Section, otherwise, the event will be returned.

$ 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 are 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 to add one of the two parameters in the above table 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 are 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 table 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 returned in JSON as mentioned in the 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}

Message model

Attribute Type Description
id String Unique string identifier. It is generated by Kimoby.
customer_id String Unique string identifier of the customer. It is generated by Kimoby.
conversation_id String Unique string identifier of the conversation that contains the message. It is generated by Kimoby.
user_sub_user_id String Unique string identifier of the user assigned to the conversation. It is generated by Kimoby.
body String Body of the message
element_type String Type of the message. Could be sent_message or received_message
direction String Direction of the message. Could be outgoing or incomming
status String Status of the message. Could be one of: queued, sending, sent,receiving, received, delivered, undelivered, failed
error String A description of the error that occurred if the status is undelivered or failed.
documents Array of string An array of URLs of the documents attached to the message
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.

/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.

You can pass a open_conversation attribute to force the creation of a conversation for the customer if there’s currently no open conversation.

Finally, you can attach documents to the message. To do so, just fill the field with the documents’ ids. You will first need to make sure they have been uploaded and created. If a single .jpg, .jpeg, .png or .gif file is attached, it will be sent as an MMS. Depending on your account’s provider and the customer’s, the maximum size for a MMS is between 1 499 999 bytes and 4 194 303 bytes. If there is more than 1 file or if the file exceeds the size limit, it will be sent as ShortURLs (1 per file).

{
  "customer": {
    "reference": "abc123" // Can also be `id`, `cell_phone_number` attribute.
  },
  "body": "Hello world!",
  "user_reference": "AM91", // The user reference from your app
  "open_conversation": true, // Force the creation of a conversation
  "documents": [1, 2, 3] // The ids of the documents to send
}

/messages

List messages

Parameters
created_at_start
DateTime (RFC 3339 format)
created_at_end
DateTime (RFC 3339 format)
customer_id
string

Filter for customer using id.

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

Returns a list of Message model.

$ curl -s https://api.kimoby.com/v1/messages \
-X GET \
-H 'Accept: application/json' \
-u {api_key}:{api_secret}
{
  "messages": [
    {
      "id": 345634563,
      "customer_id": "CUc571a62c0639ef8c30807962698c3",
      "conversation_id": 23529011,
      "user_sub_user_id": null,
      "body": "Test message",
      "element_type": "sent_message",
      "direction": "outgoing",
      "status": "queued",
      "error": null,
      "documents": [],
      "created_at": "2019-02-21T14:38:14-05:00",
      "updated_at": "2019-02-21T14:38:14-05:00"
    },
  ]
  "pagination": {
    "page": 1,
    "pages": 1,
    "items": 1,
    "per_page": 25
  }
}

/messages/:id

Retrieve a message

Returns a Message model.

$ curl -s https://api.kimoby.com/v1/messages/345634563 \
-X GET \
-H 'Accept: application/json' \
-u {api_key}:{api_secret}
{
  "id": 345634563,
  "customer_id": "CUc571a62c0639ef8c30807962698c3",
  "conversation_id": 23529011,
  "user_sub_user_id": null,
  "body": "Test message",
  "element_type": "sent_message",
  "direction": "outgoing",
  "status": "queued",
  "error": null,
  "documents": [],
  "created_at": "2019-02-21T14:38:14-05:00",
  "updated_at": "2019-02-21T14:38:14-05:00"
}

Invoice model

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.
customer Object The customer of the invoice, will only include the customer's ID.
conversation_id String Unique string identifier of the conversation where the invoice was sent in. It is generated by Kimoby.
total_price Integer A positive integer that is greater than 50. The price is represented in cents. Exemple: 10000 would be equal to an invoice of $100.00.
state String The state of the invoice. Could be one of: unpaid, processing, paid, voided, refunded.
currency String The currency of the invoice. Based on configuration of the Kimoby Pay account.
created_by String The name of the user who created the invoice. Can be null.
amount_refunded Integer The amount refunded on the invoice. The amount can be less than the full amount of the invoice, up to invoice's amount. Partial refunds are possible. A sum of the amount in the refunds object.
clicks_count String How much time the invoice was opened by the customer.
card Object An object containing the card used for payment with the following information: last_4_digits, name_on_card, brand, exp_month, exp_year
refunds Array of Objects An array of objects representing all the refunds done on the invoice. The objects contain the following information: amount, currency, refunded_by, date
public_url String The public URL for the invoice that can be sent to the customer.
invoice_paid_at String The date when the invoice was paid. Date with time in RFC 3339 format.
refunded_at String The creation date of the first refund. Date with time in RFC 3339 format.
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.

/invoices

Create an Invoice.

The required attributes to create an invoice are total_price and a customer object with the ID attribute. The reference attribute is optional.

The total_price must be greater than 50 (50 cents) and the price must be sent in cents. Ex: 10000 will equal to an invoice of $100.00.

$ 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":"12345","total_price":10000,"customer":{"id":"CU000001"}}'
{
  "id": "INd256791afb2b3ac76902dce86cbe40d8",
  "reference": "572765003029",
  "customer": {
      "id": "CUe400dcefc3f63afe221954f239b67a7e"
  },
  "total_price": 10000,
  "state": "paid",
  "currency": "CAD",
  "created_by": null,
  "conversation_id": null,
  "amount_refunded": 0,
  "refunded_on": null,
  "clicks_count": 1,
  "card": {
    "last_4_digits": "1111",
    "name_on_card": "John Doe",
    "brand": "Visa",
    "exp_month": "05",
    "exp_year": "2024"
  },
  "refunds": [],
  "public_url": "https://pay.kimoby.com/2239109u1291012948932",
  "invoice_paid_at": "2020-04-15T15:04:23-04:00",
  "created_at": "2020-04-15T00:00:00-04:00",
  "updated_at": "2020-04-15T15:04:23-04:00"
}

/invoices/:id

Retrieve an Invoice

Parameters
id
string

The id generated by Kimoby.

Will return an Invoice model.

$ curl -s https://api.kimoby.com/v1/invoices/INd256791afb2b3ac76902dce86cbe40d8 \
-X GET \
-H 'Accept:application/json' \
-u {api_key}:{api_secret}
{
  "id": "INd256791afb2b3ac76902dce86cbe40d8",
  "reference": "572765003029",
  "customer": {
      "id": "CUe400dcefc3f63afe221954f239b67a7e"
  },
  "total_price": 10000,
  "state": "paid",
  "currency": "CAD",
  "created_by": null,
  "conversation_id": null,
  "amount_refunded": 0,
  "refunded_on": null,
  "clicks_count": 1,
  "card": {
    "last_4_digits": "1111",
    "name_on_card": "John Doe",
    "brand": "Visa",
    "exp_month": "05",
    "exp_year": "2024"
  },
  "refunds": [],
  "public_url": "https://pay.kimoby.com/2239109u1291012948932",
  "invoice_paid_at": "2020-04-15T15:04:23-04:00",
  "created_at": "2020-04-15T00:00:00-04:00",
  "updated_at": "2020-04-15T15:04:23-04:00"
}

/invoices

List invoices

Parameters
created_at_start
DateTime (RFC 3339 format)
created_at_end
DateTime (RFC 3339 format)
paid_at_start
DateTime (RFC 3339 format)
paid_at_end
DateTime (RFC 3339 format)
page
integer (greater than 0)
per_page
integer (greater than 0 and less or equals to 50)

Returns a list of Invoice model.

$ curl -s https://api.kimoby.com/v1/invoices \
-X GET \
-H 'Accept: application/json' \
-u {api_key}:{api_secret}
{
  "invoices": [
    {
      "id": "INd256791afb2b3ac76902dce86cbe40d8",
      "reference": "572765003029",
      "customer": {
          "id": "CUe400dcefc3f63afe221954f239b67a7e"
      },
      "total_price": 10000,
      "state": "paid",
      "currency": "CAD",
      "created_by": null,
      "conversation_id": null,
      "amount_refunded": 0,
      "refunded_on": null,
      "clicks_count": 1,
      "card": {
        "last_4_digits": "1111",
        "name_on_card": "John Doe",
        "brand": "Visa",
        "exp_month": "05",
        "exp_year": "2024"
      },
      "refunds": [],
      "public_url": "https://pay.kimoby.com/2239109u1291012948932",
      "invoice_paid_at": "2020-04-15T15:04:23-04:00",
      "created_at": "2020-04-15T00:00:00-04:00",
      "updated_at": "2020-04-15T15:04:23-04:00"
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 1,
    "items": 1,
    "per_page": 25
  }
}

Document Model

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

Attribute Type Description
id Number Unique identifier. It is generated by Kimoby.
name String The name of the document (filename).
type String The mime type of the file.
url String URL to access the file's content.
url_expires_at String The UTC expiration date of the document's URL, which is 24 hours after the URL creation date. Date with time in RFC 3339 format.
created_at String The creation date of the document. Date with time in RFC 3339 format.
updated_at String The last update date of the document. Date with time in RFC 3339 format.
{
    "id": 1,
    "name": "test.png",
    "type": "image/png",
    "url": "https://file-server.com/1562874077",
    "url_expires_at": "2019-06-01T00:00:00Z",
    "created_at": "2019-05-31T00:00:00-04:00",
    "updated_at": "2019-05-31T00:00:00-04:00"
}

/documents

Upload and create a document.

To create a document, send the document’s file as part of the multipart/form-data of the request.

If there is a validation error it will be returned in JSON as mentioned in the Error Section, otherwise, the document will be returned.

$ curl -s https://api.kimoby.com/v1/documents \
-X POST \
-u {api_key}:{api_secret} \
-H 'Content-Type:multipart/form-data' \
--form 'file=@/home/user/Documents/test.png'
{
  "id": 1234,
  "name": "test.png",
  "type": "image/png",
  "url": "https://file-server.com/1562874077",
  "url_expires_at": "2019-06-01T00:00:00Z",
  "created_at": "2019-05-31T00:00:00-04:00",
  "updated_at": "2019-05-31T00:00:00-04:00"
}

/documents

Retrieve a Document

Parameters
id
integer

The id generated by Kimoby.

To retrieve a document, add the document’s id in the URI segment: "https://api.kimoby.com/v1/documents/1234"

$ curl -s https://api.kimoby.com/v1/documents/1234 \
 -X GET \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret}
{
  "id": 1234,
  "name": "test.png",
  "type": "image/png",
  "url": "https://file-server.com/1562874077",
  "url_expires_at": "2019-06-01T00:00:00Z",
  "created_at": "2019-05-31T00:00:00-04:00",
  "updated_at": "2019-05-31T00:00:00-04:00"
}

Delete a Document

Parameters
id
integer

The id generated by Kimoby.

To delete a document, we first need to find the document. To do so, add the document’s id in the URI segment: "https://api.kimoby.com/v1/documents/1234"

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

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

Custom Attributes Model

Custom Attributes are key/value object associated to a Customer, an Appointment or an 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 a specific object, set the value to null.

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

NOTE: Custom attributes 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
}

Webhook Model

A webhook object contains the following attributes.

It matches the webhook JSON schema except on creation where it matches it matches the webhook with authentication key JSON schema.

Attribute Type Description
id String Unique string identifier. It is generated by Kimoby.
url String The URL of the webhook endpoint.
authentication_key String The wehbook endpoint secret generate the signature. Only returned at creation.
created_at String The creation date of the webhook. Date with time in RFC 3339 format.
updated_at String The last update date of the webhook. Date with time in RFC 3339 format.
{
    "id": "WH487d9d59d5511879e2eda871b5cac50c",
    "url": "https://your.app.com/webhook/path",
    "authentication_key": "1vb3auxyhmRZ1AyuCdT4AzNS0fz2RL61Elowdhxw",
    "created_at": "2016-06-28T15:00:00+00:00",
    "updated_at": "2016-06-28T15:00:00+00:00"
}

/webhooks

Create a Webhook

To create a webhook, provide the url pointing on your application server where you want to receive webhook events. The schema of the url must be HTTPS.

If there is a validation error it will be returned in JSON as mentioned in the Error Section, otherwise, the webhook will be returned.

The webhook authentication_key is only returned on the creation of the webhook, so make sure to store it properly to be able to validate the authenticity of the webhook request.

The response matches the webhook with authentication key JSON schema

$ curl -s https://api.kimoby.com/v1/webhooks \
-X POST \
-H 'Accept:application/json' \
-u {api_key}:{api_secret} \
-H 'Content-Type:application/json' \
--data-raw '{"url":"https://your.app.com/webhook/path"}'
{
  "id": "WH487d9d59d5511879e2eda871b5cac50c",
  "url": "https://your.app.com/webhook/path",
  "authentication_key": "1vb3auxyhmRZ1AyuCdT4AzNS0fz2RL61Elowdhxw",
  "created_at": "2016-06-28T15:00:00+00:00",
  "updated_at": "2016-06-28T15:00:00+00:00"
}

/webhooks

List Webhooks

Get a list of webhook objects.

The response matches the webhooks JSON schema

$ curl -s https://api.kimoby.com/v1/webhooks \
  -X GET \
  -H 'Accept:application/json' \
  -u {api_key}:{api_secret}
[
  {
    "id": "WH487d9d59d5511879e2eda871b5cac50c",
    "url": "https://your.app.com/webhook/path",          
    "created_at": "2016-06-28T15:00:00+00:00",
    "updated_at": "2016-06-28T15:00:00+00:00"
  }
]

/webhooks/:id

Update a Webhook

Update a webhook. You can only update the url attribute.

If there is a validation error it will be returned in JSON as mentioned in the Error Section, otherwise, the webhook will be returned (without the authentication key).

The response matches the webhook JSON schema

$ curl -s https://api.kimoby.com/v1/webhooks/WH487d9d59d5511879e2eda871b5cac50c \
 -X PUT \
 -H 'Accept:application/json' \
 -u {api_key}:{api_secret} \
 -H 'Content-Type:application/json' \
 --data-raw '{"url":"https://your.app.com/webhook/path/updated"}'
{
  "id": "WH487d9d59d5511879e2eda871b5cac50c",
  "url": "https://your.app.com/webhook/path/updated",
  "created_at": "2016-06-28T15:00:00+00:00",
  "updated_at": "2016-06-29T15:00:00+00:00"
}

/webhooks/:id

Delete a Webhook

Delete a webhook.

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

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