Je projectgegevens, verbonden.

Eerste verzoek

curl "$CONTACTPORTAAL_BASE_URL/api/v1/project" \
  -H "Authorization: Bearer $CONTACTPORTAAL_API_KEY"

Stel beide omgevingsvariabelen in voor je eigen organisatie en sleutel. Het project wordt automatisch bepaald door de sleutel.

Endpoints

Gegevens en velden

Alleen geselecteerde categorieën zijn toegankelijk. Dit zijn CRM-gegevens, inclusief concepten en persoonsgegevens. De documentatie is publiek; projectgegevens vereisen altijd een sleutel.

Volledige aansluitgids

Authenticatie, paginering, foutcodes, rotatie en de verschillen met de portaal-API en MCP.

# ContactPortaal Project API v1

## Aansluiten
Gebruik de HTTPS-basis-URL van de organisatie waar de sleutel is aangemaakt.
Elke organisatie heeft een eigen deployment. Een sleutel werkt alleen daar en
is gebonden aan precies één project. Er is geen login of token-refresh nodig.

Een projectadmin maakt een sleutel aan via Instellingen > API, kiest de
gegevenscategorieën en een geldigheid van 30, 90 of 365 dagen. Het secret wordt
één keer getoond. De volledige waarde cp_… is de Bearer API key; er is geen
apart client-ID of client-secret nodig. De zichtbare prefix is geen credential.
Bewaar het secret in een secret manager of de beveiligde instellingen van je
AI-integratie. Zet het niet in browsercode, URL's, documentatie of prompts.

## Authenticatie
Authorization: Bearer <CONTACTPORTAAL_API_KEY>
Accept: application/json

GET /api/v1/project
Geeft { project: { id, code, name }, resources: string[], access: "read" }.
Controleer hiermee je verbinding en beschikbare gegevenscategorieën.
X-Project-Id is niet nodig. Een afwijkend project-ID geeft 403.

GET /api/v1/records/{resource}?limit=50&offset=0
Geeft { items: [...], limit: 50, offset: 0, next_offset: 50 | null }.
Volg next_offset totdat deze null is. Limit: 1–100, standaard 50.
Offset: 0–1000000, standaard 0. Sortering: id oplopend.
Paginering is geen momentopname; records kunnen tussentijds wijzigen.
Andere queryparameters worden afgewezen. Er zijn nog geen zoek- of datumfilters.

GET /api/v1/records/{resource}/{id}
Geeft { item: {...} }. Gebruik een UUID uit de lijstrespons.
Lijst en detail geven dezelfde gedocumenteerde velden terug.

## Beschikbare resources en responsevelden
- stakeholders (Stakeholders): id,code,name,description,type,subtype,subproject_id,created_at,updated_at
- contact-persons (Contactpersonen): id,first_name,last_name,email,phone,mobile_phone,function,subproject_id,created_at,updated_at
- contact-moments (Contactmomenten): id,title,type,description,occurred_at,is_draft,assigned_to,created_at,updated_at
- tasks (Taken): id,text,note,handled,due_at,priority,assigned_to,subject_type,subject_id,created_at,updated_at
- issues (Issues en raakvlakken): id,code,name,description,rationale,closed_at,deadline,impact,created_at,updated_at
- complaints (Meldingen): id,date,text,status,complainant_name,assigned_to,created_at,updated_at
- requirements (Klanteisen): id,code,title,description,status,impact,assigned_to,created_at,updated_at
- permits (Vergunningen): id,code,title,description,status,reference_number,authority_type,applied_date,granted_date,expiry_date,created_at,updated_at
- permit-conditions (Vergunningvoorwaarden): id,permit_id,requirement_text,component,discipline,condition_type,phase,deadline,note,status,created_at,updated_at
- land-acquisitions (Grondverwerving): id,title,code,status,phase_id,subproject_id,assigned_to,revision,created_at,updated_at

## Reikwijdte
Alleen GET (en HTTP HEAD/OPTIONS) wordt ondersteund. POST, PATCH, PUT en DELETE
geven 405. Sleutels hebben alleen de bij aanmaken gekozen leescategorieën.
De API leest CRM-records, inclusief concepten en persoonsgegevens binnen die
categorieën. Verwijderde records zijn uitgesloten. Records uit andere projecten
worden nooit teruggegeven. Alleen bovengenoemde velden zijn beschikbaar;
gekoppelde collecties, volledige dossiers, bestanden en custom fields zijn
geen onderdeel van deze versie. Tekstvelden kunnen HTML bevatten: render veilig.
De API is voor server-to-server integraties; cross-origin browser-CORS is niet ingeschakeld.

## Limieten en fouten
Maximaal 120 geauthenticeerde verzoeken per minuut per sleutel. Bij 429:
wacht de Retry-After header (60 seconden) af. Responses worden niet gecachet.
Foutvorm: { "error": { "code": "unauthenticated", "message": "..." } }
- 400 invalid_input: ongeldige UUID of paginering/onbekende queryparameters.
- 401 unauthenticated: secret ontbreekt, is onjuist, verlopen of ingetrokken.
- 403 forbidden_project: afwijkende X-Project-Id.
- 403 insufficient_scope: categorie niet toegestaan voor deze sleutel.
- 404 not_found: resource/record bestaat niet of is niet beschikbaar in dit project.
- 405: HTTP-methode niet ondersteund (framework-response).
- 429 rate_limited: limiet bereikt; respecteer Retry-After.
- 503 unavailable: tijdelijk niet beschikbaar; herhaal met oplopende wachttijd.

## Roteren en intrekken
Maak een nieuwe sleutel aan, vervang het secret in de integratie, test
GET /api/v1/project en trek daarna de oude sleutel in via Instellingen > API.
Na intrekken worden volgende authenticatiepogingen geweigerd. Reeds lopende
verzoeken kunnen nog afronden. Sleutels zijn van het project en blijven geldig
als de maker het project verlaat, tot intrekking of de vervaldatum.

## Voorbeeld (curl)
Stel CONTACTPORTAAL_BASE_URL en CONTACTPORTAAL_API_KEY in via je omgeving.
curl "$CONTACTPORTAAL_BASE_URL/api/v1/project" -H "Authorization: Bearer $CONTACTPORTAAL_API_KEY"
curl "$CONTACTPORTAAL_BASE_URL/api/v1/records/stakeholders?limit=50&offset=0" -H "Authorization: Bearer $CONTACTPORTAAL_API_KEY"

## Overige API's
De member REST API /api/mobile/v1 gebruikt een Supabase-gebruikerstoken met de
rol member voor het bewonersportaal. /api/mcp gebruikt OAuth voor medewerkers.
Project-API-sleutels werken uitsluitend op /api/v1, niet op deze andere API's.
Publieke documentatie: /developers
OpenAPI 3.1: /api/docs/openapi.json
Deze complete tekst: /api/docs/guide