Losys Customer API (1.0.0)

Download OpenAPI specification:

The Losys Customer API lets you read your company's construction project references (photos, location, description, services rendered) and generate PDF documents from them — directly from your own website or backend.

A runnable, public reference implementation is available in the losys-demo repository. When in doubt about a concrete request, that demo is the canonical example.

Base URL

All endpoints are relative to a single fixed base URL that already includes the /api/customer path prefix:

https://api.referenz-verwaltung.ch/api/customer/

So the project list, for example, is GET https://api.referenz-verwaltung.ch/api/customer/project. The same base URL is shown under Servers above and is used for the interactive examples.

Authentication

The Customer API uses OAuth 2.0 with the client_credentials grant. You receive a client_id and a client_secret from Losys. Each client is bound to exactly one company — that company is pinned into the issued token. As a result, none of the endpoints below take a company id in the path: every call automatically operates within your company's scope.

If you are new to OAuth 2.0, these are good starting points:

OAuth 2.0 — official overview
Client Credentials grant — the grant used here
RFC 6749 — The OAuth 2.0 Authorization Framework, in particular section 4.4 (Client Credentials Grant)

Obtain an access token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your-client-id>
&client_secret=<your-client-secret>

The response contains an access_token. Send it as a Bearer token with every request:

Authorization: Bearer <access_token>
Accept: application/json
Accept-Language: en

Reuse the access token — do not request one per call

