Tickets API Documentation

POST /lines/ id /ticket

Creates a new ticket.
It is possible to add extra data (ID number, website URL, age, gender etc) while creating a ticket.

Request

  curl -X POST https://api.qminder.com/v1/lines/1827/ticket \
  -H "X-Qminder-REST-API-Key: KEY" \
  -d "firstName=Marta" \
  -d "lastName=Murakas" \
  -d "extra=[{\"title\":\"Eyes\", \"value\":\"Blue\"}]"

Request parameter	Type	Description
firstName	String, Optional	First name
lastName	String, Optional	Last name
phoneNumber	Number, Optional	Phone number with country code. For example Estonian (code 372) phone number 53 12345 would be 3725312345.
email	String, Optional	Email address
source	String, Optional	"PHONE", "MANUAL" or "NAME"
extra	JSON array, Optional	Array of custom fields. All fields have following parameters: title, Mandatory value, Mandatory url, Optional editable, Optional. If false, ticket can't be edited in the Dashboard. Example: `[ { "title": "ID code", "value": 1234567890 }, { "title": "Website", "value": "CNN website", "url": "http://edition.cnn.com", "editable": false } ]`

Response

{
  "statusCode": 200,
  "id": "226859"
}

Response field	Type	Description
id	String	A unique ID of a created ticket

Searching Tickets

GET /tickets/search

Searches for tickets which match given search criteria.
List of tickets will be returned.

Request

  curl https://api.qminder.com/v1/tickets/search
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Description
location	Optional parameter for searching tickets in specified location.
line	Optional comma separated list of lines to search tickets from.
status	Optional parameter for searching tickets with specified status(es). Comma separated list of "NEW", "CALLED", "CANCELLED_BY_CLERK", "NOSHOW" or "SERVED"
caller	Optional parameter for searching tickets which were called by specified user ID.
minCreated	Optional parameter for searching tickets which are created after specified time. UTF Unix timestamp or ISO 8601.
maxCreated	Optional parameter for searching tickets which are created before specified time. UTF Unix timestamp or ISO 8601.
minCalled	Optional parameter for searching tickets which are called after specified time. UTF Unix timestamp or ISO 8601.
maxCalled	Optional parameter for searching tickets which are called before specified time. UTF Unix timestamp or ISO 8601.
limit	Optional parameter for limiting number of search results. Value has to be between 1 and 20000. If no limit is specified, 20000 will be used.
order	Optional parameter for ordering results. Valid values are "id", "number", "created", "called" and "served". It's allowed to specify asc or desc ordering. Eg. "id ASC", "created DESC".
responseScope	Optional comma-seperated parameter for additional details about the found tickets. Value "MESSAGES" will also include ticket messages with response. Value "INTERACTIONS" will include interactions messages with response. Value "CONNECTED_TICKETS" will include tickets which have same phone number or email address.

Response

Returns a list of tickets which are wrapped in a data object.

Counting Tickets

GET /tickets/count

Returns count of tickets which match given search criteria.

Request

  curl https://api.qminder.com/v1/tickets/count
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Description
location	Optional parameter for searching tickets in specified location.
line	Optional comma separated list of lines to search tickets from.
status	Optional parameter for searching tickets with specified status(es). Comma separated list of "NEW", "CALLED", "CANCELLED_BY_CLERK", "NOSHOW" or "SERVED"
caller	Optional parameter for searching tickets which were called by specified user ID.
minCreated	Optional parameter for searching tickets which are created after specified time. UTF Unix timestamp or ISO 8601.
maxCreated	Optional parameter for searching tickets which are created before specified time. UTF Unix timestamp or ISO 8601.
minCalled	Optional parameter for searching tickets which are called after specified time. UTF Unix timestamp or ISO 8601.
maxCalled	Optional parameter for searching tickets which are called before specified time. UTF Unix timestamp or ISO 8601.

Response

{
  "statusCode": 200,
  "count": 43
}

Calling a ticket from list

POST /tickets/call

Calls a next ticket from list of lines. Tickets are sorted chronologically and the oldest ticket will be called.
Tickets assigned to the user have a higher priority than the ones which are not assigned to anybody.
Tickets assigned to someone else will not be called. If you need to call a ticket which is assigned to someone else, call the ticket by its ID.
If user is serving someone, the current ticket by default will be marked as "SERVED" before calling the next ticket from the list.

