Tickets

Tickets or interventions are the main object of the application. They are created by the user and are linked to a location, an equipment and a job. They can be assigned to a user and can be scheduled for a specific date.

Properties

Name
id
Type
string
Description
Unique identifier for the ticket.
Name
from_public_interface
Type
boolean
Description
Whether the ticket was created from the public interface.
Name
intervention_scheduled_at
Type
array => ISODate
Description
Array of dates when the intervention is scheduled.
Name
intervention_occured_at
Type
array => ISODate
Description
Array of dates when the intervention occured.
Name
created_at
Type
string => ISODate
Description
Date when the ticket was created.
Name
closed_at
Type
string => ISODate
Description
Date when the ticket was closed.
Name
updated_at
Type
string => ISODate
Description
Date when the ticket was updated.
Name
assigned_at
Type
string => ISODate
Description
Date when the ticket was assigned.
Name
url
Type
string
Description
URL of the ticket.
Name
number
Type
string
Description
Number of the ticket.
Name
status
Type
string enum
Description
Status of the ticket.
- draft (ticket is draft)
- opened (ticket is open)
- waiting (ticket is waiting for assignment)
- proposed (ticket was proposed to a contractor)
- toreplan (ticket is waiting to be rescheduled)
- toplan (ticket is to plan)
- waitingplan (ticket is waiting to be scheduled)
- waiting_contractor (ticket is waiting to plan or assign)
- assigned (ticket is assigned to a contractor)
- visit(ticket has a visit date planned)
- visit_devis (waiting for the visit date to be confirmed as executed)
- validation (the quote(s) need to be validated)
- validated(the ticket's quote(s) were validated )
- dropped (one or all of the ticket's quotes were declined)
- intervention (ticket has an intervention date planned)
- intervention_finish(waiting for the intervention date to be confirmed as executed)
- finished(ticked is finished)
- closed (ticket is closed)
- canceled (ticket is canceled)
- declined(ticket is declined)
- removed (ticket is dropped)
Name
title
Type
string
Description
Title of the ticket.
Name
description
Type
string
Description
Description of the ticket.
Name
priority_label
Type
string
Description
Priority of the ticket.
Name
client
Type
Object
Description
Client of the ticket.
- _id (id of the client)
- name (name of the client)
Name
contractors
Type
array of Object
Description
Array of contractors.
- _id (id of the contractor)
- name (name of the contractor)
- type (type of the contractor)
Name
locations
Type
array of Object
Description
Array of locations with _id, name, parent_id, reference and location_facturation.
Name
equipments
Type
array
Description
Array of equipments with _id, name and parent_id.
Name
jobs
Type
array
Description
Array of jobs with _id and name.
Name
domains
Type
array
Description
Array of domains with _id, name and parent_id.
Name
managers
Type
array
Description
Array of managers.
Name
contacts
Type
array
Description
Array of contacts (users)
Name
maintenance
Type
string
Description
Name of maintenance (only if the ticket is type of maintenance).
Name
quotes
Type
string
Description
Quotes of the ticket.
Name
invoices
Type
string
Description
Invoices of the ticket.
Name
fields
Type
array
Description
The custom fields of tickets.
Name
typology
Type
array
Description
Typology of the ticket
- _id (id of the typology, curatif, maintenance, etc...)
- name (name of the typology)

GET/api/v3.0/tickets/get-id-from-number

Get ticket id from number

This endpoint allows you to retrieve a ticket id when you send an ticket number.

parameters

Name
ticket_number
Type
string
Description
Only return tickets created after this date.

Request

GET

/api/v3.0/tickets/get-id-from-number

curl -G https://api.bob-desk.com/api/v3.0/tickets/get-id-from-number \
  -H "Authorization: Bearer {token}" \
  -d ticket_number="1234"

Response

{
    "ticket_id": "63725f259ab7e72a4fb4ae69"
}

GET/api/v3.0/tickets

Tickets List

This endpoint allows you to retrieve a list of tickets.

optional parameters

Name
created_after
Type
string
Description
Only return tickets created after or at this date.
Name
created_before
Type
string
Description
Only return data created before this date.
Name
updated_after
Type
string
Description
Only return tickets updated after this date.
Name
assigned_after
Type
string
Description
Only return tickets assigned after this date.
Name
cursor
Type
string
Description
Cursor to paginate the results.
Name
client_id
Type
string
Description
Id of the client (only for contractors).
Name
interventions
Type
string
Description
Only accepts values true or false.
If true return only tickets typeof interventions
Name
maintenances
Type
string
Description
Only accepts values true or false.
If true return only tickets typeof maintenances
Name
typology
Type
string
Description
Accepts the id of the typology you want to filter.
Below are the typologies and the corresponding ids shared by all accounts.
Typology ID
Curatif 5ebb096fe1bde10a7ee21348
Maintenance 5ebb096fe1bde10a7ee21349
Levée de réserves 5f770cb039e6b8004a1cc0b7
Sinistre 5ebb096fe1bde10a7ee2134b
Travaux 5ebb096fe1bde10a7ee2134a

Typology	ID
Curatif	5ebb096fe1bde10a7ee21348
Maintenance	5ebb096fe1bde10a7ee21349
Levée de réserves	5f770cb039e6b8004a1cc0b7
Sinistre	5ebb096fe1bde10a7ee2134b
Travaux	5ebb096fe1bde10a7ee2134a

Request

GET

/api/v3.0/tickets

curl -G https://api.bob-desk.com/api/v3.0/tickets \
  -H "Authorization: Bearer {token}" \
  -d updated_after="1669805251942" \
  -d created_after="1667828888" \
  -d created_before="1670153026" \
  -d assigned_after="1670153026" \
  -d cursor="63725f259ab7e72a4fb4ae69" \
  {/* Only for contractors */}
  -d client_id="5d9b5b5b9ab7e72a4fb4ae69"

Response

{
    "cursor": "63725f259ab7e72a4fb4ae69",
    "tickets": [
        {
            "_id": "63725f259ab7e72a4fb4ae69",
            "from_public_interface": true,
            "intervention_scheduled_at": ["2019-12-01T00:00:00.000Z"],
            "intervention_occured_at": ["2019-12-01T00:00:00.000Z"],
            "created_at": "2019-12-01T00:00:00.000Z", // string => ISODate
            "closed_at": "2019-12-01T00:00:00.000Z",
            "updated_at": "2019-12-01T00:00:00.000Z",
            "assigned_at": "2019-12-01T00:00:00.000Z",
            "url": "https://bob-desk.com/tickets/63725f259ab7e72a4fb4ae69",
            "number": "123456789", // no guarantee that it is unique
            "status": "closed", // enum
            "title": "Mon titre",
            "description": "Ma description",
            "priority_label": "high", // enum,
            "typology": {
              "_id": "5ebb096fe1bde10a7ee21348",
              "name": "Curatif"
            },  
            "quotes": [
                {
                    "reference": "123456789",
                    "_id": "63725f259ab7e72a4fb4ae69",
                    "validated": true,
                    "price": "1000"
                }
            ],
            "invoices": [
                {
                    "reference": "123456789",
                    "_id": "63725f259ab7e72a4fb4ae69",
                    "price": "1000"
                }
            ],
            "client":{
                "_id": "5d9b5b5b9ab7e72a4fb4ae69",
                "name": "Bob! Desk",
            },
            "locations": [
                {
                    "_id": "5d9b5b5b9ab7e72a4fb4ae69",
                    "name": "Paris",
                    "parent_id": null,
                    "reference": "OZ76YH",
                    "address": {
                          "postalCode": "75008",
                          "country": "France",
                          "city": "Paris",
                          "route": "Avenue des Champs-Élysées",
                          "streetNumber": "110",
                          "fullAddress": "110 Av. des Champs-Élysées, 75008 Paris, France",
                          "zone": "75",
                          "lat": 48.8722455,
                          "lng": 2.2996826
                    },
                    "location_facturation": {
                      "id": "5d7e3cb4101e1d004be4c378",
                      "name": "zShop 3",
                      "reference": "",
                      "address": {
                          "postalCode": "75008",
                          "country": "France",
                          "city": "Paris",
                          "route": "Avenue des Champs-Élysées",
                          "streetNumber": "110",
                          "fullAddress": "110 Av. des Champs-Élysées, 75008 Paris, France",
                          "zone": "75",
                          "lat": 48.8722455,
                          "lng": 2.2996826
                      },
                    },
                }
            ],
            "equipments": [
                {
                    "_id": "5d9b5b5b9ab7e72a4fb4ae69",
                    "name": "Machine à café",
                    "parent_id": null,
                }
            ],
            "jobs": [
                {
                    "_id": "5d9b5b5b9ab7e72a4fb4ae69",
                    "name": "Réparation",
                }
            ],
            "managers": [
              {
                "_id": "5d9b5b5b9ab7e72a4fb4ae69",
                "firstName": "first",
                "lastName": "last",
                "email": "managers@managers.fr",
                "phone": "+33601020304"
              },
            ],
            "contacts": [
              {
                "_id": "5d9b5b5b9ab7e72a4fb4ae69",
                "lastName": "last",
                "firstName": "first",
                "email": "contacts@contacts.fr",
                "phone": "+33601020304"
              }
            ],
            "domain": [
                {
                    "_id": "5d9b5b5b9ab7e72a4fb4ae69",
                    "name": "Réparation",
                    "parent_id": null,
                }
            ],
            "fields": [
                {
                    "field_id": "5d9b5b5b9ab7e72a4fb4ae69",
                    "name": {
                        "fr": "Nom du champ 1",
                        "en": "field name 1",
                    },
                    "value": "value"
                },
            ]
        }
    ]
}

POST/api/v3.0/tickets

Create ticket

This endpoint allows you to create a ticket.

Required parameters

Name
title
Type
string
Description
Title of the ticket.

If you are a contractor, you can also provide this parameter

Name
client_id
Type
string
Description
Id of the client.

Optional parameters

Name
description
Type
string
Description
Description of the ticket.
Name
priority
Type
enum
Description
Priority of the ticket. ('none', 'low', 'medium', 'high')
Name
location_ids
Type
array
Description
Array of location ids.
Name
equipment_ids
Type
array
Description
Array of equipment ids.
Name
job_ids
Type
array
Description
Array of job ids.
Name
manager_ids
Type
array
Description
Array of manager ids.
Name
price_threshold
Type
number
Description
Price threshold of the ticket.

Request

POST

/api/v3.0/tickets

curl -X https://api.bob-desk.com/api/v3.0/tickets \
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \
  -d '{
    "title": "Light broken",
    "description": "I need a intervention to change my light",
    "priority": "high",
    "location_ids": ["5d9b5b5b9ab7e72a4fb4ae69"],
    "equipment_ids": ["5d9b5b5b9ab7e72a4fb4fe69"],
    "job_ids": ["5d9b5b5b9ab7e72a4fb4ae67"],
    "manager_ids": ["5d9b5b5b9ab7e72a4ff4ae69"],
    "price_threshold": 42
  }'

Response

{
   "ticket_id": "5f9b5b5b9ab7e72a4fb4ae69"
}

PUT/api/v3.0/tickets/:ticket_id/cancel

Cancel ticket

This endpoint allows you to cancel a ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Optional parameters

Name
reason_cancel
Type
string
Description
Reason of cancel

Request

PUT

/api/v3.0/tickets/:ticket_id/cancel

curl -X PUT https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/cancel
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \
  -d '{
    "reason_cancel": "The client no longer needs us to do the intervention"
  }'