The token response also contains an expires_in field (the token's lifetime in seconds). Request a token once and reuse the same access_token on every request until it expires — do not fetch a new token per request. Only when a request fails with 401 Unauthorized should you request a fresh token and retry.

The client_credentials grant does not return a refresh_token (per RFC 6749 §4.4.3). "Refreshing" simply means requesting a new token with your client_id and client_secret — this is intentional and cheap.

Localization

Almost all responses can be localized via the Accept-Language request header. Supported languages: de, fr, it, en.

Compression (Accept-Encoding)

The API can return gzip-compressed responses. Send

Accept-Encoding: gzip

and responses that are large enough to benefit (currently from ~4 KB of payload) are returned compressed, indicated by a Content-Encoding: gzip response header (smaller responses are sent uncompressed). Any standard HTTP client handles the decompression transparently. Using compression is recommended for the (potentially large) project list responses.

Pagination

List endpoints are paginated via limit and start (offset). When paging through a result set you must send exactly the same filter parameters on every request (only start and limit may change) — otherwise the results are inconsistent. To enforce this, every response returns an X-Paginator-Hash header; send it back on the next request and the API verifies your filter parameters did not change. This is strongly recommended.

The number of records per page is additionally capped by a per-account page-size limit (default 100). If you request a larger limit, the response is clamped to that cap and X-Paginator-Limit reports the effective size — keep paging with start to retrieve the rest. The total number of matching records (X-Paginator-Total) is never capped.

Pagination response headers

Every paginated response carries a set of X-Paginator-* headers describing the current page and the full result set:

Header	Meaning
`X-Paginator-Start`	Offset of the first returned record (echoes your `start`).
`X-Paginator-Limit`	Effective page size — the maximum number of records this page contains. Equals your `limit`, or the hardcoded page cap if your `limit` exceeds it.
`X-Paginator-Count`	Number of records actually returned in this response.
`X-Paginator-Total`	Total number of records matching your filter across all pages.
`X-Paginator-Has-Previous-Page`	`1` if a previous page exists, otherwise `0`.
`X-Paginator-Has-Next-Page`	`1` if a next page exists, otherwise `0`.
`X-Paginator-Hash`	Filter fingerprint — send it back as a request header on the next page (see above and below).

Caching & the `X-Paginator-Hash` header

Project lists are served through a cache. This has two practical consequences when paging:

The first page may take a moment longer when its cache is still cold — the result has to be computed (and, in the background, the following pages are pre-warmed).
Subsequent pages are then served much faster from the warm cache — but only if you send the X-Paginator-Hash header you received with the previous page back on the next request. The hash both guards filter consistency and lets the API hit the pre-warmed cache entry for the next page. Omitting it forfeits the speed-up.

So the recommended loop is: read X-Paginator-Hash from each response and send it back (unchanged) on the request for the next page, changing only start (and keeping all filter parameters identical).

Support

Every response carries an X-Request-Id header. Please include it when contacting support about a specific request.

Projects

Read project references.

These are the very same projects you can browse and edit interactively in the web GUI under https://referenz-verwaltung.ch/company/<your-company-id>/dashboard.

Two rules govern which projects the API returns:

Only "API-visible" projects are returned. A project is included only if the "Show this project on website" option ("Dieses Projekt in Webseite anzeigen") is enabled in the project editor of the web GUI. Projects with that option turned off are never returned.
Company groups return the whole group. If your company is a member of a company group, the Projects endpoints return the projects of all companies in that group, not only your own company's.

List projects

Returns a paginated list of your company's project references. Use the query parameters to filter, sort and page the result, and expand to include related entities.

Only "API-visible" projects are returned, and — for companies that belong to a company group — projects of all companies in the group (see the Projects section intro above).

Discovering valid filter values: the concrete values you may pass to the filter parameters (type-of-work / type-of-building / type-of-construction ids, category ids, cantons, languages, years, project-attribute ids …) can be retrieved from the Available filter values endpoint (GET /project/filter/multiple_choice_values). That endpoint only ever returns values that actually occur in projects you have access to, so it is the canonical source for populating a filter UI.

Authorizations:

customerOAuth

query Parameters

projectId

integer

Restrict to a single project id.

projectIds

Array of integers <= 4000 items

Restrict to these project ids.

companyId

integer

Restrict to a single company id (subject to access checks).

companyIds

Array of integers <= 400 items

Restrict to these company ids (subject to access checks).

groupId

integer

Restrict to projects of the member companies of a single group.

groupIds

Array of integers <= 100 items

Restrict to projects of the member companies of these groups.

yearFrom

integer

Earliest year of completion (inclusive).

yearTo

integer

Latest year of completion (inclusive).

language

string

Single language short name, e.g. de, fr, it, en.

A language can only be used to retrieve projects if your company has actually configured that language — projects only exist in the languages the company maintains. The languages available to you are listed under languages in the Available filter values response.

languages

Array of strings <= 10 items

Language short names, e.g. de, fr, it, en.

Only languages your company has configured can be requested (see the single language parameter and the languages list returned by Available filter values).

categoryId

integer

Restrict to a single category id.

categoryIds

Array of integers <= 400 items

canton

string

Single Swiss canton short name, e.g. zh, be.

cantons

Array of strings <= 75 items

Swiss canton short names, e.g. zh, be.

country

string

Single ISO 3166-1 alpha-2 country code, e.g. CH, DE.

countries

Array of strings <= 300 items

ISO 3166-1 alpha-2 country codes, e.g. CH, DE. Filters by the project's country and is independent of the Swiss cantons filter.

typeOfWorkId

integer

Restrict to a single "type of work" id.

typeOfWorkIds

Array of integers <= 400 items

Restrict to these "type of work" ids.

typeOfConstructionId

integer

Restrict to a single "type of construction" id.

typeOfConstructionIds

Array of integers <= 400 items

Restrict to these "type of construction" ids.

typeOfBuildingId

integer

Restrict to a single "type of building" id.

typeOfBuildingIds

Array of integers <= 400 items

Restrict to these "type of building" ids.

withImage

boolean

Only projects that have at least one image.

searchText

string <= 400 characters

Full-text search phrase. Multiple words are combined per concatenation.

searchTextIn

Array of strings <= 4 items

Items Enum: "project" "companies" "typeOfWork"

Where to search. Defaults to all of them when omitted.

Ignored when concatenation=fuzzy: the fuzzy (trigram) search has a fixed set of fields it matches against (project title, location, …) and does not honour searchTextIn.

concatenation

string

Default: "and"

Enum: "and" "or" "fuzzy"

How multiple search words are combined. and (default) and or are exact matches; fuzzy performs an approximate (trigram) match that also finds slight misspellings.

orderBy

Array of strings <= 25 items [ items^!?(yearOfCompletion|hasImage|id|zipcode|city... ]

Sort criteria, applied in order. Allowed values: yearOfCompletion, hasImage, id, zipcode, city, priority, canton, random, relevance. Prefix any value with ! to sort descending (e.g. !yearOfCompletion).

relevance is meant for fuzzy search: when concatenation=fuzzy, pass orderBy=relevance to sort the results by how well they match the search phrase (best matches first). In fact, for a fuzzy search with a searchText and no explicit orderBy, relevance is applied automatically. Outside of a fuzzy search relevance has no effect.

status

string

Enum: "1" "0" "true" "false" "on" "off" "active" "inactive" "null"

Filters projects by their visibility flag. By default the API already restricts results to API-visible projects (see the Projects section intro); status lets you query that flag explicitly.

Accepted values (a wide range of truthy/falsy spellings is supported):

Value	Meaning
`1`, `true`, `on`, `active`	only visible projects
`0`, `false`, `off`, `inactive`	only non-visible projects
`null` or omitted	do not filter on visibility

Examples: status=1 (visible only), status=0 (hidden only).

Array of objects (AttributeFilter)

Advanced filter on project attributes (the configurable project properties / custom fields a company defines). Each entry of the array selects one or more attributes — by numeric id or by name — and constrains the value the project must have for them. The available attribute ids and names are listed under attribute / attributeByName in the Available filter values response.

id vs. name — which to use. Available filter values returns the attributes twice: attribute is a flat, ordered list; attributeByName is the same attributes keyed by their name. An attribute's name is a language-independent key, whereas its displayed title is localized — so filtering by name is the robust choice for multilingual clients. It is also the right choice within a company group: each company defines its attributes separately (distinct ids), and attributeByName bundles all of them under one name (in its ids array), so a single name-based filter matches the attribute across the whole group at once.

Attribute types. Each attribute has a type: number, text, textarea, bool, dropdown or employees. The type determines which value constraint makes sense (a range for number, contains for text, option keys for dropdown, …). The two types that carry selectable options return them alongside the attribute:

dropdown — its selectable option values ({ value, id, key }); filter by the option key(s).
employees — its selectable people ({ id, firstName, lastName }). "Filtering by employee" means an attribute of type employees — select the people by their employee id(s).

For attributes with many options these inline lists can grow large; load them on demand (searchable, paginated) via GET /project/filter/attribute_values (dropdown) resp. GET /project/filter/employee (employees).

The value of an entry expresses the constraint. Common shapes:

Constraint	`value` example	Matches when …
equals (one of)	`[1]` or `[1, 2]`	attribute equals one of the given option ids
range	`{ "from": 4000, "to": 5000 }`	numeric value lies in `[from, to]`
text contains	`{ "contains": ["text"] }`	text value contains the phrase
assigned	`{ "assigned": true }`	the attribute is set on the project at all
negation	`{ "not": { "assigned": true } }`	wraps any of the above to invert it

Example — projects whose attribute named Realisierungszeitraum falls between 2018 and 2020:

attributes[0][name][]=Realisierungszeitraum
attributes[0][value][from]=2018
attributes[0][value][to]=2020

See filtered_listing.php in losys-demo for more worked examples.

limit

integer >= 0

Maximum number of projects to return per page. Keep this constant while paging through a result set.

The page size is additionally capped by a per-account limit (default 100). If your limit exceeds that cap, the response is clamped to the cap — page through with start to retrieve the remaining records. The page size actually in effect is always reported in the X-Paginator-Limit response header, and X-Paginator-Total reflects the full, uncapped result count — unless you opt into cap_total (see that parameter), in which case a large total may be capped.

Values above a hardcoded maximum are rejected with 422.

start

integer [ 0 .. 5000 ]

Offset of the first project to return (for pagination).

cap_total

boolean

Opt-in: cap the reported total hit count. When set (1/true), and the result set is larger than a server-side threshold, X-Paginator-Total reports that threshold instead of the exact count and the response carries X-Paginator-Capped: true. This avoids the cost of an exact count over a very large match set; the returned records and paging are unaffected — you can still page beyond the threshold. The threshold value is fixed by the server (you only choose whether to cap). Default off → exact total.

expand

Array of strings

Items Enum: "project_images" "project_videos" "parent" "children" "project_properties" "project_categories" "project_type_of_works" "project_type_of_constructions" "project_type_of_buildings" "project_address_contact_persons" "project_participating_companies" "company" "language" "*"

Related entities to include in the response. For every expand value you pass, the corresponding sub-entity is embedded — under a key of the same name — inside each project of the response. Pass several values comma-separated or repeated, or * to include all available expands.

Without expand a project only carries its own base fields; the relations below are added on demand. The concrete shape of each embedded sub-entity is best seen in the public reference implementation php-basic/public/json_listing.php in losys-demo.

Expand value	Adds …
`project_images`	the project's images (with their source-image data and URLs).
`project_videos`	the project's (YouTube) videos.
`parent`	the parent project — for a translation, the project it is a translation of.
`children`	the child projects — translations of this project into other languages.
`project_properties`	the project's attribute values (the configurable custom fields), each with its attribute definition.
`project_categories`	the categories assigned to the project (localized).
`project_type_of_works`	the "type of work" entries assigned to the project (localized).
`project_type_of_constructions`	the "type of construction" entries assigned to the project (localized).
`project_type_of_buildings`	the "type of building" entries assigned to the project (localized).
`project_address_contact_persons`	the contact persons attached to the project's address.
`project_participating_companies`	the other companies that participated in the project.
`company`	the owning company's data.
`language`	the project's language.

header Parameters

Accept-Language	string Enum: "de" "fr" "it" "en" Language to localize the response into. One of `de`, `fr`, `it`, `en`.
X-Paginator-Hash	string Send back the `X-Paginator-Hash` value from the previous page's response to let the API verify that your filter parameters did not change between pages. Strongly recommended when paging.

Responses

Response samples

Content type

application/json

[{"id": 0,
"title": "string",
"description": "string",
"yearOfCompletion": 0,
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"geolocationX": "string",
"geolocationY": "string",
"projectWebsite": "string",
"priority": 0,
"companyId": 0,
"languageId": 0,
"parentId": 0,
"status": "0",
"visibility": [true
],
"project_images": [{"id": 0,
"projectId": 0,
"imageUrl": "string",
"isMainImage": true,
"extralarge_image": "string",
"large_image": "string",
"medium_image": "string",
"small_image": "string",
"imageCaption": "string",
"imageRights": "string",
"imageSource": "string",
"original_image": null,
"old_image_id": 0,
"source_image_global_id": "string"
}
],
"project_videos": [{"id": 0,
"projectId": 0,
"embbedIframe": "string",
"videoImage": "string",
"isMainVideo": true,
"ordering": 0
}
],
"parent": { },
"children": [{ }
],
"project_properties": [{"id": 0,
"projectId": 0,
"projectAttributeId": 0,
"value": "string",
"display_value": "string",
"employee": null,
"employees": null,
"project_attribute": {"id": 0,
"companyId": 0,
"labels": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"type": "string",
"subtype": "string",
"orderingId": 0,
"view_web": true,
"view_datenblatt_extern": true,
"view_datenblatt_intern": true,
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_categories": [{"id": 0,
"projectId": 0,
"categoryId": 0,
"category": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
}
}
}
],
"project_type_of_works": [{"id": 0,
"projectId": 0,
"typeOfWorkId": 0,
"type_of_work": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_type_of_constructions": [{"id": 0,
"projectId": 0,
"typeOfConstructionId": 0,
"type_of_construction": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_type_of_buildings": [{"id": 0,
"projectId": 0,
"typeOfBuildingId": 0,
"type_of_building": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_address_contact_persons": [{"id": 0,
"projectId": 0,
"addressId": 0,
"contactPersonId": 0,
"view_web": true,
"view_datenblatt_extern": true,
"view_datenblatt_intern": true,
"refo_contact_person_id": 0,
"address": {"id": 0,
"companyId": 0,
"name": "string",
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"email": "string",
"phone": "string",
"fax": "string",
"mailBox": "string",
"website": "string",
"geolocationX": "string",
"geolocationY": "string",
"is_synced_with_company": true,
"is_synced_with_zefix": true,
"zefix_uid": "string",
"refo_address_id": 0,
"source_type": 0,
"source_global_id": "string"
},
"contact_person": {"id": 0,
"addressId": 0,
"firstName": "string",
"lastName": "string",
"gender": "string",
"email": "string",
"phone": "string",
"mobile": "string",
"avatar": "string",
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_participating_companies": [{"id": 0,
"projectId": 0,
"addressId": 0,
"contactPersonId": 0,
"orderingId": 0,
"view_web": true,
"view_datenblatt_extern": true,
"view_datenblatt_intern": true,
"address": {"id": 0,
"companyId": 0,
"name": "string",
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"email": "string",
"phone": "string",
"fax": "string",
"mailBox": "string",
"website": "string",
"geolocationX": "string",
"geolocationY": "string",
"is_synced_with_company": true,
"is_synced_with_zefix": true,
"zefix_uid": "string",
"refo_address_id": 0,
"source_type": 0,
"source_global_id": "string"
},
"works_involved": [{"id": 0,
"participatingCompanyId": 0,
"typeOfWorkId": 0,
"type_of_work": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
]
}
],
"company": {"id": 0,
"name": "string",
"alternativeName": "string",
"company_type": "string",
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"email": "string",
"inquiry_email": "string",
"phone": "string",
"fax": "string",
"mailBox": "string",
"website": "string",
"logoUrl": "string",
"logoUrlThumbnail": "string",
"geolocationX": "string",
"geolocationY": "string",
"status": "string",
"zefix_uid": "string",
"refo_company_id": 0
},
"language": {"id": 0,
"name": "string",
"shortName": "string",
"isDefault": true,
"de": "string",
"en": "string",
"fr": "string",
"it": "string"
}
}
]

Get a single project

Authorizations:

customerOAuth

path Parameters

projectId

required

integer

Numeric id of the project.

query Parameters

expand

Array of strings

Expand value	Adds …
`project_images`	the project's images (with their source-image data and URLs).
`project_videos`	the project's (YouTube) videos.
`parent`	the parent project — for a translation, the project it is a translation of.
`children`	the child projects — translations of this project into other languages.
`project_properties`	the project's attribute values (the configurable custom fields), each with its attribute definition.
`project_categories`	the categories assigned to the project (localized).
`project_type_of_works`	the "type of work" entries assigned to the project (localized).
`project_type_of_constructions`	the "type of construction" entries assigned to the project (localized).
`project_type_of_buildings`	the "type of building" entries assigned to the project (localized).
`project_address_contact_persons`	the contact persons attached to the project's address.
`project_participating_companies`	the other companies that participated in the project.
`company`	the owning company's data.
`language`	the project's language.

Responses

Response samples

Content type

application/json

{"id": 0,
"title": "string",
"description": "string",
"yearOfCompletion": 0,
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"geolocationX": "string",
"geolocationY": "string",
"projectWebsite": "string",
"priority": 0,
"companyId": 0,
"languageId": 0,
"parentId": 0,
"status": "0",
"visibility": [true
],
"project_images": [{"id": 0,
"projectId": 0,
"imageUrl": "string",
"isMainImage": true,
"extralarge_image": "string",
"large_image": "string",
"medium_image": "string",
"small_image": "string",
"imageCaption": "string",
"imageRights": "string",
"imageSource": "string",
"original_image": null,
"old_image_id": 0,
"source_image_global_id": "string"
}
],
"project_videos": [{"id": 0,
"projectId": 0,
"embbedIframe": "string",
"videoImage": "string",
"isMainVideo": true,
"ordering": 0
}
],
"parent": { },
"children": [{ }
],
"project_properties": [{"id": 0,
"projectId": 0,
"projectAttributeId": 0,
"value": "string",
"display_value": "string",
"employee": null,
"employees": null,
"project_attribute": {"id": 0,
"companyId": 0,
"labels": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"type": "string",
"subtype": "string",
"orderingId": 0,
"view_web": true,
"view_datenblatt_extern": true,
"view_datenblatt_intern": true,
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_categories": [{"id": 0,
"projectId": 0,
"categoryId": 0,
"category": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
}
}
}
],
"project_type_of_works": [{"id": 0,
"projectId": 0,
"typeOfWorkId": 0,
"type_of_work": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_type_of_constructions": [{"id": 0,
"projectId": 0,
"typeOfConstructionId": 0,
"type_of_construction": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_type_of_buildings": [{"id": 0,
"projectId": 0,
"typeOfBuildingId": 0,
"type_of_building": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_address_contact_persons": [{"id": 0,
"projectId": 0,
"addressId": 0,
"contactPersonId": 0,
"view_web": true,
"view_datenblatt_extern": true,
"view_datenblatt_intern": true,
"refo_contact_person_id": 0,
"address": {"id": 0,
"companyId": 0,
"name": "string",
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"email": "string",
"phone": "string",
"fax": "string",
"mailBox": "string",
"website": "string",
"geolocationX": "string",
"geolocationY": "string",
"is_synced_with_company": true,
"is_synced_with_zefix": true,
"zefix_uid": "string",
"refo_address_id": 0,
"source_type": 0,
"source_global_id": "string"
},
"contact_person": {"id": 0,
"addressId": 0,
"firstName": "string",
"lastName": "string",
"gender": "string",
"email": "string",
"phone": "string",
"mobile": "string",
"avatar": "string",
"source_type": 0,
"source_global_id": "string"
}
}
],
"project_participating_companies": [{"id": 0,
"projectId": 0,
"addressId": 0,
"contactPersonId": 0,
"orderingId": 0,
"view_web": true,
"view_datenblatt_extern": true,
"view_datenblatt_intern": true,
"address": {"id": 0,
"companyId": 0,
"name": "string",
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"email": "string",
"phone": "string",
"fax": "string",
"mailBox": "string",
"website": "string",
"geolocationX": "string",
"geolocationY": "string",
"is_synced_with_company": true,
"is_synced_with_zefix": true,
"zefix_uid": "string",
"refo_address_id": 0,
"source_type": 0,
"source_global_id": "string"
},
"works_involved": [{"id": 0,
"participatingCompanyId": 0,
"typeOfWorkId": 0,
"type_of_work": {"id": 0,
"companyId": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
},
"source_type": 0,
"source_global_id": "string"
}
}
]
}
],
"company": {"id": 0,
"name": "string",
"alternativeName": "string",
"company_type": "string",
"address": "string",
"zipcode": "string",
"city": "string",
"canton": "string",
"country": "string",
"email": "string",
"inquiry_email": "string",
"phone": "string",
"fax": "string",
"mailBox": "string",
"website": "string",
"logoUrl": "string",
"logoUrlThumbnail": "string",
"geolocationX": "string",
"geolocationY": "string",
"status": "string",
"zefix_uid": "string",
"refo_company_id": 0
},
"language": {"id": 0,
"name": "string",
"shortName": "string",
"isDefault": true,
"de": "string",
"en": "string",
"fr": "string",
"it": "string"
}
}

Filters

Discover the values you can offer in a filter UI — types of work / building / construction, categories, cantons, languages, years, project attributes, employees and attribute option values.

All Filters endpoints accept the same filter parameters as GET /project (e.g. companyId / companyIds[], yearFrom / yearTo, cantons[], typeOfWorkIds[], searchText, attributes …). Passing them restricts the returned values to those used by the matching subset of your projects — for example companyIds[]=14 returns only the values actually used by projects of company 14. (The searchable catalog endpoints additionally expose a scope parameter that turns this restriction on or off — see there.)

Filter values are company-specific. Types of work / building / construction, categories and project attributes are master data that each company maintains for itself. If your company belongs to a company group, these endpoints span the whole group — so the same logical entry (e.g. a "Masonry" type of work) may exist several times, once per company that defined it, each with its own id. The attributeByName view of the attributes facet exists precisely to bridge this (see the attributes parameter).

Available filter values

Returns the values you can offer in a filter UI (type of work, type of building, type of construction, categories, cantons, languages, years, project attributes …), already localized. Optionally pass the same filters as on /project/ to restrict the returned options.

Only values actually in use are returned. The endpoint does not list every value defined in the system — it returns only those values that are actually used by projects the caller has access to. A type of work, category, canton, language, etc. that no accessible project uses will not appear here. This keeps the filter UI free of options that would yield no results.

Use facets to request only what you need. By default every facet is built. For large data sets — typically large company groups — this is slow, and the high-cardinality taxonomy facets (typeOfWork, typeOfConstruction, typeOfBuilding, category) are size-capped: if one of them would exceed an internal maximum, the whole request fails with 422 instead of returning a multi-thousand-entry list that is unusable as a filter UI anyway (the cap value is intentionally not published). Naming only the facets you actually need (see the facets parameter) avoids both. For a facet that may grow large, load its values from the matching searchable, paginated endpoint instead — GET /project/filter/type_of_work (and its type_of_building / type_of_construction siblings), …/filter/employee or …/filter/attribute_values.

The same filters as on /project/ may be passed to restrict the returned options to the matching subset of your projects (see the Filters section intro).

Authorizations:

customerOAuth

query Parameters

displayLocale

string

Language to localize the returned values into (e.g. en).

facets

string

Restrict which filter dimensions ("facets") are built and returned, as a comma-separated list (e.g. facets=canton,year,typeOfWork). When omitted, every facet is built — which is slower and can trip the 422 size cap on the taxonomy facets (see the endpoint description). Naming only the facets you actually need is strongly recommended.

Facet	Returns
`typeOfWork`	Types of work used by accessible projects. Also accepts `typeOfWork:frequent` to return only the most frequently used ones (a small, bounded set that never triggers the `422` cap).
`typeOfConstruction`	Types of construction in use.
`typeOfBuilding`	Types of building in use.
`category`	Categories in use.
`canton`	Cantons in use.
`year`	Years of completion in use.
`languages`	Languages your company maintains.
`attribute`	Project-attribute (custom field) definitions, ordered.
`attributeByName`	The same attributes keyed by name (see the `attributes` parameter).

Responses

Response samples

Content type

application/json

{"languages": [{ }
],
"canton": [{ }
],
"category": [{ }
],
"typeOfWork": {"property1": { },
"property2": { }
},
"typeOfBuilding": {"property1": { },
"property2": { }
},
"typeOfConstruction": {"property1": { },
"property2": { }
},
"attribute": [{ }
],
"attributeByName": {"property1": { },
"property2": { }
},
"year": {"property1": 0,
"property2": 0
}
}

List types of work (searchable, paginated)

Returns the "type of work" catalog as a searchable, paginated list of { id, titles } entries. Use it to populate a type-of-work picker and to resolve the ids you pass to the typeOfWorkIds filter on /project/.

Unlike the typeOfWork member of Available filter values — which is always returned in full — this endpoint is searchable (text_search) and paginated (start/limit, X-Paginator-*), so it stays usable for very large catalogs.

scope=catalog (default) returns the whole catalog of the companies you can access (your company group); scope=used returns only the types of work actually used by projects you can see (the same set as the typeOfWork member of /project/filter/multiple_choice_values).

Authorizations:

customerOAuth

query Parameters

text_search	string <= 200 characters Case-insensitive substring filter on the entry titles. Matches a title in any language (e.g. searching `Masonry` also returns an entry whose English title matches, even if you display it in German).
displayLocale	string Language to localize the returned values into (e.g. `en`).
languages	Array of strings <= 10 items Language short names, e.g. `de`, `fr`, `it`, `en`. Only languages your company has configured can be requested (see the single `language` parameter and the `languages` list returned by `Available filter values`).
scope	string Default: "catalog" Enum: "catalog" "used" Controls whether the project filters are applied: `catalog` (default) returns the whole catalog of the companies you can access (your company group) and ignores the project filters (`companyIds[]`, `yearFrom`, `cantons[]`, …). `used` returns only the entries actually used by projects you can see and honours the project filters — e.g. `companyIds[]=14` restricts the values to those used by company 14's projects.
limit	integer >= 0 Maximum number of projects to return per page. Keep this constant while paging through a result set. The page size is additionally capped by a per-account limit (default 100). If your `limit` exceeds that cap, the response is clamped to the cap — page through with `start` to retrieve the remaining records. The page size actually in effect is always reported in the `X-Paginator-Limit` response header, and `X-Paginator-Total` reflects the full, uncapped result count — unless you opt into `cap_total` (see that parameter), in which case a large total may be capped. Values above a hardcoded maximum are rejected with `422`.
start	integer [ 0 .. 5000 ] Offset of the first project to return (for pagination).

header Parameters

Accept-Language	string Enum: "de" "fr" "it" "en" Language to localize the response into. One of `de`, `fr`, `it`, `en`.
X-Paginator-Hash	string Send back the `X-Paginator-Hash` value from the previous page's response to let the API verify that your filter parameters did not change between pages. Strongly recommended when paging.

Responses

Response samples

Content type

application/json

[{"id": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
}
}
]

