Creating a ticket
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.
source String, Optional "PHONE", "MANUAL", "NAME" or "PRINTER"
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: SECRET_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", "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 10000. If no limit is specified, 1000 will be used.
order Optional parameter for ordering results. Valid values are "id", "number", "created" and "called". It's allowed to specify asc or desc ordering. Eg. "id ASC", "created DESC".
responseScope Optional parameter for additional details about the found tickets. Value "MESSAGES" will also include ticket messages with response.

Response

{
  "statusCode": 200,
  "data": [
    {
      "id": "323165",
      "number": 1,
      "line": 3125,
      "source": "PHONE",
      "status": "SERVED",
      "created": {
        "date": "2014-01-03T14:23:05Z"
      },
      "called": {
        "date": "2014-01-03T14:45:55Z",
        "desk": 4,
        "caller": 4232
      }
    },
    {
      "id": "323166",
      "number": 2,
      "line": 3125,
      "source": "NAME",
      "status": "NEW",
      "created": {
        "date": "2014-01-03T14:33:45Z"
      },
      "labels": [
        {
          "color": "FF4136",
          "value": "Important"
        }
      ],
      "extra": [
        {
          "title": "Website",
          "value": "Google",
          "url": "http://www.google.com"
        }
      ]
    }
  ]
}
These fields are wrapped in a data object:
Response field Type Description
id String A unique ticket ID
number Number Ticket number
line Number Line ID
source String Source of the ticket. "PHONE", "MANUAL", "NAME" or "PRINTER". This field will not be present if no source has been specified when creating a ticket.
status String Ticket status. "NEW", "CALLED", "CANCELLED", "CANCELLED_BY_CLERK", "NOSHOW" or "SERVED"
firstName String First name
lastName String Last name
phoneNumber Number Phone number
created.date Date Time when ticket was created in ISO 8601 format.
called.date Date Time when ticket was called in ISO 8601 format.
called.desk Number Desk number
called.caller Number User ID of a caller
labels Array Array of labels
extra Array Array of extra fields
messages Array Array of ticket messages, if the "MESSAGES" response scope was set. Array is formatted similarly to messages endpoint
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 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: SECRET_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

Response

 {
  "statusCode": 200,
  "id": "7643",
  "number": 44,
  "source": "PRINTER",
  "status": "CALLED",
  "line": 27346,
  "created": {
    "date": "2014-01-20T09:37:43Z"
  },
  "extra": [
    {
      "title": "Website",
      "value": "Google",
      "url": "http://www.google.com"
    }
  ]
}
Response field Type Description
id String Ticket ID
number Number Ticket number
source String Source of the ticket. "PHONE", "MANUAL", "NAME" or "PRINTER". This field will not be present if no source has been specified when creating a ticket.
status String Ticket status. Always "CALLED"
line Number Line ID
firstName String First name
lastName String Last name
phoneNumber Number Phone number
created.date Date Creation date in ISO 8601 format
extra Array Array of extra fields
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 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: SECRET_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

Response

{
  "statusCode": 200,
  "id": "7642",
  "number": 43,
  "source": "PRINTER",
  "status": "CALLED",
  "line": 27346,
  "created": {
    "date": "2014-01-20T09:37:43Z"
  },
  "extra": [
    {
      "title": "Website",
      "value": "Group: Herded dolphins to be slaughtered at Japan's Taiji Cove",
      "url": "http://edition.cnn.com/2014/01/20/world/asia/japan-dolphin-hunt/index.html?hpt=hp_c3"
    }
  ]
}
Response field Type Description
id String Ticket ID
number Number Ticket number
source String Source of the ticket. "PHONE", "MANUAL", "NAME" or "PRINTER". This field will not be present if no source has been specified when creating a ticket.
status String Ticket status. Always "CALLED"
line Number Line ID
firstName String First name
lastName String Last name
phoneNumber Number Phone number
created.date Date Creation date in ISO 8601 format
extra Array Array of extra fields
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: SECRET_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: SECRET_KEY"
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
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: SECRET_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: SECRET_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: SECRET_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: SECRET_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: SECRET_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: SECRET_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: SECRET_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: SECRET_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"
Reordering
POST /tickets/ id /reorder

Reorders a ticket to be after another ticket in the list of tickets waiting to be called.

Request

  curl -X POST https://api.qminder.com/v1/tickets/14850/reorder
  --data "after=14889"
  -H "X-Qminder-REST-API-Key: SECRET_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: SECRET_KEY"
Request parameter Type Description
responseScope String, Optional Parameter for additional details about the found tickets. Value "MESSAGES" will also include ticket messages with response.

Response

{
  "statusCode": 200,
  "id": "344185",
  "number": 45,
  "source": "PRINTER",
  "status": "SERVED",
  "line": 27346,
  "created": {
    "date": "2014-01-20T09:37:43Z"
  },
  "called": {
    "date": "2014-01-20T09:39:33Z",
    "caller": 28458
  },
  "served": {
    "date": "2014-01-20T09:48:13Z"
  },
  "extra": [
    {
      "title": "Website",
      "value": "Group: Herded dolphins to be slaughtered at Japan's Taiji Cove",
      "url": "http://edition.cnn.com/2014/01/20/world/asia/japan-dolphin-hunt/index.html?hpt=hp_c3"
    }
  ],
  "labels": [
    {
      "color": "FF4136",
      "value": "VIP"
    }
  ]
}
Response field Type Description
id String Ticket ID
number Number Ticket number
source String Source of the ticket. "PHONE", "MANUAL", "NAME" or "PRINTER". This field will not be present if no source has been specified when creating a ticket.
status String Ticket status. "NEW", "CALLED", "CANCELLED", "CANCELLED_BY_CLERK", "NOSHOW" or "SERVED"
line Number Line ID
firstName String First name
lastName String Last name
phoneNumber Number Phone number
created.date Date Creation date in ISO 8601 format
called.date Date Call date in ISO 8601 format
called.caller Number User ID of a clerk who called the ticket
called.desk Number Desk number
served.date Date Date of the end of the service in ISO 8601 format
extra Array Array of extra fields
labels Array Array of labels
messages Array Array of ticket messages, if the "MESSAGES" response scope was set. Array is formatted similarly to messages endpoint
Estimated time of service
GET /tickets/ id /estimated-time

Get the estimated time of service of a ticket.

Request

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

Response

{
  "statusCode": 200,
  "estimatedTimeOfService": 1496234920
}
Response field Type Description
estimatedTimeOfService Number The estimated time of service as seconds from epoch. Not included if no estimation can be made.
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: SECRET_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: SECRET_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: SECRET_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"