API Introduction
The public REST API for displaying your published references on your own website or intranet.
The public REST API delivers a company's published references as JSON. It exists for one job and does it well: letting agencies and web teams build reference catalogs on the company's own website or intranet — list pages, filterable catalogs, and detail pages — while the content stays maintained on the platform.
Base URL
https://referenzen.com/api/v1
All endpoints are plain HTTPS GET requests and return JSON. Endpoints can equivalently be called via the explicit dispatcher form https://referenzen.com/api/v1/index.cfm?endpoint=/references/search&… - the clean path form above is recommended.
Authentication & scope
Every request carries an API key as the apiKey query parameter. The key identifies your company: all endpoints automatically return only your own company's data — there is no company parameter to pass (or to get wrong). See Authentication.
The endpoints at a glance
| Endpoint | Purpose |
|---|---|
GET /references/referenceprojects | The catalog list — your published references, paginated and filterable |
GET /references/referenceproject | Full detail of a single reference (for detail pages) |
GET /references/search | Full-text + faceted search with aggregations |
GET /references/filters | Filter definitions + options, ready to render a filter sidebar |
GET /branches/branches | Your industry tree with per-branch reference counts |
GET /references/export | Bulk export (Excel or JSON) — back-office use, extra credentials required |
GET /apps/settings | Stored configuration of a registered widget/app instance |
Follow the catalog guide for how they fit together.
Conventions
Languages
Content endpoints accept lang_ID: 1 = English, 2 = German (default 2). Only these two values are valid — anything else falls back to your API key's default language.
What is delivered
The API serves published references released to the API channel (see publication channels). Draft, internal, and non-API content is never returned. Client information respects each client's display type; individual fields respect their release levels.
Responses & status codes
Responses are the payload directly — a JSON array or object without an envelope.
| Status | Meaning |
|---|---|
200 | Success — body contains the result |
204 | No content — the query matched nothing (empty body, not an empty array) |
401 | Missing or invalid API key (or no access to the requested resource) |
Handle 204 explicitly: an empty result set arrives as 204 with an empty body. Parsing the body of a 204 as JSON will fail in most HTTP clients.
CORS & JSONP
Cross-origin requests are allowed, so the API can be called directly from browser code. For legacy integrations, JSONP is supported via a callback parameter.
Calling the API from the browser exposes your API key to visitors. The key grants read access to your published content only — but if you prefer to keep it private, proxy the calls through your own backend.
Field name casing
JSON field names follow the platform's conventions and are case-sensitive as documented per endpoint — note mixed styles like reference_ID, projecttitle, and the aggregation keys V/C in search responses. Copy field names from the endpoint reference rather than guessing.
Quick start
# Your 10 newest published references, in English
curl "https://referenzen.com/api/v1/references/referenceprojects?apiKey=YOUR_KEY&lang_ID=1&records=10&page=1&orderby=datefrom%20desc"
Continue with Authentication or jump into the endpoint reference in the sidebar.