List types of building (searchable, paginated)

Returns the "type of building" catalog as a searchable, paginated list of { id, titles } entries — the companion of List types of work for the typeOfBuildingIds filter on /project/. Same scope, text_search, languages and pagination semantics.

Authorizations:

customerOAuth

query Parameters

text_search	string <= 200 characters Case-insensitive substring filter on the entry titles. Matches a title in any language (e.g. searching `Masonry` also returns an entry whose English title matches, even if you display it in German).
displayLocale	string Language to localize the returned values into (e.g. `en`).
languages	Array of strings <= 10 items Language short names, e.g. `de`, `fr`, `it`, `en`. Only languages your company has configured can be requested (see the single `language` parameter and the `languages` list returned by `Available filter values`).
scope	string Default: "catalog" Enum: "catalog" "used" Controls whether the project filters are applied: `catalog` (default) returns the whole catalog of the companies you can access (your company group) and ignores the project filters (`companyIds[]`, `yearFrom`, `cantons[]`, …). `used` returns only the entries actually used by projects you can see and honours the project filters — e.g. `companyIds[]=14` restricts the values to those used by company 14's projects.
limit	integer >= 0 Maximum number of projects to return per page. Keep this constant while paging through a result set. The page size is additionally capped by a per-account limit (default 100). If your `limit` exceeds that cap, the response is clamped to the cap — page through with `start` to retrieve the remaining records. The page size actually in effect is always reported in the `X-Paginator-Limit` response header, and `X-Paginator-Total` reflects the full, uncapped result count — unless you opt into `cap_total` (see that parameter), in which case a large total may be capped. Values above a hardcoded maximum are rejected with `422`.
start	integer [ 0 .. 5000 ] Offset of the first project to return (for pagination).

