Kimoby API Documentation

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}

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}

Getting Started

Customers

Appointments

Events

Messages

Invoices

Documents

Custom Attributes

Webhooks

Parameters

Format

Events

Supported events

Event message_created

Event message_updated

Event customer_unsubscribed

Event customer_resubscribed

Acceptation

Retry

Signature authentication

Algorithm

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Event `message_created`

Event `message_updated`

Event `customer_unsubscribed`

Event `customer_resubscribed`