Tickets

Tickets

Tickets and messages. Priority: low, normal, high, urgent (invalid → normal). Scope: tickets.read / tickets.write.

List tickets

GET /v1/tickets

Paginated list of tickets with status, priority, customer and assignee. `search` filters the list. With user credentials only tickets of teams the user may use are listed

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Query
Name Type Description
page integer
per_page integer
search string
Request body

None

Response
data array
id string
number string
subject string
status string

Status name.

priority string

Ticket priority. As input any other value gives `422` (`invalid_value`); an empty value gives `normal` on create and keeps the current priority on update.

Enum
low normal high urgent
Example: normal
client_name string
client_email string
client_id string Nullable
project_id string Nullable
created_at string
assignee object Nullable

Assigned user, or null when unassigned.

id string
name string
meta object
page integer
per_page integer
total integer
pages integer

Examples

GET /v1/tickets
curl -X GET "https://api.appficient.nl/v1/tickets" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json"

Curl, Node and response are shown to the right of this endpoint.

Create a ticket

POST /v1/tickets

Creates a ticket with a `subject`. Link a client with `client_id` (unknown id gives `404`) and/or give the customer's `client_name` and `client_email`. `priority` is `low`, `normal` (default), `high` or `urgent`

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Headers
Name Type Description
Idempotency-Key string Optional. Replay within 24h returns the same response.
Request body
subject string Required
priority string

Ticket priority. As input any other value gives `422` (`invalid_value`); an empty value gives `normal` on create and keeps the current priority on update.

Enum
low normal high urgent
Example: normal
client_name string
client_email string
client_id string
Response
data object

Ticket.

id string
number string
subject string
status string

Status name.

priority string

Ticket priority. As input any other value gives `422` (`invalid_value`); an empty value gives `normal` on create and keeps the current priority on update.

Enum
low normal high urgent
Example: normal
client_name string
client_email string
client_id string Nullable
project_id string Nullable
created_at string
assignee object Nullable

Assigned user, or null when unassigned.

id string
name string
source string
Example: api
updated_at string
closed_at string Nullable
meta object

Examples

POST /v1/tickets
curl -X POST "https://api.appficient.nl/v1/tickets" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "string",
    "priority": "normal",
    "client_name": "string",
    "client_email": "string",
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}'

Curl, Node and response are shown to the right of this endpoint.

Retrieve a ticket

GET /v1/tickets/{id}

One ticket with its status, priority, customer, source and assignee. The messages are listed separately

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Path
Name Type Description
id Required string
Request body

None

Response
data object

Ticket.

id string
number string
subject string
status string

Status name.

priority string

Ticket priority. As input any other value gives `422` (`invalid_value`); an empty value gives `normal` on create and keeps the current priority on update.

Enum
low normal high urgent
Example: normal
client_name string
client_email string
client_id string Nullable
project_id string Nullable
created_at string
assignee object Nullable

Assigned user, or null when unassigned.

id string
name string
source string
Example: api
updated_at string
closed_at string Nullable
meta object

Examples

GET /v1/tickets/{id}
curl -X GET "https://api.appficient.nl/v1/tickets/{id}" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json"

Curl, Node and response are shown to the right of this endpoint.

Update a ticket

PATCH /v1/tickets/{id}

Send at least one field. `status` takes a status name, `assignee_id` a user uuid (empty string unassigns)

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Path
Name Type Description
id Required string
Request body
subject string
priority string

Ticket priority. As input any other value gives `422` (`invalid_value`); an empty value gives `normal` on create and keeps the current priority on update.

Enum
low normal high urgent
Example: normal
client_name string
client_email string
client_id string
status string

Ticket status name as returned by `GET /v1/ticket-statuses`. Unknown names give 422.

assignee_id string

User id (uuid) of the assignee, from `GET /v1/ticket-teams` members. Empty string unassigns. The user must be active in the environment and allowed to use the ticket team.

Response
data object

Ticket.

id string
number string
subject string
status string

Status name.

priority string

Ticket priority. As input any other value gives `422` (`invalid_value`); an empty value gives `normal` on create and keeps the current priority on update.

Enum
low normal high urgent
Example: normal
client_name string
client_email string
client_id string Nullable
project_id string Nullable
created_at string
assignee object Nullable

Assigned user, or null when unassigned.

id string
name string
source string
Example: api
updated_at string
closed_at string Nullable
meta object

Examples

PATCH /v1/tickets/{id}
curl -X PATCH "https://api.appficient.nl/v1/tickets/{id}" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "string",
    "priority": "normal",
    "client_name": "string",
    "client_email": "string",
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "string",
    "assignee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}'

Curl, Node and response are shown to the right of this endpoint.

List messages for a ticket

GET /v1/tickets/{id}/messages

Not paginated

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Path
Name Type Description
id Required string
Request body

None

Response
data array
id string
direction string

API creates are always `out`.

Enum
in out
type string
Enum
reply note
Example: note
body string
created_at string
author object
name string
email string
meta object

Examples

GET /v1/tickets/{id}/messages
curl -X GET "https://api.appficient.nl/v1/tickets/{id}/messages" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json"

Curl, Node and response are shown to the right of this endpoint.

Create a ticket message

POST /v1/tickets/{id}/messages