header Parameters

Accept-Language	string Enum: "de" "fr" "it" "en" Language to localize the response into. One of `de`, `fr`, `it`, `en`.
X-Paginator-Hash	string Send back the `X-Paginator-Hash` value from the previous page's response to let the API verify that your filter parameters did not change between pages. Strongly recommended when paging.

Responses

Response samples

Content type

application/json

[{"id": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
}
}
]

List types of construction (searchable, paginated)

Returns the "type of construction" catalog as a searchable, paginated list of { id, titles } entries — the companion of List types of work for the typeOfConstructionIds filter on /project/. Same scope, text_search, languages and pagination semantics.

Authorizations:

customerOAuth

query Parameters

text_search	string <= 200 characters Case-insensitive substring filter on the entry titles. Matches a title in any language (e.g. searching `Masonry` also returns an entry whose English title matches, even if you display it in German).
displayLocale	string Language to localize the returned values into (e.g. `en`).
languages	Array of strings <= 10 items Language short names, e.g. `de`, `fr`, `it`, `en`. Only languages your company has configured can be requested (see the single `language` parameter and the `languages` list returned by `Available filter values`).
scope	string Default: "catalog" Enum: "catalog" "used" Controls whether the project filters are applied: `catalog` (default) returns the whole catalog of the companies you can access (your company group) and ignores the project filters (`companyIds[]`, `yearFrom`, `cantons[]`, …). `used` returns only the entries actually used by projects you can see and honours the project filters — e.g. `companyIds[]=14` restricts the values to those used by company 14's projects.
limit	integer >= 0 Maximum number of projects to return per page. Keep this constant while paging through a result set. The page size is additionally capped by a per-account limit (default 100). If your `limit` exceeds that cap, the response is clamped to the cap — page through with `start` to retrieve the remaining records. The page size actually in effect is always reported in the `X-Paginator-Limit` response header, and `X-Paginator-Total` reflects the full, uncapped result count — unless you opt into `cap_total` (see that parameter), in which case a large total may be capped. Values above a hardcoded maximum are rejected with `422`.
start	integer [ 0 .. 5000 ] Offset of the first project to return (for pagination).

