{"openapi":"3.1.0","info":{"title":"SDEP - Listing Screening Authority (LSA) API","description":"Endpoints for the listing screening authority to retrieve submitted listings and to submit screening results (random checks), and to view platforms, competent authorities and areas. Status: alpha.","contact":{"name":"Nationaal Coordinator SDEP","url":"https://minvro.nl/","email":"nationaalcoordinatorsdep@minbzk.nl"},"version":"1.10.0"},"paths":{"/listings":{"get":{"tags":["lsa"],"summary":"Get the submitted listings awaiting screening, across all platforms","description":"Get the current listings that platforms submitted for screening and that are not yet screened (fixed scope: `status` is `pending`, `flags` empty, `screenedAt` null), across all platforms. Submit the screening results with `POST /listing-screenings/bulk`. Returns at most 1000 listings per request (the default and maximum `limit`). Use the `offset` and `limit` pagination parameters to page through results. Optional filters use AND semantics: every provided filter narrows the result set. The `createdAtFrom` and `createdAtTo` form an inclusive `createdAt` range; the other filters are exact-match, except `flags` which matches any of the given codes. Use `areaId`, `platformId` and `competentAuthorityId` to group the work by area, platform and/or competent authority.\n\n**Each listing contains:**\n- `listingId`: Functional ID identifying this listing\n- `listingName`: Display name (optional) of the listing\n- `status`: Lifecycle status: `pending`, `clear`, `flagged` or `acknowledged`\n- `flags`: Flag codes raised by the screening (`ABS`, `UNK`, `EXP`, `MIS`, `NPR`, `UNX`, `UDS`); empty until screened\n- `areaId`: Functional ID referencing the area where the listing is posted\n- `areaName`: Display name (optional) of the area\n- `competentAuthorityId`: Functional ID referencing the competent authority that owns the area\n- `competentAuthorityName`: Display name (optional) of the competent authority\n- `url`: URL referencing the listing online\n- `address`: Address composite (`thoroughfare`, `locatorDesignatorNumber` (optional), `locatorDesignatorLetter` (optional), `locatorDesignatorAddition` (optional), `postCode`, `postName`, `fullAddress`)\n- `declaredAsShortTermRental`: Host self-declaration\n- `registrationNumber`: Registration number shown on the listing (optional)\n- `submittedAt`: Timestamp of the platform's submission (UTC)\n- `screenedAt`: Timestamp of the screening (UTC, null until screened)\n- `acknowledgedAt`: Timestamp of the acknowledgement (UTC, null until acknowledged)\n- `platformId`: Functional ID referencing the platform that submitted the listing\n- `platformName`: Display name (optional) of the platform\n- `createdAt`: Timestamp when this listing version was created (UTC); the version token for screening and acknowledgement","operationId":"getListingsForScreening","security":[{"OAuth2ClientCredentials":[]}],"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip (default: 0)","default":0,"title":"Offset"},"description":"Number of records to skip (default: 0)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of records to return (default: 1000, max: 1000)","default":1000,"title":"Limit"},"description":"Maximum number of records to return (default: 1000, max: 1000)"},{"name":"createdAtFrom","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter listings whose createdAt timestamp is greater than or equal to this UTC value","examples":["2026-09-01T00:00:00Z"],"title":"Createdatfrom"},"description":"Filter listings whose createdAt timestamp is greater than or equal to this UTC value"},{"name":"createdAtTo","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter listings whose createdAt timestamp is less than or equal to this UTC value","examples":["2026-09-30T23:59:59Z"],"title":"Createdatto"},"description":"Filter listings whose createdAt timestamp is less than or equal to this UTC value"},{"name":"areaId","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9-]+$"},{"type":"null"}],"description":"Filter by area functional ID","examples":["58ff0814-3aa1-5019-9afb-3cd9f398602c"],"title":"Areaid"},"description":"Filter by area functional ID"},{"name":"competentAuthorityId","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9-]+$"},{"type":"null"}],"description":"Filter by competent authority functional ID","examples":["c4ac8ccf-a281-5789-bad7-28dfac20ca7f"],"title":"Competentauthorityid"},"description":"Filter by competent authority functional ID"},{"name":"platformId","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9-]+$"},{"type":"null"}],"description":"Filter by platform functional ID","examples":["8e70f1e2-4c61-477b-89b8-0dbf25ab8b21"],"title":"Platformid"},"description":"Filter by platform functional ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingListResponse"},"example":{"listings":[{"listingId":"550e8400-e29b-41d4-a716-446655440000","listingName":"Amsterdam Canal Apartment","status":"pending","flags":[],"areaId":"58ff0814-3aa1-5019-9afb-3cd9f398602c","areaName":"Amsterdam","competentAuthorityId":"c4ac8ccf-a281-5789-bad7-28dfac20ca7f","competentAuthorityName":"Amsterdam (inclusief Weesp)","url":"http://example.com/amsterdam-canal-apartment","address":{"thoroughfare":"Prinsengracht","locatorDesignatorNumber":263,"postCode":"1016GV","postName":"Amsterdam","fullAddress":"Prinsengracht 263, 1016GV Amsterdam"},"declaredAsShortTermRental":true,"registrationNumber":"REG0001","submittedAt":"2026-09-07T08:00:00Z","platformId":"8e70f1e2-4c61-477b-89b8-0dbf25ab8b21","platformName":"Test STR 01","createdAt":"2026-09-07T08:00:00Z"}]}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}}}},"/listings/count":{"get":{"tags":["lsa"],"summary":"Get the count of listings awaiting screening (optional, to support pagination)","description":"Get the count of the current listings awaiting screening, across all platforms (optional, to support pagination). Optional filters use AND semantics: every provided filter narrows the result set. The `createdAtFrom` and `createdAtTo` form an inclusive `createdAt` range; the other filters are exact-match, except `flags` which matches any of the given codes.","operationId":"countListingsForScreening","security":[{"OAuth2ClientCredentials":[]}],"parameters":[{"name":"createdAtFrom","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter listings whose createdAt timestamp is greater than or equal to this UTC value","examples":["2026-09-01T00:00:00Z"],"title":"Createdatfrom"},"description":"Filter listings whose createdAt timestamp is greater than or equal to this UTC value"},{"name":"createdAtTo","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter listings whose createdAt timestamp is less than or equal to this UTC value","examples":["2026-09-30T23:59:59Z"],"title":"Createdatto"},"description":"Filter listings whose createdAt timestamp is less than or equal to this UTC value"},{"name":"areaId","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9-]+$"},{"type":"null"}],"description":"Filter by area functional ID","examples":["58ff0814-3aa1-5019-9afb-3cd9f398602c"],"title":"Areaid"},"description":"Filter by area functional ID"},{"name":"competentAuthorityId","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9-]+$"},{"type":"null"}],"description":"Filter by competent authority functional ID","examples":["c4ac8ccf-a281-5789-bad7-28dfac20ca7f"],"title":"Competentauthorityid"},"description":"Filter by competent authority functional ID"},{"name":"platformId","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9-]+$"},{"type":"null"}],"description":"Filter by platform functional ID","examples":["8e70f1e2-4c61-477b-89b8-0dbf25ab8b21"],"title":"Platformid"},"description":"Filter by platform functional ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingCountResponse"}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}}}},"/listing-screenings/bulk":{"post":{"tags":["lsa"],"summary":"Submit screening results in bulk","description":"Submit 1-1000 screening results. Each screened listing becomes a new version: `clear` when `flags` is empty, `flagged` otherwise. Flagged listings appear in the platform's `GET /listings` for acknowledgement.\n\n**Flag codes:** `ABS` (absent registration number), `UNK` (unknown registration number), `EXP` (expired registration number), `MIS` (mismatched address), `NPR` (not a private residence), `UNX` (unexpected registration number), `UDS` (undeclared short-term rental). See the functional design for the decision table.\n\n**Correction:** a `clear` or `flagged` listing may be re-screened (new version, state follows the new flags). An `acknowledged` listing is final: such items are marked NOK with `conflict_error`.\n\n**Concurrency:**\n- `platformId` and `listingId` identify the listing (a `listingId` is only unique within a platform)\n- `createdAt` is the `createdAt` of the version that was screened, as returned by `GET /listings`\n- When that version is no longer current (for example, the platform corrected the listing), the item is marked NOK with `conflict_error` and `loc` `[\"createdAt\"]`; the corrected listing reappears in `GET /listings` with its new data\n\n**Validation flow (4 steps):**\n\n1. **Syntax and semantical validation** - each item is validated individually (`platformId`, `listingId`, UTC `createdAt`, known flag codes).\n2. **Referential Integrity Check** - the platform and the listing must exist (`not_found_error`).\n3. **Versioning and Bulk Insert** - the current version is locked and checked (`createdAt` current, status not `acknowledged`), marked ended, and the screened versions are inserted in a single multi-row INSERT.\n4. **Feedback** - per-item OK/NOK response preserving original order.\n\n**Intra-batch duplicates (last-wins):**\nWhen the same (`platformId`, `listingId`) appears multiple times in a single batch, only the last\noccurrence is processed. Earlier occurrences receive NOK.\n\n**The request contains:**\n- `screenings`: Array of screening results to process (1-1000 items per batch)\n\n**Each screening item in the request contains:**\n- `platformId`: Functional ID of the platform that submitted the listing\n- `listingId`: Functional ID of the screened listing\n- `createdAt`: `createdAt` of the screened listing version (UTC)\n- `flags`: Zero or more distinct flag codes\n\n**The response contains:**\n- `totalReceived`, `succeeded`, `failed`: Summary counts\n- `results`: Per-item results preserving the original request order (`listingIndex`, `listingId`, `status`, `listing` for OK items, `errors` for NOK items)\n\n**Response HTTP status:**\n- 201: all items screened\n- 200: partial success (some OK, some NOK)\n- 401: missing or invalid token\n- 403: insufficient permissions\n- 409: a concurrent request wrote the same record first (`conflict_error`), retry the request\n- 422: all items failed","operationId":"postListingScreeningsBulk","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingScreeningBulkRequest"},"example":{"screenings":[{"platformId":"8e70f1e2-4c61-477b-89b8-0dbf25ab8b21","listingId":"550e8400-e29b-41d4-a716-446655440000","createdAt":"2026-09-07T08:00:00Z","flags":["UNK"]},{"platformId":"8e70f1e2-4c61-477b-89b8-0dbf25ab8b21","listingId":"1d1a7f0c-2b4e-4a63-9c0f-7c1e5b2a9d10","createdAt":"2026-09-07T08:00:00Z","flags":[]}]}}},"required":true},"responses":{"201":{"description":"All screening results processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingScreeningBulkResponse"},"example":{"totalReceived":2,"succeeded":2,"failed":0,"results":[{"listingIndex":0,"listingId":"550e8400-e29b-41d4-a716-446655440000","status":"OK","listing":{"listingId":"550e8400-e29b-41d4-a716-446655440000","listingName":"Amsterdam Canal Apartment","status":"flagged","flags":["UNK"],"areaId":"58ff0814-3aa1-5019-9afb-3cd9f398602c","areaName":"Amsterdam","competentAuthorityId":"c4ac8ccf-a281-5789-bad7-28dfac20ca7f","competentAuthorityName":"Amsterdam (inclusief Weesp)","url":"http://example.com/amsterdam-canal-apartment","address":{"thoroughfare":"Prinsengracht","locatorDesignatorNumber":263,"postCode":"1016GV","postName":"Amsterdam","fullAddress":"Prinsengracht 263, 1016GV Amsterdam"},"declaredAsShortTermRental":true,"registrationNumber":"REG0001","submittedAt":"2026-09-07T08:00:00Z","screenedAt":"2026-09-08T06:00:00Z","platformId":"8e70f1e2-4c61-477b-89b8-0dbf25ab8b21","platformName":"Test STR 01","createdAt":"2026-09-08T06:00:00Z"}},{"listingIndex":1,"listingId":"1d1a7f0c-2b4e-4a63-9c0f-7c1e5b2a9d10","status":"OK","listing":{"listingId":"1d1a7f0c-2b4e-4a63-9c0f-7c1e5b2a9d10","listingName":"Amsterdam Canal Apartment","status":"clear","flags":[],"areaId":"58ff0814-3aa1-5019-9afb-3cd9f398602c","areaName":"Amsterdam","competentAuthorityId":"c4ac8ccf-a281-5789-bad7-28dfac20ca7f","competentAuthorityName":"Amsterdam (inclusief Weesp)","url":"http://example.com/amsterdam-canal-apartment","address":{"thoroughfare":"Prinsengracht","locatorDesignatorNumber":263,"postCode":"1016GV","postName":"Amsterdam","fullAddress":"Prinsengracht 263, 1016GV Amsterdam"},"declaredAsShortTermRental":true,"registrationNumber":"REG0001","submittedAt":"2026-09-07T08:00:00Z","screenedAt":"2026-09-08T06:00:00Z","platformId":"8e70f1e2-4c61-477b-89b8-0dbf25ab8b21","platformName":"Test STR 01","createdAt":"2026-09-08T06:00:00Z"}}]}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"200":{"description":"Partial success - some screening results processed, some failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingScreeningBulkResponse"},"example":{"totalReceived":3,"succeeded":1,"failed":2,"results":[{"listingIndex":0,"listingId":"550e8400-e29b-41d4-a716-446655440000","status":"OK","listing":{"listingId":"550e8400-e29b-41d4-a716-446655440000","listingName":"Amsterdam Canal Apartment","status":"flagged","flags":["UNK"],"areaId":"58ff0814-3aa1-5019-9afb-3cd9f398602c","areaName":"Amsterdam","competentAuthorityId":"c4ac8ccf-a281-5789-bad7-28dfac20ca7f","competentAuthorityName":"Amsterdam (inclusief Weesp)","url":"http://example.com/amsterdam-canal-apartment","address":{"thoroughfare":"Prinsengracht","locatorDesignatorNumber":263,"postCode":"1016GV","postName":"Amsterdam","fullAddress":"Prinsengracht 263, 1016GV Amsterdam"},"declaredAsShortTermRental":true,"registrationNumber":"REG0001","submittedAt":"2026-09-07T08:00:00Z","screenedAt":"2026-09-08T06:00:00Z","platformId":"8e70f1e2-4c61-477b-89b8-0dbf25ab8b21","platformName":"Test STR 01","createdAt":"2026-09-08T06:00:00Z"}},{"listingIndex":1,"listingId":"abc-123","status":"NOK","errors":{"detail":[{"msg":"Listing 'abc-123' version '2026-09-07T08:00:00Z' is no longer current","type":"conflict_error","loc":["createdAt"]}]}},{"listingIndex":2,"listingId":"def-456","status":"NOK","errors":{"detail":[{"msg":"Input should be 'ABS', 'UNK', 'EXP', 'MIS', 'NPR', 'UNX' or 'UDS'","type":"enum","loc":["flags","0"]}]}}]}}}},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"},"409":{"description":"Conflict - a concurrent request wrote the same record first (`conflict_error`), retry the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"All screening results failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingScreeningBulkResponse"},"example":{"totalReceived":1,"succeeded":0,"failed":1,"results":[{"listingIndex":0,"listingId":"abc-123","status":"NOK","errors":{"detail":[{"msg":"Platform with platformId 'unknown-platform' not found","type":"not_found_error","loc":["platformId"]}]}}]}}}}},"security":[{"OAuth2ClientCredentials":[]}]}},"/platforms":{"get":{"tags":["lsa"],"summary":"Get all platforms","description":"Get all current platforms. Returns at most 1000 records per request (the default and maximum `limit`). Use the `offset` and `limit` pagination parameters to page through results, and the `/count` endpoint for the total. Use `platformId` as the `platformId` filter of the activity and listing reads.\n\n**Each platform contains:**\n- `platformId`: Functional ID identifying this platform\n- `platformName`: Display name (optional) of the platform\n- `createdAt`: Timestamp when this platform version was created (UTC)","operationId":"getPlatforms","security":[{"OAuth2ClientCredentials":[]}],"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip (default: 0)","default":0,"title":"Offset"},"description":"Number of records to skip (default: 0)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of records to return (default: 1000, max: 1000)","default":1000,"title":"Limit"},"description":"Maximum number of records to return (default: 1000, max: 1000)"}],"responses":{"200":{"description":"List of platforms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformListResponse"},"example":{"platforms":[{"platformId":"8e70f1e2-4c61-477b-89b8-0dbf25ab8b21","platformName":"Test STR 01","createdAt":"2025-01-01T00:00:00Z"}]}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}}}},"/platforms/count":{"get":{"tags":["lsa"],"summary":"Get platforms count (optional, to support pagination)","description":"Get platforms count (optional, to support pagination)","operationId":"countPlatforms","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformCountResponse"}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}},"security":[{"OAuth2ClientCredentials":[]}]}},"/competent-authorities":{"get":{"tags":["lsa"],"summary":"Get all competent authorities","description":"Get all current competent authorities. Returns at most 1000 records per request (the default and maximum `limit`). Use the `offset` and `limit` pagination parameters to page through results, and the `/count` endpoint for the total. Use `competentAuthorityId` as the `competentAuthorityId` filter of the activity and listing reads.\n\n**Each competent authority contains:**\n- `competentAuthorityId`: Functional ID identifying this competent authority\n- `competentAuthorityName`: Display name (optional) of the competent authority\n- `createdAt`: Timestamp when this competent authority version was created (UTC)","operationId":"getCompetentAuthorities","security":[{"OAuth2ClientCredentials":[]}],"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip (default: 0)","default":0,"title":"Offset"},"description":"Number of records to skip (default: 0)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of records to return (default: 1000, max: 1000)","default":1000,"title":"Limit"},"description":"Maximum number of records to return (default: 1000, max: 1000)"}],"responses":{"200":{"description":"List of competent authorities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetentAuthorityListResponse"},"example":{"competentAuthorities":[{"competentAuthorityId":"c4ac8ccf-a281-5789-bad7-28dfac20ca7f","competentAuthorityName":"Amsterdam (inclusief Weesp)","createdAt":"2025-01-01T00:00:00Z"}]}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}}}},"/competent-authorities/count":{"get":{"tags":["lsa"],"summary":"Get competent authorities count (optional, to support pagination)","description":"Get competent authorities count (optional, to support pagination)","operationId":"countCompetentAuthorities","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetentAuthorityCountResponse"}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}},"security":[{"OAuth2ClientCredentials":[]}]}},"/areas":{"get":{"tags":["lsa"],"summary":"Get all areas","description":"Get all areas, maximum 1000 per page. `limit` defaults to 1000 (the maximum); use `offset` and `limit` to page through the result set, and `GET /areas/count` for the total.\n\n**Each area contains:**\n- `areaId`: Functional ID identifying this area\n- `areaName`: Display name (optional) of the area\n- `regulation`: Regulation type of the area - 'listing', 'activity', or 'all'\n- `filename`: Name of the area shapefile (e.g., 'area.zip')\n- `competentAuthorityId`: Functional ID referencing the competent authority that owns the area\n- `competentAuthorityName`: Display name (optional) of the competent authority\n- `createdAt`: Timestamp when this area version was created (UTC)","operationId":"getAreas","security":[{"OAuth2ClientCredentials":[]}],"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip (default: 0)","default":0,"title":"Offset"},"description":"Number of records to skip (default: 0)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of records to return (default: 1000, max: 1000)","default":1000,"title":"Limit"},"description":"Maximum number of records to return (default: 1000, max: 1000)"}],"responses":{"200":{"description":"List of areas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AreaListResponse"},"example":{"areas":[{"areaId":"58ff0814-3aa1-5019-9afb-3cd9f398602c","areaName":"Amsterdam","regulation":"all","filename":"Amsterdam.zip","competentAuthorityId":"c4ac8ccf-a281-5789-bad7-28dfac20ca7f","competentAuthorityName":"Amsterdam (inclusief Weesp)","createdAt":"2025-01-01T00:00:00Z"},{"areaId":"974e2c23-b666-5044-a05c-9479a4c293a1","areaName":"Rotterdam","regulation":"all","filename":"Rotterdam.zip","competentAuthorityId":"a30df3a7-7e38-534c-b9c0-7666bad077d2","competentAuthorityName":"Rotterdam","createdAt":"2025-01-01T00:00:00Z"}]}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}}}},"/areas/count":{"get":{"tags":["lsa"],"summary":"Get areas count (optional, to support pagination)","description":"Get areas count (optional, to support pagination).","operationId":"countAreas","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AreaCountResponse"}}}},"500":{"description":"Internal Server Error - an unexpected issue occurred that prevented the request from being completed"},"503":{"description":"Service Unavailable - temporarily unable to process requests due to overload, maintenance, or dependency issues (database/authorization server)"},"401":{"description":"Unauthorized - missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions"}},"security":[{"OAuth2ClientCredentials":[]}]}}},"components":{"schemas":{"AreaCountResponse":{"properties":{"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of areas in context of the current SDEP/member state","examples":[42]}},"type":"object","required":["count"],"title":"Area.CountResponse","description":"Count of areas response schema."},"AreaListResponse":{"properties":{"areas":{"items":{"$ref":"#/components/schemas/AreaResponse"},"type":"array","title":"Areas","description":"List of areas in context of the current SDEP/member state"}},"type":"object","required":["areas"],"title":"Area.ListResponse","description":"List of areas response schema."},"AreaResponse":{"properties":{"areaId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Areaid","description":"Functional ID identifying this area","examples":["58ff0814-3aa1-5019-9afb-3cd9f398602c"]},"areaName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Areaname","description":"Display name (optional) of the area","examples":["Amsterdam"]},"regulation":{"$ref":"#/components/schemas/Regulation","description":"Regulation type of the area - 'listing', 'activity', or 'all'","default":"all","examples":["all"]},"filename":{"type":"string","maxLength":64,"title":"Filename","description":"Name of the area shapefile (e.g., 'area.zip')","examples":["Amsterdam.zip"]},"competentAuthorityId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Competentauthorityid","description":"Functional ID of the competent authority that owns the area","examples":["c4ac8ccf-a281-5789-bad7-28dfac20ca7f"]},"competentAuthorityName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Competentauthorityname","description":"Display name (optional) of the competent authority","examples":["Amsterdam (inclusief Weesp)"]},"createdAt":{"type":"string","format":"date-time","title":"Createdat","description":"Timestamp when this area version was created (UTC)","examples":["2025-01-01T00:00:00Z"]}},"type":"object","required":["areaId","filename","competentAuthorityId","createdAt"],"title":"Area.Response","description":"Area response schema."},"CommonAddressResponse":{"properties":{"thoroughfare":{"type":"string","maxLength":80,"title":"Thoroughfare","description":"Street / public space name (max 80 chars)"},"locatorDesignatorNumber":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Locatordesignatornumber","description":"Numeric house number component (optional, >= 0 when provided)"},"locatorDesignatorLetter":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Locatordesignatorletter","description":"Letter/character suffix (optional, max 10 chars)"},"locatorDesignatorAddition":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Locatordesignatoraddition","description":"Additional qualifier (optional, max 128 chars)"},"postCode":{"type":"string","maxLength":10,"title":"Postcode","description":"Postal code (max 10 chars)"},"postName":{"type":"string","maxLength":80,"title":"Postname","description":"City / town / village (max 80 chars)"},"fullAddress":{"type":"string","maxLength":328,"title":"Fulladdress","description":"Full address as a single string (max 328 chars)"}},"type":"object","required":["thoroughfare","postCode","postName","fullAddress"],"title":"Common.AddressResponse","description":"Address composite schema for activity responses (INSPIRE/STR-AP field names)."},"Regulation":{"type":"string","enum":["listing","activity","all"],"title":"Common.Regulation","description":"Regulation type for an area: 'listing', 'activity', or 'all' (covers both)."},"CompetentAuthorityCountResponse":{"properties":{"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of competent authorities in context of the current SDEP/member state","examples":[42]}},"type":"object","required":["count"],"title":"CompetentAuthority.CountResponse","description":"Count of competent authorities response schema."},"CompetentAuthorityListResponse":{"properties":{"competentAuthorities":{"items":{"$ref":"#/components/schemas/CompetentAuthorityResponse"},"type":"array","title":"Competentauthorities","description":"List of competent authorities in context of the current SDEP/member state"}},"type":"object","required":["competentAuthorities"],"title":"CompetentAuthority.ListResponse","description":"List of competent authorities response schema."},"CompetentAuthorityResponse":{"properties":{"competentAuthorityId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Competentauthorityid","description":"Functional ID identifying this competent authority","examples":["c4ac8ccf-a281-5789-bad7-28dfac20ca7f"]},"competentAuthorityName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Competentauthorityname","description":"Display name (optional) of the competent authority","examples":["Amsterdam (inclusief Weesp)"]},"createdAt":{"type":"string","format":"date-time","title":"Createdat","description":"Timestamp when this competent authority version was created (UTC)","examples":["2025-01-01T00:00:00Z"]}},"type":"object","required":["competentAuthorityId","createdAt"],"title":"CompetentAuthority.Response","description":"Competent authority response schema. The private client_id is never exposed."},"ErrorDetail":{"properties":{"msg":{"type":"string","title":"Msg","description":"Human-readable error message"},"type":{"type":"string","title":"Type","description":"Error type identifier"},"loc":{"anyOf":[{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array"},{"type":"null"}],"title":"Loc","description":"Location of the error (e.g. ['body', 'fieldName'])"}},"type":"object","required":["msg","type"],"title":"Error.Detail","description":"Detail of a single error."},"ErrorResponse":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array","title":"Detail","description":"List of error details"}},"type":"object","required":["detail"],"title":"Error.Response","description":"Standardized error response format."},"ListingCountResponse":{"properties":{"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of listing records","examples":[42]}},"type":"object","required":["count"],"title":"Listing.CountResponse","description":"Count of listings response schema."},"ListingFlag":{"type":"string","enum":["ABS","UNK","EXP","MIS","NPR","UNX","UDS"],"title":"Listing.Flag","description":"Flag code raised by listing screening, see docs/LISTING_FUNC.md."},"ListingListResponse":{"properties":{"listings":{"items":{"$ref":"#/components/schemas/ListingResponse"},"type":"array","title":"Listings","description":"List of listings"}},"type":"object","required":["listings"],"title":"Listing.ListResponse","description":"List of listings for GET responses."},"ListingResponse":{"properties":{"listingId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Listingid","description":"Functional ID identifying this listing","examples":["550e8400-e29b-41d4-a716-446655440000"]},"listingName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Listingname","description":"Display name (optional) of the listing"},"status":{"$ref":"#/components/schemas/ListingStatus","description":"Lifecycle status: `pending`, `clear`, `flagged` or `acknowledged`","examples":["flagged"]},"flags":{"items":{"$ref":"#/components/schemas/ListingFlag"},"type":"array","title":"Flags","description":"Flag codes raised by the screening (empty until screened; non-empty when `flagged` or `acknowledged`)","examples":[["UNK"]]},"areaId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Areaid","description":"Functional ID referencing the area where the listing is posted (case-sensitive)","examples":["58ff0814-3aa1-5019-9afb-3cd9f398602c"]},"areaName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Areaname","description":"Display name (optional) of the area"},"competentAuthorityId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Competentauthorityid","description":"Functional ID referencing the competent authority that owns the area","examples":["c4ac8ccf-a281-5789-bad7-28dfac20ca7f"]},"competentAuthorityName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Competentauthorityname","description":"Display name (optional) of the competent authority"},"url":{"type":"string","maxLength":2048,"title":"Url","description":"URL referencing the listing online (max 2048 chars)"},"address":{"$ref":"#/components/schemas/CommonAddressResponse","description":"Address composite (`thoroughfare`, `locatorDesignatorNumber` (optional), `locatorDesignatorLetter` (optional), `locatorDesignatorAddition` (optional), `postCode`, `postName`, `fullAddress`)"},"declaredAsShortTermRental":{"type":"boolean","title":"Declaredasshorttermrental","description":"Host self-declaration: `true` when the host declared the listing as a short-term rental"},"registrationNumber":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Registrationnumber","description":"Registration number shown on the listing (optional, max 128 chars)"},"submittedAt":{"type":"string","format":"date-time","title":"Submittedat","description":"Timestamp of the platform's submission (UTC); unchanged by screening and acknowledgement"},"screenedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Screenedat","description":"Timestamp of the screening (UTC); null until screened"},"acknowledgedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Acknowledgedat","description":"Timestamp of the acknowledgement (UTC); null until acknowledged"},"platformId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Platformid","description":"Functional ID referencing the platform that submitted the listing","examples":["8e70f1e2-4c61-477b-89b8-0dbf25ab8b21"]},"platformName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Platformname","description":"Display name (optional) of the platform"},"createdAt":{"type":"string","format":"date-time","title":"Createdat","description":"Timestamp when this listing version was created (UTC); the version token for screening and acknowledgement"}},"type":"object","required":["listingId","status","flags","areaId","competentAuthorityId","url","address","declaredAsShortTermRental","submittedAt","platformId","createdAt"],"title":"Listing.Response","description":"Listing response schema, the same for every audience."},"ListingStatus":{"type":"string","enum":["pending","clear","flagged","acknowledged"],"title":"Listing.Status","description":"Lifecycle status for a listing (random check) record."},"ListingScreeningBulkRequest":{"properties":{"screenings":{"items":{"$ref":"#/components/schemas/ListingScreeningRequest"},"type":"array","maxItems":1000,"minItems":1,"title":"Screenings","description":"Array of screening results to process (1-1000 items per batch)"}},"type":"object","required":["screenings"],"title":"ListingScreening.BulkRequest","description":"Bulk screening request schema (`POST /listing-screenings/bulk`)."},"ListingScreeningBulkResponse":{"properties":{"totalReceived":{"type":"integer","minimum":0.0,"title":"Totalreceived","description":"Total number of items received in the request","examples":[2]},"succeeded":{"type":"integer","minimum":0.0,"title":"Succeeded","description":"Number of items successfully processed (status OK)","examples":[2]},"failed":{"type":"integer","minimum":0.0,"title":"Failed","description":"Number of items that failed validation or processing (status NOK)","examples":[0]},"results":{"items":{"$ref":"#/components/schemas/ListingScreeningBulkResultItem"},"type":"array","title":"Results","description":"Per-item results preserving the original request order"}},"type":"object","required":["totalReceived","succeeded","failed","results"],"title":"ListingScreening.BulkResponse","description":"Bulk screening response schema."},"ListingScreeningBulkResultItem":{"properties":{"listingIndex":{"type":"integer","minimum":0.0,"title":"Listingindex","description":"Zero-based index of this item in the original request list","examples":[0]},"listingId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Listingid","description":"As supplied in the request item, or `null` when it is missing or not a string","examples":["550e8400-e29b-41d4-a716-446655440000"]},"status":{"type":"string","enum":["OK","NOK"],"title":"Status","description":"Processing result - `OK` (new listing version created) or `NOK` (failed validation or processing)","examples":["OK"]},"listing":{"anyOf":[{"$ref":"#/components/schemas/ListingResponse"},{"type":"null"}],"description":"The listing as it now is (present for OK items, omitted for NOK items)"},"errors":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"null"}],"description":"Structured error details (present for NOK items, omitted for OK items)","examples":[{"detail":[{"loc":["createdAt"],"msg":"Listing 'abc-123' version '2026-09-07T08:00:00Z' is no longer current","type":"conflict_error"}]}]}},"type":"object","required":["listingIndex","status"],"title":"ListingScreening.BulkResultItem","description":"Result for a single item in a screening bulk response."},"ListingScreeningRequest":{"properties":{"platformId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Platformid","description":"Functional ID of the platform that submitted the listing","examples":["8e70f1e2-4c61-477b-89b8-0dbf25ab8b21"]},"listingId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Listingid","description":"Functional ID of the screened listing","examples":["550e8400-e29b-41d4-a716-446655440000"]},"createdAt":{"type":"string","format":"date-time","title":"Createdat","description":"`createdAt` of the listing version that was screened (UTC); refused with `conflict_error` when that version is no longer current","examples":["2026-09-07T08:00:00Z"]},"flags":{"items":{"$ref":"#/components/schemas/ListingFlag"},"type":"array","maxItems":7,"title":"Flags","description":"Flag codes raised by the screening; empty means `clear`, non-empty means `flagged`","examples":[["UNK"],[]]}},"type":"object","required":["platformId","listingId","createdAt","flags"],"title":"ListingScreening.Request","description":"Screening result for one listing, submitted by the listing screening authority."},"PlatformCountResponse":{"properties":{"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of platforms in context of the current SDEP/member state","examples":[12]}},"type":"object","required":["count"],"title":"Platform.CountResponse","description":"Count of platforms response schema."},"PlatformListResponse":{"properties":{"platforms":{"items":{"$ref":"#/components/schemas/PlatformResponse"},"type":"array","title":"Platforms","description":"List of platforms in context of the current SDEP/member state"}},"type":"object","required":["platforms"],"title":"Platform.ListResponse","description":"List of platforms response schema."},"PlatformResponse":{"properties":{"platformId":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","title":"Platformid","description":"Functional ID identifying this platform","examples":["8e70f1e2-4c61-477b-89b8-0dbf25ab8b21"]},"platformName":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Platformname","description":"Display name (optional) of the platform","examples":["Example.com"]},"createdAt":{"type":"string","format":"date-time","title":"Createdat","description":"Timestamp when this platform version was created (UTC)","examples":["2025-01-01T00:00:00Z"]}},"type":"object","required":["platformId","createdAt"],"title":"Platform.Response","description":"Platform response schema. The private client_id is never exposed."}},"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{},"tokenUrl":"https://pre-sdep.minvro.nl/api/auth/v1/token"}}}}},"servers":[{"url":"/api/lsa/v2"}]}