Support Tickets¶

19 endpoints. Authentication, errors, paging and rate limits are described once, in the API overview.

Action	Method	Description
`addticketnote`	POST	Add a staff note to a ticket
`addticketreply`	POST	Add a reply to an existing ticket
`blockticketsender`	POST	Block a ticket sender
`deleteticket`	POST	Delete a ticket and all its replies
`deleteticketnote`	POST	Delete a staff note from a ticket
`deleteticketreply`	POST	Delete a specific ticket reply
`getsupportdepartments`	GET	List all support departments
`getsupportstatuses`	GET	List the ticket statuses
`getticket`	GET	Get a single ticket with replies
`getticketattachment`	GET	List or download the files on a ticket
`getticketcounts`	GET	Count tickets by status
`getticketnotes`	GET	List the staff notes on a ticket
`getticketpredefinedcats`	GET	List the canned reply categories
`getticketpredefinedreplies`	GET	List canned replies
`gettickets`	GET	List support tickets with optional filtering
`mergeticket`	POST	Merge one ticket into another
`openticket`	POST	Open a new support ticket
`updateticket`	POST	Update ticket status or details
`updateticketreply`	POST	Edit a ticket reply

addticketnote¶

Add a staff note to a ticket.

POST /api/v1/addticketnote

Permission: manage_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket.
`message`	string	yes	The note. Staff only; the client never sees it.

Response

Field	Description
`result`	`success`
`noteid`	integer

Errors

Status	When
404	No such ticket.

Example

curl -X POST https://example.com/api/v1/addticketnote \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1" \
  --data-urlencode "message=example"

addticketreply¶

Add a reply to an existing ticket.

POST /api/v1/addticketreply

Permission: reply_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket.
`message`	string	yes	The reply.
`adminusername`	string	no	Any value: the reply is from staff, signed by the staff member the credential belongs to. Left out, the reply is the client's.
`userid`	integer	no	For a client reply: which client. Default: the ticket's client.

Response

Field	Description
`result`	`success`
`replyid`	integer

Errors

Status	When
404	No such ticket.

Note

The ticket status and the notification mails follow, as for a reply from the panel.

Example

curl -X POST https://example.com/api/v1/addticketreply \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1" \
  --data-urlencode "message=example"

blockticketsender¶

Block a ticket sender.

POST /api/v1/blockticketsender

Permission: manage_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket whose sender to block.
`delete`	boolean	no	Delete the ticket as well.

Response

Field	Description
`result`	`success`
`ticketid`	integer
`blocked`	string: the blocked address

Errors

Status	When
404	No such ticket.
422	The ticket has no sender address.

Note

Adds the address to the ticket spam filter: no more tickets from it, by mail or by form.

Example

curl -X POST https://example.com/api/v1/blockticketsender \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1"

deleteticket¶

Delete a ticket and all its replies.

POST /api/v1/deleteticket

Permission: manage_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket.

Response

Field	Description
`result`	`success`

Errors

Status	When
404	No such ticket.

Example

curl -X POST https://example.com/api/v1/deleteticket \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1"

deleteticketnote¶

Delete a staff note from a ticket.

POST /api/v1/deleteticketnote

Permission: manage_tickets

Parameters

Name	Type	Required	Description
`noteid`	integer	yes	The note.

Response

Field	Description
`result`	`success`

Errors

Status	When
404	No such note.

Example

curl -X POST https://example.com/api/v1/deleteticketnote \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "noteid=1"

deleteticketreply¶

Delete a specific ticket reply.

POST /api/v1/deleteticketreply

Permission: reply_tickets

Parameters

Name	Type	Required	Description
`replyid`	integer	yes	The reply.

Response

Field	Description
`result`	`success`

Errors

Status	When
404	No such reply.

Example

curl -X POST https://example.com/api/v1/deleteticketreply \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "replyid=1"

getsupportdepartments¶

List all support departments.

GET /api/v1/getsupportdepartments

Permission: list_tickets

Parameters

None.

Response

Field	Description
`result`	`success`
`departments`	array of support departments in their display order

Example

curl -G https://example.com/api/v1/getsupportdepartments \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getsupportstatuses¶

List the ticket statuses.

GET /api/v1/getsupportstatuses

Permission: list_tickets

Parameters

None.

Response

Field	Description
`result`	`success`
`statuses`	array of ticket statuses in their display order

Example

curl -G https://example.com/api/v1/getsupportstatuses \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getticket¶

Get a single ticket with replies.

GET /api/v1/getticket

Permission: list_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket.

Response

Field	Description
`result`	`success`
`ticket`	object: the ticket with its department, replies and staff notes

Errors

Status	When
404	No such ticket.

Example

curl -G https://example.com/api/v1/getticket \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1"

getticketattachment¶

List or download the files on a ticket.

GET /api/v1/getticketattachment

Permission: list_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket.
`attachmentindex`	integer	no	Which file. Left out, the files are listed instead.

Response