header Parameters

Accept-Language	string Enum: "de" "fr" "it" "en" Language to localize the response into. One of `de`, `fr`, `it`, `en`.
X-Paginator-Hash	string Send back the `X-Paginator-Hash` value from the previous page's response to let the API verify that your filter parameters did not change between pages. Strongly recommended when paging.

Responses

Response samples

Content type

application/json

[{"id": 0,
"titles": {"de": "string",
"displayLocale": "string",
"property1": "string",
"property2": "string"
}
}
]

List employees (searchable, paginated)

Returns the employees you can offer in a filter UI as a searchable, paginated list of { id, firstName, lastName } entries. Employees are attached to projects through a project attribute of type employees (see the attributes parameter); use the ids returned here to build such an attributes constraint.

scope=used (default) returns only the employees actually referenced by projects you can see (honouring the project filters); scope=catalog returns all employees of your accessible company group. text_search matches the combined firstName lastName.

Authorizations:

customerOAuth

query Parameters

scope	string Default: "used" Enum: "catalog" "used" Controls whether the project filters are applied: `used` (default) returns only the values actually used by projects you can see and honours the project filters (`companyIds[]`, `yearFrom`, …). `catalog` returns the whole set defined for your accessible company group and ignores the project filters.
text_search	string <= 200 characters Case-insensitive substring filter on the returned entries — matched against the employee's `firstName lastName` (on `/filter/employee`) resp. the localized option `value` (on `/filter/attribute_values`).
displayLocale	string Language to localize the returned values into (e.g. `en`).
limit	integer >= 0 Maximum number of projects to return per page. Keep this constant while paging through a result set. The page size is additionally capped by a per-account limit (default 100). If your `limit` exceeds that cap, the response is clamped to the cap — page through with `start` to retrieve the remaining records. The page size actually in effect is always reported in the `X-Paginator-Limit` response header, and `X-Paginator-Total` reflects the full, uncapped result count — unless you opt into `cap_total` (see that parameter), in which case a large total may be capped. Values above a hardcoded maximum are rejected with `422`.
start	integer [ 0 .. 5000 ] Offset of the first project to return (for pagination).

