{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1e959002-6536-42a3-9f5b-7af231cf6a9d","name":"Cathago APIs | Version 3.8.0","description":"# Cathago API\n\n**Last updated: 30.09.2026** · Version 3.8.0\n\n---\n\n### What is this?\n\nThis interface connects your ERP or merchandise-management system to Cathago. Use it to transfer  \nconstruction sites, staff, suppliers, framework contracts, price lists and business documents  \n(orders, delivery notes, invoices, credit notes) automatically instead of by hand.\n\nThese pages are written for the person setting up the connection — at your company or at your  \nsoftware provider.\n\n### What you need — 3 steps\n\n1. **Create an API key.** In the Cathago web app: `Admin Settings` → `API Keys` →  \n    `Create API Key`. You can create as many keys as you need. There is no call limit.\n    \n2. **Note your company ID.** It is on the same page and is called `companyAccountId` here.  \n    Every single call needs it.\n    \n3. **Choose an environment.** Always try the test system first, never production.\n    \n\n### The two systems\n\n| System | Address to call | What it is for |\n| --- | --- | --- |\n| Test system | `https://api.staging.cathago.de` | For trying things out. The data is not real. |\n| Live system | `https://api.cathago.de` | Your real data. |\n\nEvery address on these pages is written as `{{baseUrl}}/…`. That stands for whichever of the two  \nsystems you are working against. It is set to the **live system** here.\n\n**To try something against the test system instead:** open the collection in Postman, go to the  \n**Variables** tab, and change `baseUrl` to `https://api.staging.cathago.de`. Every call switches  \nover at once. Change it back when you are done.\n\n> **Careful:** your API key is different on each system. A test key will not work against the live  \nsystem, and the other way round. \n  \n\n### Authentication\n\nEvery call needs this header:\n\n| Header | Value |\n| --- | --- |\n| `API-Key` | Your API key |\n\n> **Security:** Treat the key like a password. If it leaks, delete it immediately under  \n`Admin Settings` → `API Keys`. \n  \n\n### How to read these pages\n\nEvery call has the same sections, in the same order. Learn them once and you have learned all 62.\n\n1. **What this call does** — one sentence.\n    \n2. **What you need first** — what must already exist before you call.\n    \n3. **Parameters** — what goes in the address line.\n    \n4. **The fields** — every field: type, whether it is required, its default, what it means.\n    \n5. **What you get back** — the server's answer, and what a success does _not_ guarantee.\n    \n6. **Common mistakes** — what you see, why it happened, what to do about it.\n    \n7. **What we could not confirm** — anything the interface does not settle. If a page says nothing  \n    is unconfirmed, everything on it was checked.\n    \n\nAlongside them sits the **example data**: a complete, realistic payload where every field carries a  \ncomment giving its meaning, whether it is required, and the allowed values.\n\n> Every statement on these pages was checked against the running interface — not carried over from  \nan older version of the documentation. \n  \n\n### Three things people get wrong\n\n**1\\. The comments are not part of the real payload.**  \nIn the examples, each field is followed by a comment after two slashes:\n\n```\n\"title\": \"Neubau Wohnpark Süd-West\", // Name of the construction site. Required.\n\n ```\n\nThose comments are for reading only — the server rejects a payload that still contains them.\n\n- **In Postman:** you need do nothing. Postman strips the comments when it sends the request.\n    \n- **In your own program:** delete the comments by hand, or use a parser that understands them  \n    (JSONC / JSON5).\n    \n\n> **Do not simply delete everything after** **`//`****.** Web addresses such as  \n`https://maps.app.goo.gl/...` contain two slashes too. A blunt find-and-replace destroys them. \n  \n\n**2\\. Dates and amounts look different in the payload than on paper.**\n\n|  | In English text | In the payload (JSON) |\n| --- | --- | --- |\n| Date | 15 May 2026 | `\"2026-05-15\"` |\n| Amount | €1,234.56 | `1234.56` |\n\nAmounts carry **no** quotation marks and **no** currency symbol.\n\n**3\\. A \"construction site\" is called** **`project`** **in the interface.**  \nThe Cathago web app says Baustelle (construction site). The interface calls the same thing  \n`project`. Field names are always English and are never translated.\n\n### Four rules that apply to every call\n\nThese come from how the server reads your JSON. They are the same on every endpoint, and between  \nthem they explain most integrations that appear to work but quietly do the wrong thing.\n\n**1\\. A misspelled field name is ignored, not rejected.**  \nSend `\"titel\"` instead of `\"title\"` and the server does not complain. It accepts the call, skips  \nthat field, and returns success. Nothing tells you the value never arrived.\n\n> Always read the response back and check that the field you sent really came back. \n  \n\n**2\\. An unrecognised value for a fixed-choice field behaves in one of two ways.**  \nFields with a fixed set of values — status, type, role, mode — either fall back to a built-in  \ndefault, or are rejected. Which one you get depends on the field, so **each field's page says****which**. Do not assume.\n\nThe dangerous half is the silent one. `projectStatus` accepts `DRAFT`, `ACTIVE`, `ARCHIVED` and  \n`DEACTIVATED`, and falls back to `ACTIVE`. So a misspelled `\"ARCHIEVED\"` does not archive the site  \nand does not report an error — it silently sets the site to **ACTIVE**.\n\n`role` behaves the other way: it has no fallback, so a wrong value fails loudly with a `400`.\n\n> Earlier versions of these pages printed that misspelling. If your integration copied it, your  \nsites have been activated instead of archived. Search your code for `ARCHIEVED`. \n  \n\n**3\\. Capitalisation does not matter.**  \n`\"title\"`, `\"Title\"` and `\"TITLE\"` are all accepted, as are `\"active\"` and `\"ACTIVE\"`. Only the  \nspelling has to be right.\n\n**4\\. Dates and times are always text, never numbers.**  \nYou receive `\"2026-05-15\"` and `\"2026-05-15T09:30:00\"`, never a numeric timestamp. Send them the  \nsame way.\n\n### What is new in version 3.8.0\n\n**Call-off agreements can be maintained over this interface.** They are a kind of price list, stored  \nwith your price lists and reached through the same addresses with `?type=CALL_OFF` added. **Price****Lists** and **Products** each have a **Standard** and a **Call-Off** subfolder now. Nothing you  \nalready have changes: send no `type` and both behave exactly as they did in 3.7.1.\n\nThree other changes, all in your favour:\n\n1. **An update to a price list no longer resets** **`type`****.** It used to, silently, so a `RENTAL` list  \n    became `STANDARD` on any `PATCH` that did not repeat the field. `currency`, `status` and  \n    `tenantProjectAssignments` still reset — the Price Lists section says so on the call itself.\n    \n2. **The product bulk call can report every row.** Add `response=summary` and you get a per-row  \n    result instead of an answer that fails on the first bad row while the good ones are already  \n    written. Use it for anything unattended.\n    \n3. **New calls:** \"Look up one price list\", and a stack of named discounts and surcharges on a  \n    product's price.\n    \n\n### The sections\n\n| # | Section | What is in it |\n| --- | --- | --- |\n| 1 | Projects | Create, change, search and delete construction sites — with addresses, members and locations |\n| 2 | Members | Create, change, invite and delete staff |\n| 3 | Business Documents | Orders, delivery notes, invoices, credit notes — with file attachments |\n| 4 | Suppliers | Search and maintain supplier accounts |\n| 5 | Contracts | Framework contracts with contract file and attachments |\n| 6 | Price Lists | Price lists and call-off agreements — a **Standard** and a **Call-Off** half |\n| 7 | Products | The articles on them — the same **Standard** and **Call-Off** split |\n| 8 | Catalogs _(deprecated)_ | Do not use. Replaced by Price Lists. |\n| 9 | Articles _(deprecated)_ | Do not use. Replaced by Products. |\n\nCall-offs have two halves, and they live in two places. The **agreement** — the quantity you  \nnegotiated, the price you negotiated for it, and the articles it covers — is in **Price Lists →****Call-Off** and **Products → Call-Off**. The **draw-down** — each time somebody actually calls a  \nquantity off — is a business document in **Business Documents**, created with `documentType` set to  \n`CALL_OFF`.\n\n> **Deprecated** means: still works, but is no longer developed and will be switched off at some  \npoint. Do not build anything new on it. \n  \n\n### Help\n\nStuck? Write to your Cathago contact and include: the name of the call, the payload you sent, and  \nthe server's full response.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"50511806","team":3971464,"collectionId":"1e959002-6536-42a3-9f5b-7af231cf6a9d","publishedId":"2sBYB4MTAt","public":true,"publicUrl":"https://apidocs.cathago.de","privateUrl":"https://go.postman.co/documentation/50511806-1e959002-6536-42a3-9f5b-7af231cf6a9d","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":"CATHAGO API Docs - AI Copilot for Construction Procurement "}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.12.10","publishDate":"2026-09-30T09:26:54.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"CATHAGO API Docs - AI Copilot for Construction Procurement ","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"Production","id":"c50f5d1e-c418-4bc7-836d-ca44255e4620","owner":"23106842","values":[{"key":"baseUrl","value":"","enabled":true,"type":"default"},{"key":"apiKey","value":"","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/11e5d52a4428377ecc0efb6cc7b3b4c6987065ce8f67aa0c8ca6295768b3299e","favicon":"https://res.cloudinary.com/postman/image/upload/v1661959504/team/hffnfgqqyuayr1ge6id1.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Production","value":"23106842-c50f5d1e-c418-4bc7-836d-ca44255e4620"}],"canonicalUrl":"https://apidocs.cathago.de/view/metadata/2sBYB4MTAt"}