Référence de l’API

Lisez et modifiez les données de votre espace de travail depuis vos propres outils : entreprises, contacts, conversations, tâches, projets, factures et plus. L’API échange du JSON en HTTPS, et chaque requête porte un jeton d’API personnel.

Description lisible par machine (OpenAPI 3.1) : OpenAPI JSON

La même description est servie à https://<votre adresse>/api/v1/openapi.json.

Adresse de base

Envoyez les requêtes à l’adresse de votre organisation, par exemple https://your-team.unifydesk.app/api/v1. Chaque jeton appartient à un espace de travail, et chaque requête lit et modifie cet espace seulement.

Authentification

Envoyez le jeton dans l’en-tête Authorization : Authorization: Bearer udk_... Un jeton absent, expiré ou révoqué renvoie 401.

Créer un jeton

Dans UnifyDesk, ouvrez Paramètres > Accès et API. Les propriétaires et administrateurs de l’organisation, ainsi que les gestionnaires de l’espace de travail, y créent les jetons. Créer ou révoquer un jeton demande une vérification en deux étapes de moins de deux heures.

Choisissez les modules et ce que le jeton peut y faire (consulter, créer, modifier, supprimer). Un jeton n’obtient jamais plus que ce que son créateur peut faire. Les taux de facturation des contrats demandent aussi la permission des taux de facturation.

Un jeton expire après 90 jours par défaut, et après 365 jours au plus. Il n’est affiché qu’une fois : conservez-le dans un gestionnaire de secrets. Révoquez-le depuis la même page dès qu’il ne sert plus.

Limites de débit

Chaque jeton peut faire 60 requêtes par minute sauf réglage contraire, et chaque réseau 600. Au-delà, l’API répond 429 avec Retry-After: 60.

Pagination et tri

Les listes renvoient { data, limit, offset, nextCursor }. Utilisez limit (1 à 100, 50 par défaut) et offset (jusqu’à 1000). Au-delà, passez le nextCursor de la page précédente comme cursor jusqu’à ce qu’il soit null. Triez avec order=<champ>.asc ou order=<champ>.desc, et filtrez avec les champs indiqués pour chaque ressource.

Modifications et suppressions

POST et PATCH reçoivent un objet JSON avec seulement les champs que vous fixez ; un champ inconnu renvoie 400. Ajoutez l’en-tête Idempotency-Key (255 caractères au plus) à un POST pour qu’une nouvelle tentative renvoie le premier résultat au lieu de créer deux fois.

Pour les enregistrements qui vont à la corbeille, DELETE demande If-Match: "<updated_at>" tiré de votre dernier GET. Un enregistrement modifié depuis renvoie 412.

Erreurs

Les erreurs renvoient un corps JSON { "error": "..." } avec le statut HTTP : 400 requête invalide, 401 jeton refusé, 403 non autorisé (ou abonnement en lecture seule), 404 introuvable, 409 conflit, 412 version périmée, 428 If-Match ou Idempotency-Key manquant, 429 trop de requêtes.

Remboursements

Enregistrer un remboursement hors ligne demande une personne connectée avec une connexion en deux étapes récente : ce n’est donc pas possible par l’API. Les remboursements restent consultables, et leur motif modifiable.

Ressources

Chaque ressource accepte les méthodes indiquées. La colonne Modifiable indique les méthodes qui acceptent chaque champ. Remplacez l’adresse d’exemple et les identifiants entre chevrons par les vôtres.

activity

GET /activity
GET /activity/{id}

Filtres : event_type, actor_id, entity_type, entity_id

Champ	Type	Modifiable
id	string (uuid)
event_type	string
actor_id	string (uuid)
entity_type	string
entity_id	string (uuid)
created_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/activity?limit=20"

assets

GET /assets
POST /assets
GET /assets/{id}
PATCH /assets/{id}
DELETE /assets/{id}

Filtres : asset_type_id, assigned_user_id, company_id, status

Champ	Type	Modifiable
id	string (uuid)
name	string	POST, PATCH
asset_type_id	string (uuid)	POST, PATCH
serial_number	string	POST, PATCH
manufacturer	string	POST, PATCH
model	string	POST, PATCH
status	string	POST, PATCH
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
assigned_user_id	string (uuid)	POST, PATCH
location	string	POST, PATCH
purchased_at	string (date)	POST, PATCH
warranty_until	string (date)	POST, PATCH
notes	string	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/assets?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example"}' "https://your-team.unifydesk.app/api/v1/assets"

companies