PUT/api/v3.0/tickets/:ticket_id/finish

Finish ticket

This endpoint allows you to finish a ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Optional parameters

Name
reserve
Type
boolean
Description
Only when the ticket to finish is a reserve ticket otherwise it's not necessary.

Request

PUT

/api/v3.0/tickets/:ticket_id/finish

curl -X PUT https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/finish
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \
  -d '{
    "reserve": false
  }'

PUT/api/v3.0/tickets/:ticket_id/close

Close a ticket

This endpoint allows you to close a ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Optional parameters

Name
reserve
Type
boolean
Description
Only when the ticket to close is a reserve ticket, otherwise it is not needed.

Request

PUT

/api/v3.0/tickets/:ticket_id/close

curl -X PUT https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/close
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \
  -d '{
    "reserve": false
    }'

POST/api/v3.0/tickets/:ticket_id/open

ReOpen ticket

This endpoint allows you to reopen a ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Request

POST

/api/v3.0/tickets/:ticket_id/open

curl -X POST https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/open
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}"

GET/api/v3.0/tickets/:ticket_id/notes

Notes ticket

This endpoint allows you to get all notes of a ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Request

GET

/api/v3.0/tickets/:ticket_id/notes

curl -G https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/notes
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \

Response

{
   "notes": []
}

