API docs by Redocly

Cyclis Integrator API (1.2.1)

Download OpenAPI specification:Download

Cyclis API info: info@cyclis.be URL: https://www.cyclis.be

introduction

The Cyclis integrator API is designed arround the JSON:API specification.
This API is designed for external systems integrating with Cyclis,
and allows Integrators to create Get Cyclists, Companies, Dealers and Orders and also allows to Create Cyclists and approve orders.

Authentication

*An API key must be obtained from Cyclis.*
This API key must be included with every request in a HTTP request header called API-TOKEN

Error codes

when an error occurs, an "error" and a "message" field will be returned. Those will contain the relevant error code and a human readable description

Change log

1.4.0

Cyclist fields

Added the fields metadata and external_identifier to cyclists.

1.3.0 - 16/05/2022

Extra order fields

Added the fields bike_type, bike_frame_type, bike_size, bike_color and bike_order_state.

Company callback

An extra callback is added which is called when a company is added or deleted from an API key.

Cyclist create

The field saml_uid is added to the cyclist create call. This technical field is used in SAML single sign on integrations.

Callback documentation

The documentation about the callbacks didn't reflect the implementation. This has been fixed.

1.2.1 - 30/06/2021

Search cyclist by email

The key filter[email]=<email> has been made case insensitive.

1.2.0 - 22/06/2021

Search cyclist by email

The cyclist list can now by filtered by email by adding filter[email]=<email> to the request query string.

1.1.0 - 21/04/2021

Orders in review added

Orders in review can now be retrieved from through the API. An extra state quote_to_review has been added to the orders. Orders in this state are read only and can't be edited through the API.

1.0.0 - 15/01/2021

Initial release

Entities

Returns a list of companies

All companies to which the used API key has access.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Returns a specific company.

Get the company information with a specific UUID.

path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Returns a list of cyclists, linked to a company you have access to.

Cyclist definition: A person, linked to a company, who is allowed to request quotations, who has a existing lease contract, ...

Can be filtered on company using company_id param

An email is NOT guaranteed to be unique. In some cases multiple cyclists exist with the same email. Cyclis will make every effort to prevent multiple cyclists per email. Please contact Cyclis if multiple cyclists per email are found.

query Parameters
company_id
string <uuid>
filter[email]
string

Return only cyclists with the provided email. Note an email is not guaranteed to be unique. In some cases multiple cyclists exist with the same email.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Creates a new cyclist assigned to a specific company

Request Body schema: application/json
object (CyclistCreate)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Returns a cyclist with a specific uuid

path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates a cyclist

path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
object (CyclistPatch)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Returns a list of all dealers

Get all known dealers

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Orders

Retrieves all orders

Returns orders available to a specific API key.

query Parameters
company_id
string <uuid>

Limit the orders to a single company. If this is used with cyclist_id, the cyclist_id must be a member of the company.

cyclist_id
string <uuid>

Limit the orders to a single cyclist. If this is used with company_id, the cyclist_id must be a member of the company.

updated_since
string <date-time>

Only returns orders updated since that date or date-time.

Example "2021-12-30" or "2021-12-15T10:30:00"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieves a single order

path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates a single order

Status can be updated if the status is in "quote", "quote_sent" or "approved_cyclist" The HR always has to approve the Order, the Cyclist can also approve, but it will not be confirmed before HR has accepted the order.

Note: This is a PATCH method and the status field triggers changes on the sale order and other internal processes. Calling this multiple times will probably fail and/or have unintended effects. This status field is not the same as the status field in the GET sale order method.

path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Callbacks

Subscribe to the callback

Only one callback URL can be active at a time. To prevent loss of data, the callback url should be cleared first with a DELETE request before setting a new one.

Request Body schema: application/json

Send the URL which should be called on callback

object (RegisterCallback)

Responses

Callbacks

Request samples

Content type
application/json
{}

Callback payload samples

Callback
Content type
application/json
{
  • "data": {
    }
}

Remove the existing callback

Responses