GET /companies
POST /companies
GET /companies/{id}
PATCH /companies/{id}
DELETE /companies/{id}

Filtres : industry

Champ	Type	Modifiable
id	string (uuid)
name	string	POST, PATCH
domain	string	POST, PATCH
phone	string	POST, PATCH
address	string	POST, PATCH
industry	string	POST, PATCH
notes	string	POST, PATCH
is_vendor	boolean
employee_count	number
last_interaction_at	string (date-time)
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/companies?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example"}' "https://your-team.unifydesk.app/api/v1/companies"

contacts

GET /contacts
POST /contacts
GET /contacts/{id}
PATCH /contacts/{id}
DELETE /contacts/{id}

Filtres : company_id

Champ	Type	Modifiable
id	string (uuid)
company_id	string (uuid)	POST, PATCH
first_name	string	POST, PATCH
last_name	string	POST, PATCH
email	string	POST, PATCH
phone	string	POST, PATCH
title	string	POST, PATCH
notes	string	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/contacts?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Example","last_name":"Example"}' "https://your-team.unifydesk.app/api/v1/contacts"

contracts

GET /contracts
POST /contracts
GET /contracts/{id}
PATCH /contracts/{id}
DELETE /contracts/{id}

Filtres : status, company_id, contact_id

Champ	Type	Modifiable
id	string (uuid)
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
contract_number	string
title	string	POST, PATCH
status	string
amount	number	POST, PATCH
currency	string	POST, PATCH
billing_cycle	string	POST, PATCH
start_date	string (date)	POST, PATCH
end_date	string (date)	POST, PATCH
start_at	string (date-time)	POST, PATCH
end_at	string (date-time)	POST, PATCH
is_all_day	boolean	POST, PATCH
renewal_date	string (date)	POST, PATCH
description	string	POST, PATCH
rate_per_word	number	POST, PATCH
is_default	boolean
source_quote_id	string (uuid)
signed_by_name	string
signed_at	string (date-time)
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/contracts?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Example","currency":"USD"}' "https://your-team.unifydesk.app/api/v1/contracts"

conversations

GET /conversations
POST /conversations
GET /conversations/{id}
PATCH /conversations/{id}
DELETE /conversations/{id}

Filtres : status, priority, assignee_id, company_id, contact_id, project_id, contract_id

Champ	Type	Modifiable
id	string (uuid)
mailbox_id	string (uuid)	POST, PATCH
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
project_id	string (uuid)	POST, PATCH
contract_id	string (uuid)	POST, PATCH
category_id	string (uuid)	POST, PATCH
subject	string	POST, PATCH
status	string	POST, PATCH
priority	string	POST, PATCH
assignee_id	string (uuid)	POST, PATCH
team_id	string (uuid)	POST, PATCH
ticket_number	string
channel	string	POST, PATCH
first_response_at	string (date-time)
closed_at	string (date-time)
created_at	string (date-time)
updated_at	string (date-time)
resolution_category_id	string (uuid)	POST, PATCH
resolution_note	string	POST, PATCH

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/conversations?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Example"}' "https://your-team.unifydesk.app/api/v1/conversations"

credit_notes

GET /credit_notes
POST /credit_notes
GET /credit_notes/{id}
PATCH /credit_notes/{id}
DELETE /credit_notes/{id}

Filtres : status, invoice_id

Champ	Type	Modifiable
id	string (uuid)
credit_number	string
invoice_id	string (uuid)	POST, PATCH
company_id	string (uuid)
contact_id	string (uuid)
amount	number	POST, PATCH
currency	string	POST, PATCH
status	string
reason	string	POST, PATCH
issue_date	string (date)
applied_at	string (date-time)
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/credit_notes?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"<invoice id>"}' "https://your-team.unifydesk.app/api/v1/credit_notes"

documents

GET /documents
GET /documents/{id}
PATCH /documents/{id}
DELETE /documents/{id}

Filtres : folder, company_id, contact_id, project_id

Champ	Type	Modifiable
id	string (uuid)
company_id	string (uuid)	PATCH
contact_id	string (uuid)	PATCH
conversation_id	string (uuid)	PATCH
project_id	string (uuid)	PATCH
contract_id	string (uuid)	PATCH
invoice_id	string (uuid)	PATCH
task_id	string (uuid)	PATCH
name	string	PATCH
description	string	PATCH
file_type	string
mime_type	string
size_bytes	number
folder	string	PATCH
version	number
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/documents?limit=20"

expenses

GET /expenses
POST /expenses
GET /expenses/{id}
PATCH /expenses/{id}
DELETE /expenses/{id}

