Projects

Projects are the top-level organizational unit in Ditio. Every work order (task), time registration, and resource allocation belongs to a project — so most ERP integrations start here: create projects, then add work orders inside them.

Base URL: api/v4/integration/projects · Scope: ditioapiv3

# Test (default for all examples)
export DITIO_API_BASE="https://core-api.ditio.dev/core"
# Production: export DITIO_API_BASE="https://core-api.ditio.app/core"

Create a project

POST /api/v4/integration/projects

curl -X POST "$DITIO_API_BASE/api/v4/integration/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "YOUR_COMPANY_ID",
    "projectNumber": "P-2026-001",
    "name": "Prosjekt Fjellhall",
    "active": true,
    "startDate": "2026-03-01T00:00:00Z",
    "finishedDatePlanned": "2026-12-31T00:00:00Z",
    "projectCustomerName": "Eksempel Kommune",
    "projectAddress": "Fjellveien 1, Trondheim",
    "mainContactEmail": "prosjektleder@example.com"
  }'

Response: the created project with its generated id.

{
  "id": "65f1a2b3c4d5e6f7a8b9c0d1",
  "companyId": "YOUR_COMPANY_ID",
  "projectNumber": "P-2026-001",
  "name": "Prosjekt Fjellhall",
  "active": true
}

Note

Save the id from the response — you need it when creating work orders in this project.

Required fields

Field	Type	Description
companyId	string	Your Ditio company ID
projectNumber	string	Your internal project number (must be unique within the company)

Optional fields

Field	Type	Description
name	string	Project name
externalProjectNumber	string	Project number in your external system
externalDimension1	string	External dimension 1 (for accounting/ERP mapping)
externalDimension2	string	External dimension 2 (for accounting/ERP mapping)
description	string	Project description
active	bool	Whether the project is active (default: false)
requireTaskNumber	bool	Require a work order number for time registrations
blockedForRegistration	bool	Block all time registrations on this project
startDate	datetime	Project start date
finishedDatePlanned	datetime	Planned completion date
finishedDate	datetime	Actual completion date
estimatedHourQty	double	Estimated total hours
mainForemanId	string	Main foreman (user ID, phone number, name, or employee number)
projectLeaderId	string	Project leader (user ID, phone number, name, or employee number)
mainContactEmail	string	Contact email for the project
projectCustomerName	string	Customer name
customerNumber	string	External customer number. When provided, the project is linked to an existing company customer with this number, or a new customer is created (named with projectCustomerName) and linked. Omit to leave any existing customer link unchanged.
projectAddress	string	Project address
projectLocationLatitude	double	GPS latitude
projectLocationLongitude	double	GPS longitude
workBreakLunchStartTime	string	Lunch break start time (HH:mm)
workBreakLunchLength	int	Lunch break duration in minutes
workBreakDinnerStartTime	string	Dinner break start time (HH:mm)
workBreakDinnerLength	int	Dinner break duration in minutes

Get all projects

GET /api/v4/integration/projects

Returns a list of all projects in your company.

Get a project by ID

GET /api/v4/integration/projects/{id}

Get a project by project number

GET /api/v4/integration/projects/by-project-number/{projectNumber}

curl "$DITIO_API_BASE/api/v4/integration/projects/by-project-number/P-2026-001" \
  -H "Authorization: Bearer $TOKEN"

Useful when you know the project number from your external system but not the Ditio ID.

Update a project (full)

PUT /api/v4/integration/projects/{id}

Replaces all fields — send the complete project object.

curl -X PUT "$DITIO_API_BASE/api/v4/integration/projects/65f1a2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "YOUR_COMPANY_ID",
    "projectNumber": "P-2026-001",
    "name": "Prosjekt Fjellhall - fase 2",
    "active": true,
    "startDate": "2026-03-01T00:00:00Z",
    "finishedDatePlanned": "2027-06-30T00:00:00Z"
  }'

Update a project (partial)

PATCH /api/v4/integration/projects/{id}

Updates only the fields you include; all other fields remain unchanged.

curl -X PATCH "$DITIO_API_BASE/api/v4/integration/projects/65f1a2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Prosjekt Fjellhall - nytt navn", "active": false }'

Delete a project

DELETE /api/v4/integration/projects/{id}

Caution

A project can only be deleted if it has no associated time registrations, mass transport records, or terminal transactions — otherwise the API returns 400. When deletion succeeds, it permanently removes the project and its work orders, plans, and settings. This cannot be undone. Consider deactivating the project (active: false) instead.

Attaching documents

Projects can carry documents (drawings, contracts) that field workers see in the mobile app — see Documents.

Related

• Work Orders (Tasks) — the units of work inside a project
• Documents — push files to a project
• Project Data guide — bulk export of the full project catalogue
• Help centre: Prosjekt — project setup in Ditio Web (Norwegian)