Request

  curl -X POST https://api.qminder.com/v1/tickets/call
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
lines	List of Number, Mandatory	Comma separated list of lines where next ticket should be called
user	Number, Optional	User ID of a clerk who calls the ticket. Only needed if calling ticket on behalf a user
desk	Number, Optional	Desk number where ticket was called. Mandatory if selecting a desk is mandatory in location
keepActiveTicketsOpen	Boolean, Optional	Setting to "true" will cause any tickets that are being served to remain that way, instead of being marked "SERVED"

Response

Returns a ticket.

Calling a ticket

POST /tickets/ id /call

Calls the ticket. Ticket can be called only when its status is "NEW".
If user is serving someone, the current ticket will by default be marked as "SERVED" before calling the ticket.

Request

  curl -X POST https://api.qminder.com/v1/tickets/7642/call
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
user	Number, Optional	User ID of a clerk who calls the ticket. Only needed if calling ticket on behalf a user
desk	Number, Optional	Desk number where ticket was called. Mandatory if selecting a desk is mandatory in location
keepActiveTicketsOpen	Boolean, Optional	Setting to "true" will cause any tickets that are being served to remain that way, instead of being marked "SERVED"

Returns a ticket.

Recalling a ticket

POST /tickets/ id /recall

Recalls the ticket. Ticket can be recalled only when its status is "CALLED".

Request

  curl -X POST https://api.qminder.com/v1/tickets/14846/recall
  -H "X-Qminder-REST-API-Key: KEY"

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Editing a ticket

POST /tickets/ id /edit

Edits tickets fields.

Request

  curl -X POST https://api.qminder.com/v1/tickets/14848/edit
  -H "X-Qminder-REST-API-Key: KEY" \
  -d "extra=[{\"title\":\"Eyes\", \"value\":\"Brown\"}]"

Request parameter	Type	Description
line	Number, Optional	ID of the line. New line has to be in the same location as the current one. If no value is provided, ticket will remain in the same line.
user	Number, Optional	User ID of a clerk who edits the ticket
phoneNumber	Number, Optional	Phone number with country code. For example Estonian (code 372) phone number 53 12345 would be 3725312345.
firstName	String, Optional	First name
lastName	String, Optional	Last name
email	String, Optional	Email address
extra	JSON array, Optional	Array of custom fields. All fields have following parameters: title, Mandatory value, Mandatory url, Optional Example: `[ { "title": "ID code", "value": 1234567890}, { "title": "Website", "value": "CNN website", "url": "http://edition.cnn.com" } ]`

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Marking ticket served

POST /tickets/ id /markserved

Marks ticket as "SERVED". Ticket can be marked served only when its status is "CALLED".

Request

  curl -X POST https://api.qminder.com/v1/tickets/14848/markserved
  -H "X-Qminder-REST-API-Key: KEY"

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Marking ticket no show

POST /tickets/ id /marknoshow

Marks ticket as "NOSHOW". Ticket can be marked as no show only when its status is "CALLED".

Request

  curl -X POST https://api.qminder.com/v1/tickets/14848/marknoshow
  -H "X-Qminder-REST-API-Key: KEY"

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Cancelling a ticket

POST /tickets/ id /cancel

Cancels the ticket. Ticket can be cancelled only when its status is "NEW".

Request

  curl -X POST https://api.qminder.com/v1/tickets/14849/cancel
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
user	Number, Mandatory	User ID of a clerk who cancels the ticket

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Return to queue

POST /tickets/ id /returntoqueue

Returns ticket back to the queue, ticket will be in the "NEW" status. Ticket can be returned to the queue only when its status is "CALLED".

Request

curl -X POST https://api.qminder.com/v1/tickets/14849/returntoqueue?user=USER&position=POSITION
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
user	Number, Mandatory	User ID of a clerk who returns the ticket to the queue
position	String, Mandatory	"FIRST", "MIDDLE" or "LAST"

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Forward

POST /tickets/ id /forward

Forwards ticket to a different line, status of the ticket will be set to "NEW". Ticket can be forwarded only when its status is "CALLED".

Request

curl -X POST https://api.qminder.com/v1/tickets/14849/forward \
-d user=USERID -d line=LINEID \
-H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
user	Number, Optional	User ID of a clerk who forwards the ticket. Only needed if forwarding a ticket on behalf a user
line	Number, Mandatory	ID of a line where to forward the ticket to

Response

{
  "statusCode": 200,
}

Labelling a ticket

POST /tickets/ id /labels/add

Adds new label to the ticket if it does not exist already.

Request

  curl -X POST https://api.qminder.com/v1/tickets/14849/labels/add
  --data "value=Important&user=123"
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
value	String	Value of the label to be added
user	Number, Mandatory	User ID of a clerk who adds the label

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	"success" if label was added successfully; "no action" if ticket already has a label with this value