Filtres : status, category, company_id, project_id

Champ	Type	Modifiable
id	string (uuid)
submitted_by	string
approved_by	string
company_id	string (uuid)	POST, PATCH
project_id	string (uuid)	POST, PATCH
contract_id	string (uuid)	POST, PATCH
conversation_id	string (uuid)	POST, PATCH
invoice_id	string (uuid)
category	string	POST, PATCH
description	string	POST, PATCH
amount	number	POST, PATCH
currency	string	POST, PATCH
expense_date	string (date)	POST, PATCH
status	string
rejection_reason	string
approved_at	string (date-time)
reimbursed_at	string (date-time)
billable	boolean	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/expenses?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"Example","amount":1}' "https://your-team.unifydesk.app/api/v1/expenses"

invoices

GET /invoices
POST /invoices
GET /invoices/{id}
PATCH /invoices/{id}
DELETE /invoices/{id}

Filtres : status, company_id, contact_id, contract_id

Champ	Type	Modifiable
id	string (uuid)
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
contract_id	string (uuid)	POST, PATCH
project_id	string (uuid)	POST, PATCH
conversation_id	string (uuid)	POST, PATCH
invoice_number	string
amount	number	POST, PATCH
currency	string	POST, PATCH
status	string
issue_date	string (date)	POST, PATCH
due_date	string (date)	POST, PATCH
paid_date	string (date)
sent_at	string (date-time)
delivered_at	string (date-time)
delivery_method	string
payment_terms	string
memo	string
customer_po_number	string	POST, PATCH
is_recurring	boolean
recurring_frequency	string
recurring_next_at	string (date)
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/invoices?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currency":"USD"}' "https://your-team.unifydesk.app/api/v1/invoices"

opportunities

GET /opportunities
POST /opportunities
GET /opportunities/{id}
PATCH /opportunities/{id}
DELETE /opportunities/{id}

Filtres : stage_id, company_id, contact_id, owner_id

Champ	Type	Modifiable
id	string (uuid)
stage_id	string (uuid)	POST, PATCH
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
owner_id	string (uuid)	POST, PATCH
name	string	POST, PATCH
description	string	POST, PATCH
amount	number	POST, PATCH
currency	string	POST, PATCH
expected_close_date	string (date)	POST, PATCH
closed_at	string (date-time)
probability_snapshot	number
source	string	POST, PATCH
lost_reason_id	string (uuid)	POST, PATCH
lost_reason_note	string	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/opportunities?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example"}' "https://your-team.unifydesk.app/api/v1/opportunities"

pipeline

GET /pipeline
POST /pipeline
GET /pipeline/{id}
PATCH /pipeline/{id}
DELETE /pipeline/{id}

Filtres : stage_id, company_id, contact_id, owner_id

Champ	Type	Modifiable
id	string (uuid)
stage_id	string (uuid)	POST, PATCH
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
owner_id	string (uuid)	POST, PATCH
name	string	POST, PATCH
description	string	POST, PATCH
amount	number	POST, PATCH
currency	string	POST, PATCH
expected_close_date	string (date)	POST, PATCH
closed_at	string (date-time)
probability_snapshot	number
source	string	POST, PATCH
lost_reason_id	string (uuid)	POST, PATCH
lost_reason_note	string	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/pipeline?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example"}' "https://your-team.unifydesk.app/api/v1/pipeline"

projects

GET /projects
POST /projects
GET /projects/{id}
PATCH /projects/{id}
DELETE /projects/{id}

Filtres : status, company_id, owner_id, contact_id, health_status

Champ	Type	Modifiable
id	string (uuid)
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
project_type_id	string (uuid)
stage_id	string (uuid)
name	string	POST, PATCH
description	string	POST, PATCH
status	string	POST, PATCH
start_date	string (date)	POST, PATCH
end_date	string (date)	POST, PATCH
start_at	string (date-time)	POST, PATCH
end_at	string (date-time)	POST, PATCH
is_all_day	boolean	POST, PATCH
owner_id	string (uuid)	POST, PATCH
budget_amount	number	POST, PATCH
budget_currency	string	POST, PATCH
budget_type	string	POST, PATCH
budget_alert_threshold_pct	number	POST, PATCH
health_status	string	POST, PATCH
source_word_count	number	POST, PATCH
target_word_count	number	POST, PATCH
word_count_updated_at	string (date-time)
memsource_project_uid	string	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/projects?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example"}' "https://your-team.unifydesk.app/api/v1/projects"

purchase_orders

