Jifeline Partner API (1.0.0)

To make use of this API you need to have a Client ID and Client Secret.

With these credentials you can request a token which you will need to access the resources from this API.

1. Login into your Partner Portal.
2. Go to "Settings" via the menu on the left side.
3. Click on the "Manage Partner API credentials"-button to go to the API credentials management screen.

Create new API credentials

1. In the API credentials management screen.
2. Click "Add new API credentials" button at the bottom to open a form.
3. Provide a "Credential name" which allows you to quickly recognize the intended use of the new credentials. E.g. the name of the application that will be using it.
4. Specify if the credentials should provide full access to your entire portal, a General credential set, or only access things that are for a specific branding profile, a Branding specific credential set.
5. If you chose "Branding specific credential set", choose the correct branding profile.
6. Click "Generate".
7. Check your e-mail inbox. Within a few minutes you should receive an e-mail containing the Client ID and Client Secret.

Be aware: the Client Secret is only provided once so keep this value somewhere safe.

You can retrieve an access token via our OAuth token endpoint. You can find the full documentation for this endpoint here. The endpoint only supports HTTPS POST. You need to separately retrieve this token before executing any of the other endpoints.

The token endpoint is as follows: https://partner-api-001.prd.jifeline.cloud/oauth2/token.

Request parameters in header

Content-Type : Set the value of this parameter to application/x-www-form-urlencoded.

Request parameters in body

grant_type : Must equal client_credentials.

client_id : Must equal the value received in the email received when generating new credentials. It can also be found in the API credentials management screen.

client_secret : Must equal the value received in the email received when generating new credentials.

Response

In the response body you will find your access token in addition with the amount of seconds until this token is no longer valid.

Example

Example request

curl -X POST https://partner-api-001.prd.jifeline.cloud/oauth2/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials" \
--data "client_id=<yourClientId>" \
--data "client_secret=<yourClientSecret>"

Example response

{
  "expires_in": 3600,
  "access_token": "eyJraWQ.........",
  "token_type": "Bearer"
}

Token validity

The access token is valid for 90 minutes, however it is cached only for 30 minutes. This means that if you request the token again after 35 minutes, you will get a new token even though the previous one was still valid for +-55 minutes.

This gives you the room to implement a refresh mechanism to request a new token before it expires. A safe implementation would be to request a new token every 60 minutes.

To make use of your access token you need to add the following headers to your requests.

Authorization : Must equal Bearer <yourAccessToken>

Example request

curl \
--header 'Authorization: Bearer <yourAccessToken>' \
https://partner-api-001.prd.jifeline.cloud/v2/system/locales

We have created a small example application in Java (JRE/JDK 11) to demonstrate how to authenticate with our Partner API. You can download it here. Please extract the archive and check the README.md for more information.

The Partner API is a RESTFull API with different endpoints which return JSON data regarding all sorts of resources.

The base address of the Partner API is https://partner-api-001.prd.jifeline.cloud.

Resources are accessed via standard HTTP requests in UTF-8 format to an endpoint. The Partner API uses the following HTTP verbs:

To ensure fair use and maintain the performance of the Partner API, the following throttle limits are in place:

Rate Limit: You are allowed 5 requests per second with a burst capacity of 10 requests. This means that while the average rate is 5 requests per second, up to 10 requests can be sent in quick bursts. Once the burst capacity is reached, subsequent requests will be rejected.

Daily Quota: The maximum number of requests you can make to the API in a 24-hour period is 50,000 requests. Once this limit is reached, no additional requests will be processed.

Tips to reduce API usage

1. Use caching

Cache API responses when possible to avoid making repeated requests for the same data. This is especially useful for endpoints that return data that doesn't change often. If possible, consider creating one singular component that communicates with the Partner API instead of multiple. In this way, the cache can be shared by multiple sources.

2. Avoid polling too frequently

If you're polling the API for changes, consider increasing the interval between polls or using events in the /system/events or the Partner Websocket API.

