API reference

Read and change your workspace data from your own tools: companies, contacts, conversations, tasks, projects, invoices and more. The API speaks JSON over HTTPS, and every request carries a personal API token.

Machine-readable description (OpenAPI 3.1): OpenAPI JSON

The same description is served at https://<your address>/api/v1/openapi.json.

Base URL

Send requests to your organization's address, for example https://your-team.unifydesk.app/api/v1. Each token belongs to one workspace, and every request reads and writes that workspace only.

Authentication

Send the token in the Authorization header: Authorization: Bearer udk_... A missing, expired or revoked token returns 401.

Create a token

In UnifyDesk, open Settings > Access & API. Organization owners and admins, and the workspace managers, create tokens there. Creating or revoking a token needs a two-step verification within the last two hours.

Choose the modules and what the token may do in each (view, create, edit, delete). A token never gets more than its creator can do. Contract billing rates need the billing rates permission as well.

A token expires after 90 days by default, and after 365 days at most. The token is shown once: store it in a secret manager. Revoke it from the same page as soon as it is no longer needed.

Rate limits

Each token may make 60 requests per minute unless set otherwise, and each network 600. Above that the API answers 429 with Retry-After: 60.

Pagination and sorting

Lists return { data, limit, offset, nextCursor }. Use limit (1 to 100, default 50) and offset (up to 1000). Beyond that, pass the nextCursor of the previous page as cursor until it is null. Sort with order=<field>.asc or order=<field>.desc, and filter with the fields listed for each resource.

Changes and deletes

POST and PATCH take a JSON object with only the fields you set; unknown fields return 400. Add an Idempotency-Key header (up to 255 characters) to a POST so a retry returns the first result instead of creating twice.

Records that go to the trash need If-Match: "<updated_at>" from your last GET on DELETE. A record changed since then returns 412.

Errors

Errors return a JSON body { "error": "..." } with the HTTP status: 400 invalid request, 401 bad token, 403 not allowed (or a read-only subscription), 404 not found, 409 conflict, 412 stale version, 428 missing If-Match or Idempotency-Key, 429 too many requests.

Refunds

Recording an offline refund needs a signed-in person with current two-step sign-in, so it is not available through the API. Refunds stay readable, and their reason can be edited.

Resources

Each resource accepts the methods shown. The Writable column lists the methods that accept each field. Replace the example address and identifiers in angle brackets with your own.

activity

GET /activity
GET /activity/{id}

Filters: event_type, actor_id, entity_type, entity_id

Field	Type	Writable
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}

Filters: asset_type_id, assigned_user_id, company_id, status

Field	Type	Writable
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}

Filters: industry

Field	Type	Writable
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}

Filters: company_id

Field	Type	Writable
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}

Filters: status, company_id, contact_id

Field	Type	Writable
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}

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

Field	Type	Writable
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}

Filters: status, invoice_id

Field	Type	Writable
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}

Filters: folder, company_id, contact_id, project_id

Field	Type	Writable
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}

Filters: status, category, company_id, project_id

Field	Type	Writable
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}

Filters: status, company_id, contact_id, contract_id

Field	Type	Writable
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}

Filters: stage_id, company_id, contact_id, owner_id

Field	Type	Writable
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}

Filters: stage_id, company_id, contact_id, owner_id

Field	Type	Writable
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}

Filters: status, company_id, owner_id, contact_id, health_status

Field	Type	Writable
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}

Filters: status, vendor_id, project_id

Field	Type	Writable
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}

Filters: status, company_id, contact_id, opportunity_id

Field	Type	Writable
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}

Recording a refund needs a signed-in person with current two-step sign-in, so tokens cannot record refunds (CO51). Refunds stay readable and their reason editable.

Filters: invoice_id, credit_note_id

Field	Type	Writable
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}

Field	Type	Writable
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}

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

Field	Type	Writable
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}

Filters: entity_type, entity_id, user_id, billable

Field	Type	Writable
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"

Questions? Contact us.