Developer Docs

REST API Documentation

Build integrations with Urbaneta. Automate invoicing, sync residents, read meter data, and more.

API Keys

Generate API keys in your account settings. Each key is scoped to your organization.

Bearer Auth

All endpoints require a valid Bearer token. Tokens expire in 15 minutes — use refresh tokens to stay authenticated.

Webhooks

Subscribe to events (invoice.created, payment.received, reading.submitted) with HMAC-signed payloads.

Base URL

https://testlnp.workizon.com/api

All requests must be made over HTTPS. Replace with your self-hosted instance URL if applicable.

Authentication

Include your access token in the Authorization header on every request.

# Tokens are short-lived. Use POST /auth/refresh with your refresh token to obtain a new access token automatically. Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Quick start

Three steps to your first API integration.

1. Authenticate and get your token

curl -X POST https://testlnp.workizon.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

# Response
{ "data": { "accessToken": "eyJ...", "refreshToken": "dGhp..." } }

2. List your buildings

curl https://testlnp.workizon.com/api/buildings \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. Generate invoices for a building

curl -X POST https://testlnp.workizon.com/api/invoices/generate-bulk \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildingId":"<uuid>","periodStart":"2025-01-01","periodEnd":"2025-01-31"}'

JavaScript / TypeScript example

No SDK required — the API uses standard REST. Here's a pattern for fetching invoices and recording a payment.

# Fetch unpaid invoices
curl "https://testlnp.workizon.com/api/invoices?buildingId=<uuid>&status=sent" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Mark invoice as paid
curl -X PATCH "https://testlnp.workizon.com/api/invoices/<invoice-id>" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid","paidDate":"2025-02-01"}'

Endpoint Reference

Authentication

POST/auth/loginLogin with email and password, returns access and refresh tokens

POST/auth/refreshRefresh an expired access token using a refresh token

POST/auth/logoutInvalidate the current session

POST/auth/magic-linkRequest a magic link login email

Buildings

GET/buildingsList all buildings for the authenticated tenant

POST/buildingsCreate a new building

GET/buildings/:idGet a single building by ID

PATCH/buildings/:idUpdate building settings (name, address, billing, etc.)

DELETE/buildings/:idDelete a building (requires password confirmation)

Apartments

GET/buildings/:id/apartmentsList apartments in a building

POST/buildings/:id/apartmentsCreate an apartment

PATCH/buildings/:id/apartments/:aptIdUpdate apartment details

DELETE/buildings/:id/apartments/:aptIdDelete an apartment

Invoices

GET/invoicesList invoices with filtering (status, building, date range)

GET/invoices/:idGet invoice details including line items

POST/invoices/generate-bulkGenerate invoices for a building and period

PATCH/invoices/:idUpdate invoice status, payment date, or reference

POST/invoices/send-bulkSend invoices by email to residents

GET/invoices/:id/pdfDownload invoice as PDF

Meters

GET/metersList meter definitions for a building

POST/metersCreate a new meter

POST/meters/:id/readingsSubmit a meter reading

POST/meters/ocrExtract a reading from a meter photo using AI OCR

Residents & Users

GET/residentsList residents linked to your buildings

POST/invitationsInvite a user to an apartment

GET/invitationsList pending invitations

DELETE/invitations/:idCancel an invitation

Payments

POST/payments/banklinkInitiate a Paysera / Maksekeskus banklink payment

GET/paymentsList recorded payments for your tenant

POST/bank-statements/importImport CSV/XML bank statement for auto-reconciliation

Webhooks

GET/webhooksList configured webhook endpoints

POST/webhooksCreate a webhook endpoint (URL + event types)

DELETE/webhooks/:idDelete a webhook endpoint

Webhook event types

Subscribe to any combination of these events when creating a webhook endpoint.

invoice.createdA new invoice was generated

invoice.sentInvoice was sent to the resident by email

invoice.paidInvoice marked as paid (manual or banklink)

invoice.overdueInvoice passed its due date unpaid

payment.receivedA payment was recorded against an invoice

reading.submittedA resident submitted a meter reading

reading.confirmedManager confirmed a meter reading

maintenance.createdA new maintenance request was submitted

maintenance.updatedMaintenance request status changed

Example payload

POST https://your-server.com/webhook X-Urbaneta-Signature: sha256=... { "event": "invoice.paid", "timestamp": "2025-02-01T10:30:00Z", "tenantId": "550e8400-e29b-41d4-a716-...", "data": { "invoiceId": "...", "amount": 142.50 } }

HTTP error codes

400Bad RequestInvalid request body or missing required fields

401UnauthorizedMissing or expired access token

403ForbiddenAuthenticated but insufficient permissions

404Not FoundResource not found or not accessible by your tenant

409ConflictDuplicate resource (e.g. apartment number already exists)

422UnprocessableValidation failed — check the errors array in the response

429Rate LimitedToo many requests — retry after the Retry-After header value

500Server ErrorUnexpected error — contact support if it persists

Ready to integrate?

Go to dashboard