header Parameters

Accept-Language	string Enum: "de" "fr" "it" "en" Language to localize the response into. One of `de`, `fr`, `it`, `en`.
X-Paginator-Hash	string Send back the `X-Paginator-Hash` value from the previous page's response to let the API verify that your filter parameters did not change between pages. Strongly recommended when paging.

Responses

Response samples

Content type

application/json

[{"id": 0,
"firstName": "string",
"lastName": "string"
}
]

List attribute option values (searchable, paginated)

Returns the selectable option values of one project-attribute filter field as a searchable, paginated list of { value, id, key } entries. Pass the attribute's id(s) via attribute_ids[] — these are the ids of the corresponding attributeByName group (for a company group, one logical attribute may span several ids; pass them all to merge their values).

This is the on-demand companion for dropdown attributes whose option lists are too large to ship inline. (For an employees attribute, list the selectable people via GET /project/filter/employee instead.) scope=used (default) returns only the values actually used by projects you can see (honouring the project filters); scope=catalog returns all values defined for the attribute. text_search matches the localized value.

Authorizations:

customerOAuth

query Parameters

attribute_ids required	Array of integers non-empty The id(s) of the attribute (`attributeByName` group) whose option values to list. At least one is required.
scope	string Default: "used" Enum: "catalog" "used" Controls whether the project filters are applied: `used` (default) returns only the values actually used by projects you can see and honours the project filters (`companyIds[]`, `yearFrom`, …). `catalog` returns the whole set defined for your accessible company group and ignores the project filters.
text_search	string <= 200 characters Case-insensitive substring filter on the returned entries — matched against the employee's `firstName lastName` (on `/filter/employee`) resp. the localized option `value` (on `/filter/attribute_values`).
displayLocale	string Language to localize the returned values into (e.g. `en`).
limit	integer >= 0 Maximum number of projects to return per page. Keep this constant while paging through a result set. The page size is additionally capped by a per-account limit (default 100). If your `limit` exceeds that cap, the response is clamped to the cap — page through with `start` to retrieve the remaining records. The page size actually in effect is always reported in the `X-Paginator-Limit` response header, and `X-Paginator-Total` reflects the full, uncapped result count — unless you opt into `cap_total` (see that parameter), in which case a large total may be capped. Values above a hardcoded maximum are rejected with `422`.
start	integer [ 0 .. 5000 ] Offset of the first project to return (for pagination).

