API Setup

Introduction

Important: Please read this page carefully and make sure that you have all your credentials and necessary assets available before you start. If you need help, contact us.

The purpose of the Case Management API is to provide an easy way to communicate with clients, providing tools that help manage and automate the handling of such conversations. You can find all those messages in the Case Management section of the Backstage.

This page describes how to set up the Case Management API and request and retrieve information.

Obtain Authentication and Authorization Keys

All requests to Inbenta APIs endpoints will be authenticated and authorized.
In order to start using our APIs you must first contact Inbenta so we can provide you with your own API Key, API Secret and Domain Key:

  • The API Key will grant you access to the APIs.
  • The Secret allows the request to access your instance's data.

Note: For a complete description of keys and authorization methods, see the Authorization section.

Caution: Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations. For more information, see the Authorization page.

Use the access token

You need a valid access token to use Inbenta APIs. Follow the steps listed in the Authorization section to set up your page with your token and refresh it. Once you obtain the access token, you must append it to every request inside the Authorization header, with the format Bearer <your_access_token>.

Get the API URL

The Inbenta API's base URLs depend on the project so we can offer a world wide service and allow service auto-escalation. This base URL may change over time and it should not be persistently stored or cached. Instead, you should get it every time you obtain a new valid access token.

To get the current API URL for your project, there must be a request to https://api.inbenta.io/v1/apis like this:

curl -X GET \
  https://api.inbenta.io/v1/apis \
  -H 'authorization: Bearer <your_access_token>' \
  -H 'x-inbenta-key: <your_API_Key>'

This request will return a response like this:

{
    "apis": {
        "ticketing": "https://endpoint.inbenta.example/prod/ticketing"
    }
}

Use this response to pick the URL for the product that you want to use.

Caution: Do not perform this request after each API call! You would quickly exceed your rate limits.

Specify the version

Once you have picked the appropriate product URL for your implementation, remember to specify the version of the API.

You specify the version at the end of the URL with v + {version}.

Examples:

The URLs for the current latest version of each product API look like this:

  • Case Management: "https://endpoint.inbenta.example/prod/ticketing/v1"

Use the API

Authorization

Note: For a complete description of keys and authorization methods, see the Authorization section.

You need a valid access token to use Inbenta APIs. Follow the steps listed in the Authorization section to set up your page with your token and refresh it.

Caution: Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations.

Ticket flow

Users

You must complete several fields to create a ticket, including the details of the user who created the case. If this was not done already, you can register a user into the Case Management database with the following endpoint:

POST /v1/users HTTP/1.1
Content-Type: application/json

{
    "name": "Lorem Ipsum",
    "address": "test@test.com"
}

This request will return the user's UUID. You can now use it to create the case:

POST /v1/tickets HTTP/1.1
Content-Type: application/json

{
    "message": "Lorem Ipsum",
    "creator": "UUID"
}
Attachments

It is possible to attach files to tickets and replies.

Attached files are converted to a base64 string. The conversion process from a binary file into the base64 representation makes the file roughly 40% larger in size. Because the API Payload limit is 10Mb, this means that you can upoad files up to 7Mb. For more information, click here (This link takes you to an external site unaffiliated with Inbenta).

Note that old browsers without "btoa/binary files API" support must use an external helper to convert the files into a base64 string.

To attach a file, you first need to upload it through the media endpoint:

POST /v1/media HTTP/1.1
Content-Type: application/json

{   
    "name": "file.pdf"
    "content": "Y29udGVudA=="
}

You can use the response to this request (the UUID of the uploaded file) in all the endpoints that support attachments:

POST /v1/tickets HTTP/1.1
Content-Type: application/json

{
    "title": "Testing the API",
    "creator": 1234,
    "message": "This is a test",
    "attachments": [
        "UUID"
    ]
}

It is also possible to add attachments in the body of a message (a.k.a. inline attachments) with the IMG tag like this:

POST /v1/tickets HTTP/1.1
Content-Type: application/json

{ 
"title": "Testing the API", 
"creator": 1234, 
"message": "This is a test: <img src=\"att:UUID\"/>", 
"attachments": [ "UUID" ] 
}

Caution: To avoid people using this service as an online data store system, all the media files that are not used as attachments are deleted after an hour.