Adds a message to the ticket thread. By default it is an internal note: the customer does not see it and no email is sent. Give `body` (plain text) or `html`

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Path
Name Type Description
id Required string
Headers
Name Type Description
Idempotency-Key string Optional. Replay within 24h returns the same response.
Request body
body string
html string
type string
Enum
reply note
Example: note
to string
cc string
author_name string
author_email string
plain_text_body boolean
author_user_id integer
Response
data object

Ticket message.

id string
direction string

API creates are always `out`.

Enum
in out
type string
Enum
reply note
Example: note
body string
created_at string
author object
name string
email string
meta object
via_staff_save boolean
email_sent boolean

`false` means stored but not sent; do not retry.

email_error string

Reason the e-mail was not sent. Only present when `email_sent` is `false`.

Examples

POST /v1/tickets/{id}/messages
curl -X POST "https://api.appficient.nl/v1/tickets/{id}/messages" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "string",
    "html": "string",
    "type": "note",
    "to": "string",
    "cc": "string",
    "author_name": "string",
    "author_email": "string",
    "plain_text_body": false,
    "author_user_id": 0
}'

Curl, Node and response are shown to the right of this endpoint.

Send a reply to the customer

POST /v1/tickets/{id}/replies
in

Sends an e-mail reply to the ticket's customer. Recipients are always taken from the ticket: `to`, `cc` and `type` are not allowed and return 422. Every recipient must be a known address: the e-mail address or invoice e-mail address of the customer (client) linked to the ticket, the e-mail address of one of its contact persons, or the sender of an incoming message on this ticket. A sender of an incoming message is only accepted when the recipient is clear or has been confirmed by a user in Appficient. A known address of the linked customer is always accepted, also on a ticket without incoming mail. Otherwise the reply returns `422` `recipient_unconfirmed` and nothing is stored or sent: confirm the recipient in Appficient, or link the ticket to the correct customer. A `201` means the reply is stored. If `meta.email_sent` is `false` the reply was stored but not sent (see `meta.email_error`): do not retry, or the message is duplicated. A `422` `reply_failed` means nothing was stored. On `server_error` the result is unknown: do not retry; check `GET /v1/tickets/ /messages` first. This endpoint needs the `mcp.send` scope in addition to `tickets.write`; without it the request returns `403` and nothing is stored or sent. At most 5 replies per minute per key or user

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Path
Name Type Description
id Required string
Headers
Name Type Description
Idempotency-Key string Optional. Replay within 24h returns the same response.
Request body
body string Required
html string
plain_text_body boolean
Response
data object

Ticket message.

id string
direction string

API creates are always `out`.

Enum
in out
type string
Enum
reply note
Example: note
body string
created_at string
author object
name string
email string
meta object
via_staff_save boolean
email_sent boolean

`false` means stored but not sent; do not retry.

email_error string

Reason the e-mail was not sent. Only present when `email_sent` is `false`.

Examples

POST /v1/tickets/{id}/replies
curl -X POST "https://api.appficient.nl/v1/tickets/{id}/replies" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "string",
    "html": "string",
    "plain_text_body": false
}'

Curl, Node and response are shown to the right of this endpoint.

Retrieve a ticket message

GET /v1/tickets/{id}/messages/{message_id}

One message of a ticket with its type (`note` or `reply`), direction, author, body and creation time

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Path
Name Type Description
id Required string
message_id Required string
Request body

None

Response
data object

Ticket message.

id string
direction string

API creates are always `out`.

Enum
in out
type string
Enum
reply note
Example: note
body string
created_at string
author object
name string
email string
meta object

Examples

GET /v1/tickets/{id}/messages/{message_id}
curl -X GET "https://api.appficient.nl/v1/tickets/{id}/messages/{message_id}" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json"

Curl, Node and response are shown to the right of this endpoint.

List ticket channels

GET /v1/ticket-channels

Optional `active` (default `1`)

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Query
Name Type Description
active string 1 = active (default), 0 = inactive
Request body

None

Response
data array
id string

Channel id.

name string

Channel name.

email string

Mailbox address when configured.

from_email string

From-address when configured.

from_name string

From name on outbound mail.

inbound_email string

Inbound address for forwarded mail.

forwarding_emails array

Addresses that forward into this channel.

active boolean

Whether this channel is active.

order integer

Sort order.

meta object

Examples

GET /v1/ticket-channels
curl -X GET "https://api.appficient.nl/v1/ticket-channels" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json"

Curl, Node and response are shown to the right of this endpoint.

List ticket statuses

GET /v1/ticket-statuses

Optional `active` (default `1`)

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Query
Name Type Description
active string 1 = active (default), 0 = inactive
Request body

None

Response
data array
id string

Status id.

name string

Status name.

active boolean

Whether this status is active.

order integer

Sort order.

meta object

Examples

GET /v1/ticket-statuses
curl -X GET "https://api.appficient.nl/v1/ticket-statuses" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json"

Curl, Node and response are shown to the right of this endpoint.

List ticket teams

GET /v1/ticket-teams

Active ticket teams with their members. Members are users who can be assigned to tickets of that team. With user credentials only teams the user may use are listed

Authorization: HTTP
name: httpBearer
type: http
scheme: bearer
Request body

None

Response
data array
name string
members array
id string
name string
meta object

Examples

GET /v1/ticket-teams
curl -X GET "https://api.appficient.nl/v1/ticket-teams" \
  -H "Authorization: Bearer apf_xxxxxxxx" \
  -H "Accept: application/json"

Curl, Node and response are shown to the right of this endpoint.