header Parameters

Accept-Language	string Enum: "de" "fr" "it" "en" Language to localize the response into. One of `de`, `fr`, `it`, `en`.
X-Paginator-Hash	string Send back the `X-Paginator-Hash` value from the previous page's response to let the API verify that your filter parameters did not change between pages. Strongly recommended when paging.

Responses

Response samples

Content type

application/json

[{"value": "string",
"id": 0,
"key": 0
}
]

PDF

Generate PDF documents from project references (asynchronous).

Start PDF generation

Starts an asynchronous PDF generation job for the projects matching the given filters. Returns a job_uuid you can poll for completion via /project/pdf/{jobUuid}/status.

The generated PDF contains the data of the matching projects. Use the filter parameters to control which projects are included in the PDF.

Filter parameters are passed with a filter_ prefix (e.g. filter_companyIds[]=1, filter_yearFrom=2020) and mirror the parameters of /project/.

Authorizations:

customerOAuth

query Parameters

printlayout	string PDF template id, or one of `datasheet` / `datalist` (default).
mode	string Default: "extern" Enum: "extern" "intern" Which data variant to render: `extern` (default) — the external datasheet, i.e. the public-facing content, exactly as it is shown on a website. `intern` — the internal datasheet, which may include additional internal fields.
orientation	string Enum: "portrait" "landscape" Page orientation. Defaults depend on the chosen layout/template.
format	string Enum: "a4" "a3" Paper format of the generated PDF. When omitted, the format from the chosen layout/template is used (`a4` by default).
quality	string Default: "regular" Enum: "regular" "low" Image rendering quality of the generated PDF: `regular` (default) — full quality. `low` — lower image resolution, producing a smaller file (useful for large project lists or faster downloads).
displayLocale	string Language to render the PDF content in (e.g. `de`, `fr`, `it`, `en`). When omitted, the request's `Accept-Language` / default locale is used.
companycover	integer Company id to render a cover sheet for.
usercover	integer Employee id to render on the cover sheet.
secondusercover	integer Optional second employee id to render on the cover sheet.