Properties of the response

Name
notes
Type
array
Description
An array of notes.

POST/api/v3.0/tickets/:ticket_id/notes

Create a note

This endpoint allows you to post a note on a specific ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Required parameters

Name
note
Type
string
Description
The content of note.
Name
type
Type
string
Description
Type of the note.
(only values allowed: internal, managers, public)

Request

POST

/api/v3.0/tickets/:ticket_id/notes

curl -X https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/notes
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \
  -d '{
    "note": "Tell me when you are coming",
    "type": "internal"
  }'

GET/api/v3.0/tickets/:ticket_id/dates

Dates list

This endpoint allows you to get all dates of a ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Request

GET

/api/v3.0/tickets/:ticket_id/dates

curl -G https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/notes
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \

Response

{
   "visit_dates": [],
   "intervention_dates": [],
}

Properties of the response

Name
visit_dates
Type
array
Description
An array of visit dates.
Name
intervention_dates
Type
array
Description
An array of intervention dates.

POST/api/v3.0/tickets/:ticket_id/dates

Append a date

This endpoint allows you to post a date by type on a specific ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Required parameters

Name
start
Type
ISODate || Timestamps
Description
The start of visit date.
Name
end
Type
ISODate || Timestamps
Description
Tne end of visit date.
Name
type
Type
string
Description
The type of date
( Only values allowed: planned, actual )

Request

POST

/api/v3.0/tickets/:ticket_id/dates

curl -X https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/dates
  -H "Content-Type: application/json"
  -H "Authorization: Bearer {token}" \
  -d '{
    "start": "2023-03-17T10:00:00.915Z",
    "end": "2023-03-17T14:00:00.915Z",
    "type": "planned"
  }'