3. Implement exponential backoff

If you hit rate limits, use exponential backoff strategies when retrying requests, rather than retrying immediately.

4. Monitor your usage

Regularly monitor your API usage and set up alerts or dashboards to track it over time. This helps you stay ahead of potential issues.

5. Throttle client requests

Add throttling logic to your application to control how frequently it makes API calls. This can help prevent sudden spikes in traffic.

The Partner API normally returns JSON in the response body (unless explicitly defined otherwise).

Response status codes

Below is a list of status code that are in use. Each resource endpoint will document all response codes that could be expected.

Rate Limit Exceeded Response

If you exceed the throttle limits, the API will return an HTTP status code 429 (Too Many Requests), indicating that you have surpassed the rate or burst limits. In such cases, you should respect the retry-after header or implement appropriate retry logic with backoff to ensure successful future requests. Example of 429 response:

{
  "type": "/problems/too-many-requests",
  "status": 429,
  "title": "Too Many Requests",
  "detail": "You have exceeded the rate limit for this resource. Please wait and try again later."
}

To avoid disruptions, it is recommended to monitor your usage and optimize your request patterns according to the throttle limits.

Error response

The Partner API uses a single response to describe an error. This error response can be detected by the returned status code (4XX or 5XX) and the Content-Type header which will have a value of application/problem+json.

The response itself will be a JSON structure according to RFC-7807. In general this response looks like:

{
  "type": "about:blank",
  "status": 403,
  "title": "Forbidden",
  "detail": "You don't have permission to access this resource."
}

• The status property contains the status code from the response.
• The title property contains short a human-readable summary of the occurred problem.
• The detail property contains a detailed human-readable description of the occurred problem and usually provides more insight into the resolution (if any).
• The type property describes the type of problem and can be used as a discriminator for problem variants with additional properties. Type about:blank is the default and will only contain the aforementioned properties.

Example of a non-default problem type

{
  "type": "/problems/violations",
  "status": 400,
  "title": "Bad request",
  "detail": "The request contains one or more violations. Please resolve all of them and try again.",
  "violations": [
    {
      "property_path": "/customer_id",
      "in": "body",
      "detail": "This value must be a valid UUID."
    }
  ]
}

Note

If a resource endpoint supports one or more of the problem types they will be documented as a possible response.

If the response is for a collection of resources its structure will always look like the following.

{
  "query": {
    // applied query
  },
  "result": [
    // 0 or more resources
    {
      "name": "Resource 1"
    },
    {
      "name": "Resource 2"
    }
  ],
  "total": 2
}

• The query property will always contain the query parameters that have been applied to get the resulting resources. These include all provided query parameters and those not provided, but with a default.
• The result property will contain a list of zero or more resources matching the executed query.
• The total property will contain the total number of resources matching provided query parameters.

If a resource supports the limit and offset query parameters the collection response will only contain a subset of the total available resources (a single page).

• The limit parameter can be used to control the maximum amount of resource returned per page.
• The offset parameter can be used to control the index of the first resource returned. E.g. ?offset=0&limit=25 gives the first page of 25 resources. ?offset=25&limit=25 gives you the second page of 25 resources.

The response will always be a collection response in which the used (provided or default) values for limit and offset are available in its query property. The total property provides the total amount of resources available in the system which gives you insight in the total number of "pages" that could be retrieved.

{
  "query": {
    "limit": 25,
    "offset": 0
  },
  "result": [
    // resources for first "page".
  ],
  "total": 34
}

In the documentation of requests to the API and responses from it, you will frequently encounter properties with a data format.

For example

The id property of a customer has string <uuid> as its data type where uuid is the format for the string that will be returned.

The list below provides some clarification on what these mean and how to handle them.

OAuth2 is used as the authentication protocol for this API.

Customers describe the workshops for which you perform services via tickets.

Manage the connectors of your customers.

Manage a customer's contact points.