Removing a label

POST /tickets/ id /labels/remove

Removes the label from the ticket.

Request

  curl -X POST https://api.qminder.com/v1/tickets/14849/labels/remove
  --data "value=Important&user=123"
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
value	String	Value of the label to be removed
user	Number, Mandatory	User ID of a clerk who removes the label

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Assigning to a user

POST /tickets/ id /assign

Assigns ticket to a user. Status of the ticket has to be "NEW".

Request

  curl -X POST https://api.qminder.com/v1/tickets/14849/assign
  --data "assigner=213&assignee=123"
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
assigner	Number, Mandatory	User ID of a clerk who assigned the ticket to another user
assignee	Number, Mandatory	User ID of a clerk who was assigned to the ticket

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Unnasigning

POST /tickets/ id /unassign

Unassigns a ticket. Status of the ticket has to be "NEW".

Request

  curl -X POST https://api.qminder.com/v1/tickets/14849/unassign
  --data "user=213"
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
user	Number, Mandatory	User ID of a clerk who unassigned a ticket

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Reordering

POST /tickets/ id /reorder

Reorders a ticket to be after another ticket in the list of tickets waiting to be called.
This change in the order is reflected in the "orderAfter" parameter of the ticket.
NB! It is not recommended to reorder a ticket between two tickets that have less than 2 ms between their created/orderAfter times, as the results are unpredictable.

Request

  curl -X POST https://api.qminder.com/v1/tickets/14850/reorder
  --data "after=14889"
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
after	String, Optional	ID of a ticket which should be before in the list of tickets. If omitted, ticket will be first in the list

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"

Ticket Details

GET /tickets/ id

Get details of a ticket.

Request

  curl https://api.qminder.com/v1/tickets/226859
  -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
responseScope	Comma-separated array of strings, Optional	Parameter for additional details about the found tickets. Value "MESSAGES" will also include ticket messages with response. Value "INTERACTIONS" will include interactions with response.

Response

Returns a ticket.

Ticket Audit

GET /tickets/ id /audit

Get the audit logs of a ticket.

Request

  curl https://api.qminder.com/v1/tickets/226859/audit
  -H "X-Qminder-REST-API-Key: KEY"

Response

{
  "statusCode": 200,
  "data": [
    {
      "created": "2016-11-22T14:56:07Z",
      "user": 1234,
      "changes": [
        {
          "field": "Email",
          "value": "user@example.com",
          "action": "add.extra"
        }
      ]
    },
    {
      "created": "2016-11-22T15:22:54Z",
      "user": 1234,
      "changes": [
        {
          "color": "39CCCC",
          "value": "labelA",
          "action": "add.label"
        }
      ]
    }
  ]
}

Response field	Type	Description
created	Date	Time when the changes were applied to the ticket in ISO 8601 format.
user	Number	User ID of the user making the changes.
changes	Array	Array of the changes that were made.

Ticket Messages

GET /tickets/ id /messages

Get the messages associated with a ticket.

Request

  curl https://api.qminder.com/v1/tickets/226859/messages
  -H "X-Qminder-REST-API-Key: KEY"

Response

{
  "statusCode": 200,
  "messages": [
    {
      "created":
      {
        "date": "2017-04-12T16:27:57Z"
      },
      "body": "It's your turn!",
      "type": "OUTGOING",
      "status": "SENT",
      "userId": 15000
    },
    {
      "created":
      {
        "date": "2017-04-17T11:50:13Z"
      },
      "body": "Thank you!",
      "type": "INCOMING",
      "status": "NEW"
    }
  ]
}

Response field	Type	Description
created.date	Date	Time when the message was sent or received in ISO 8601 format.
body	String	The contents of the message.
type	String	Type of the message, either OUTGOING or INCOMING.
status	String	The status of the message, one of the following: NEW, SENT, DELIVERED, INVALID_NUMBER.
userId	Number	The user ID of the clerk who sent the message. Null for incoming messages and automatic messages.

Sending an SMS message

POST /tickets/ id /messages

Send an SMS message to the ticket holder.

Request

  curl -X POST https://api.qminder.com/v1/tickets/226859/messages
  -d "message=Hello%2C%20it%27s%20your%20turn%21&user=123" -H "X-Qminder-REST-API-Key: KEY"

Request parameter	Type	Description
message	String	The message you wish to send.
user	Number	The user id of the user sending the message.

Response

{
  "statusCode": 200,
  "result": "success"
}

Response field	Type	Description
result	String	Always "success"