Responses

Response samples

Content type

application/json

{"job_uuid": "de25c4df-6d4e-439f-9d5f-a4c55d30f26e",
"message": "string"
}

Poll PDF generation status

Authorizations:

customerOAuth

path Parameters

jobUuid

required

string <uuid>

The job_uuid returned when starting the job.

Responses

Response samples

Content type

application/json

{"pdf_url": "string",
"message": "string"
}

List PDF templates

Authorizations:

customerOAuth

Responses

Response samples

Content type

application/json

[{"id": "string"
}
]

List PDF templates for a specific company

Authorizations:

customerOAuth

path Parameters

companyId

required

integer

Responses

Response samples

Content type

application/json

[{"id": "string"
}
]

HTML

Ready-to-embed HTML widgets.

Embeddable project box (HTML)

Returns a ready-to-embed, interactive HTML widget (with built-in search, map and PDF controls). Requires Accept: text/html.

Authorizations:

customerOAuth

query Parameters

hide	Array of strings Items Enum: "search" "map" "pdf" UI components to hide.
skip_includes	Array of strings Items Enum: "jquery" "bootstrap" "popper" "select2" "polyfill" External libraries the widget should not load itself.

Responses

Response samples

Content type

application/json

{"type": "string",
"code": 0,
"message": "string",
"field_errors": {"property1": ["string"
],
"property2": ["string"
]
}
}

Losys Customer API (1.0.0)

Base URL

Authentication

Reuse the access token — do not request one per call

Localization

Compression (Accept-Encoding)

Pagination

Pagination response headers

Caching & the X-Paginator-Hash header

Support

Projects

List projects

Authorizations:

query Parameters

header Parameters

Responses

Response samples

Get a single project

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Filters

Available filter values

Authorizations:

query Parameters

Responses

Response samples

List types of work (searchable, paginated)

Authorizations:

query Parameters

header Parameters

Responses

Response samples

List types of building (searchable, paginated)

Authorizations:

query Parameters

header Parameters

Responses

Response samples

List types of construction (searchable, paginated)

Authorizations:

query Parameters

header Parameters

Responses

Response samples

List employees (searchable, paginated)

Authorizations:

query Parameters

header Parameters

Responses

Response samples

List attribute option values (searchable, paginated)

Authorizations:

query Parameters

header Parameters

Responses

Response samples

PDF

Start PDF generation

Authorizations:

query Parameters

Responses

Response samples

Poll PDF generation status

Authorizations:

path Parameters

Responses

Response samples

List PDF templates

Authorizations:

Responses

Response samples

List PDF templates for a specific company

Authorizations:

path Parameters

Responses

Response samples

HTML

Caching & the `X-Paginator-Hash` header