REST API Companies

🏢 REST API: Companies

The usage guide for companies in the REST API - listing them, and creating and keeping them in step from an ERP or CRM. Mirrors the interactive documentation at System → API → Documentation. User guide: Multi-company · Developer guide: Companies.

Note

New to the API? The basics table on REST API: Tickets covers base URL, authentication, the response envelope, error codes, rate limits and PATCH semantics - identical across all modules.

What's distinctive about companies (5.3.0, #279):

🔑 An outside reference	external_ref is the company's ID in your ERP or CRM - unique when set, matched ignoring case. tax_id (VAT, AFM ...) is unique too.
🔄 Upsert by reference	POST /companies/upsert creates the company the first time and updates it after - send the whole customer list every night and nothing is duplicated.
🛡️ Writes are an administrator's	Creating, updating and upserting need a key that acts as a System administrator and is scoped to all companies - as System → Companies is administrators only. Reads follow the key's company scope as everywhere.

🚀 Quick start

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"

# Find a company by its ERP reference (inactive ones too)
curl -s -H "$K" "$B/companies?external_ref=CUST-1042" | jq '.data[0]'

# Nightly: create or update each customer by its reference
curl -s -H "$K" -H "Content-Type: application/json" -X POST "$B/companies/upsert" -d '{
  "external_ref": "CUST-1042",
  "name": "Papadopoulos Bakery",
  "tax_id": "EL094019245",
  "is_active": true
}'
# 201 + "created": true the first time, 200 + "created": false after

# Change one field - only what is sent changes
curl -s -H "$K" -H "Content-Type: application/json" -X PATCH "$B/companies/12" -d '{"tax_id": "EL094019246"}'

📚 Endpoints

Method	Path	Permission	What it does
GET	/companies	companies.read	The companies the key can see: id, name, is_default, is_active, ticket_code, external_ref, tax_id. Filters q (name, reference or tax ID contains), external_ref and tax_id (exact, ignoring case), active (true - the default - false or all). An exact external_ref / tax_id lookup finds inactive companies too.
GET	/companies/{id}	companies.read	One company; outside the key's scope is the same 404 as unknown.
POST	/companies	companies.create	Create. name required; is_active, ticket_code, external_ref, tax_id optional. 201.
PATCH	/companies/{id}	companies.update	Change only the fields sent; "" clears ticket_code, external_ref or tax_id.
POST	/companies/upsert	companies.create + update	Create or update by external_ref (required). Returns the company and created.

Errors: 409 duplicate when a ticket code, outside reference or tax ID is already another company's (the message names it); 422 when the name is missing, a value is too long, or the Default company would be made inactive; 403 when the key is not an all-companies administrator's.

👤 People: employee ID

GET /users, GET /users/{id}, POST /users and PATCH /users/{id} carry employee_id (up to 64 characters, not unique), and GET /users?employee_id= finds a person by it - so an HR or ERP system can match its people to FreeITSM's.

📨 How mail reaches a synced company

A person created with tenant_id set (POST /users) is that company's: mail from their address files with it even on a Gmail address, once nothing more specific (a company's specific senders, a mapped domain) claims it. See Multi-company: email routing.