GET /purchase_orders
GET /purchase_orders/{id}
PATCH /purchase_orders/{id}
DELETE /purchase_orders/{id}

Filtres : status, vendor_id, project_id

Champ	Type	Modifiable
id	string (uuid)
po_number	string
vendor_id	string (uuid)	PATCH
contact_id	string (uuid)	PATCH
project_id	string (uuid)	PATCH
contract_id	string (uuid)	PATCH
status	string
total_amount	number
currency	string	PATCH
order_date	string (date)	PATCH
expected_date	string (date)	PATCH
received_date	string (date)
notes	string	PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/purchase_orders?limit=20"

quotes

GET /quotes
POST /quotes
GET /quotes/{id}
PATCH /quotes/{id}
DELETE /quotes/{id}

Filtres : status, company_id, contact_id, opportunity_id

Champ	Type	Modifiable
id	string (uuid)
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
opportunity_id	string (uuid)	POST, PATCH
quote_number	string
title	string	POST, PATCH
status	string
amount	number
currency	string	POST, PATCH
valid_until	string (date)	POST, PATCH
line_items	json	POST, PATCH
terms	string
notes	string	POST, PATCH
sent_at	string (date-time)
accepted_at	string (date-time)
accepted_by_name	string
declined_at	string (date-time)
invoice_id	string (uuid)
project_id	string (uuid)	POST, PATCH
contract_id	string (uuid)	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/quotes?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Example","currency":"USD"}' "https://your-team.unifydesk.app/api/v1/quotes"

refunds

GET /refunds
GET /refunds/{id}
PATCH /refunds/{id}
DELETE /refunds/{id}

La création n’est pas offerte par l’API (voir Remboursements).

Filtres : invoice_id, credit_note_id

Champ	Type	Modifiable
id	string (uuid)
invoice_id	string (uuid)
credit_note_id	string (uuid)
amount	number
currency	string
reason	string	PATCH
status	string
refunded_at	string (date-time)
refunded_by	string
created_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/refunds?limit=20"

reports

GET /reports
GET /reports/{id}

Champ	Type	Modifiable
id	string (uuid)
name	string
description	string
source	string
columns	json
filters	json
group_by	string
aggregate	string
aggregate_field	string
sort_by	string
sort_dir	string
created_by	string
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/reports?limit=20"

tasks

GET /tasks
POST /tasks
GET /tasks/{id}
PATCH /tasks/{id}
DELETE /tasks/{id}

Filtres : status, priority, assignee_id, company_id, contact_id, project_id, parent_task_id

Champ	Type	Modifiable
id	string (uuid)
conversation_id	string (uuid)	POST, PATCH
project_id	string (uuid)	POST, PATCH
company_id	string (uuid)	POST, PATCH
contact_id	string (uuid)	POST, PATCH
contract_id	string (uuid)	POST, PATCH
invoice_id	string (uuid)	POST, PATCH
parent_task_id	string (uuid)	POST, PATCH
title	string	POST, PATCH
description	string	POST, PATCH
status	string	POST, PATCH
priority	string	POST, PATCH
assignee_id	string (uuid)	POST, PATCH
due_date	string (date)	POST, PATCH
due_at	string (date-time)	POST, PATCH
is_all_day	boolean	POST, PATCH
recurrence_rule	string	POST, PATCH
estimated_hours	number	POST, PATCH
estimate_minutes	number	POST, PATCH
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/tasks?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Example"}' "https://your-team.unifydesk.app/api/v1/tasks"

time_entries

GET /time_entries
POST /time_entries
GET /time_entries/{id}
PATCH /time_entries/{id}
DELETE /time_entries/{id}

Filtres : entity_type, entity_id, user_id, billable

Champ	Type	Modifiable
id	string (uuid)
entity_id	string (uuid)	POST, PATCH
entity_type	string	POST, PATCH
user_id	string (uuid)
duration_minutes	integer	POST, PATCH
description	string	POST, PATCH
billable	boolean	POST, PATCH
started_at	string (date-time)	POST, PATCH
is_running	boolean
approval_status	string
submitted_at	string (date-time)
approved_at	string (date-time)
approved_by	string
rejection_reason	string
created_at	string (date-time)
updated_at	string (date-time)

curl -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  "https://your-team.unifydesk.app/api/v1/time_entries?limit=20"

curl -X POST -H "Authorization: Bearer $UNIFYDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_type":"conversation","entity_id":"<conversation id>","duration_minutes":1}' "https://your-team.unifydesk.app/api/v1/time_entries"

Une question ? Écrivez-nous.