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