Field	Description
`result`	`success`
`attachments`	without attachmentindex: array of
`filename`	with attachmentindex: string
`data`	with attachmentindex: the file, base64 encoded

Errors

Status	When
404	No such ticket, or no file at that index.

Example

curl -G https://example.com/api/v1/getticketattachment \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1"

getticketcounts¶

Count tickets by status.

GET /api/v1/getticketcounts

Permission: list_tickets

Parameters

None.

Response

Field	Description
`result`	`success`
`counts`	object: all, open, answered, customer_reply, on_hold, closed

Example

curl -G https://example.com/api/v1/getticketcounts \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getticketnotes¶

List the staff notes on a ticket.

GET /api/v1/getticketnotes

Permission: list_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket.

Response

Field	Description
`result`	`success`
`notes`	array of staff notes

Errors

Status	When
404	No such ticket.

Example

curl -G https://example.com/api/v1/getticketnotes \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1"

getticketpredefinedcats¶

List the canned reply categories.

GET /api/v1/getticketpredefinedcats

Permission: list_tickets

Parameters

None.

Response

Field	Description
`result`	`success`
`categories`	array of canned reply categories

Example

curl -G https://example.com/api/v1/getticketpredefinedcats \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getticketpredefinedreplies¶

List canned replies.

GET /api/v1/getticketpredefinedreplies

Permission: list_tickets

Parameters

Name	Type	Required	Description
`catid`	integer	no	Only this category.

Response

Field	Description
`result`	`success`
`replies`	array of canned replies

Example

curl -G https://example.com/api/v1/getticketpredefinedreplies \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

gettickets¶

List support tickets with optional filtering.

GET /api/v1/gettickets

Permission: list_tickets

Parameters

Name	Type	Required	Description
`clientid`	integer	no	Only this client's tickets. userid is accepted too.
`deptid`	integer	no	Only this department.
`status`	string	no	A ticket status, such as Open, Answered, Customer-Reply or Closed.
`limitstart`	integer	no	Where the page starts. Default 0.
`limitnum`	integer	no	Page size, 1 to 250. Default 25.

Response

Field	Description
`result`	`success`
`totalresults`	integer: rows matching the filters
`startnumber`	integer: where this page starts
`numreturned`	integer: rows on this page
`data`	array: the rows

Note

Most recently active first.

Example

curl -G https://example.com/api/v1/gettickets \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

mergeticket¶

Merge one ticket into another.

POST /api/v1/mergeticket

Permission: manage_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket to merge away.
`mergeid`	integer	yes	The ticket to merge into.

Response

Field	Description
`result`	`success`
`ticketid`	integer: the ticket that remains

Errors

Status	When
404	Either ticket does not exist.
422	The two ids are the same.

Note

The replies and staff notes move to mergeid; ticketid is closed and points to it.

Example

curl -X POST https://example.com/api/v1/mergeticket \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1" \
  --data-urlencode "mergeid=1"

openticket¶

Open a new support ticket.

POST /api/v1/openticket

Permission: reply_tickets

Parameters

Name	Type	Required	Description
`deptid`	integer	yes	The support department.
`subject`	string	yes	Up to 255 characters.
`message`	string	yes	The first message.
`email`	email	yes	The sender address.
`clientid`	integer	no	The client, when the sender is one. userid is accepted too.
`name`	string	no	The sender name, for a guest.
`priority`	string	no	low, medium (default), high or critical.
`adminusername`	string	no	Any value: the ticket is opened by staff.

Response

Field	Description
`result`	`success`
`tid`	string: the six-digit ticket number
`ticketid`	integer

Note

The acknowledgement to the sender and the alert to support go out as for any new ticket.

Example

curl -X POST https://example.com/api/v1/openticket \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "deptid=1" \
  --data-urlencode "subject=example" \
  --data-urlencode "message=example" \
  --data-urlencode "email=client@example.com"

updateticket¶

Update ticket status or details.

POST /api/v1/updateticket

Permission: manage_tickets

Parameters

Name	Type	Required	Description
`ticketid`	integer	yes	The ticket.
`status`	string	no	One of the ticket statuses configured here (any letter case).
`subject`	string	no	Up to 255 characters.
`priority`	string	no	low, medium, high or critical.
`deptid`	integer	no	Move it to this department.
`flag`	integer	no	Assign it to this staff account (admin id).

Response

Field	Description
`result`	`success`
`ticketid`	integer

Errors

Status	When
404	No such ticket.

Example

curl -X POST https://example.com/api/v1/updateticket \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "ticketid=1"

updateticketreply¶

Edit a ticket reply.

POST /api/v1/updateticketreply

Permission: reply_tickets

Parameters

Name	Type	Required	Description
`replyid`	integer	yes	The reply.
`message`	string	no	The new text. Cannot be empty.

Response

Field	Description
`result`	`success`
`replyid`	integer

Errors

Status	When
404	No such reply.

Example

curl -X POST https://example.com/api/v1/updateticketreply \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "replyid=1"