Skip to main content
On this page

First API call

This walkthrough guides you through executing your first successful API request against etg24. You only need one prerequisite: an API key.

1. Create an API key

API keys are created directly in the etg24 app. Generate a dedicated key for your integration or agent and store it securely — the secret token is displayed only once. Key management, scope assignments, and actor bindings are explained in Key lifecycle.

2. Send your first request

The Property Management v2 API is hosted at https://api.etg24.de/propertymanagement/v2. Authenticate every request with an HTTP header: Authorization: Bearer <API_KEY>.

The following cURL command retrieves a paginated list of contacts in your portal — a safe, read-only query:

Terminal window
curl -s "https://api.etg24.de/propertymanagement/v2/query/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

The server responds with a JSON payload containing pagination metadata and an array of contact records:

{
  "pagination": { "total": 12, "limit": 50, "offset": 0 },
  "contacts": [
    {
      "id": "c1f7a28e-49b1-4f16-83b6-123456789abc",
      "firstName": "Erika",
      "lastName": "Mustermann",
      "email": "erika.mustermann@example.com"
    }
  ]
}

3. Understand the API architecture

Every endpoint follows a strict CQRS convention: operations either query data or execute state-changing commands. This split is directly reflected in the URL path:

GET  /propertymanagement/v2/query/contacts          Retrieve a list of contacts
GET  /propertymanagement/v2/query/contacts.show     Retrieve a specific contact by ID
POST /propertymanagement/v2/command/contacts.create Create a new contact

This predictable design aligns directly with the tools exposed by our MCP server: queries are safe and retryable, while commands are auditable state modifications. Learn more in CQRS.

4. Explore the interactive reference

The complete, interactive API documentation is generated directly from live OpenAPI specifications: explore Property Management v2. For ready-to-run client implementations in Python and Node.js, consult our code snippets.

Troubleshooting initial requests

  • 401 Unauthorized — The API key is missing, invalid, or has been disabled. Verify the Authorization header format (Bearer <KEY>) and key state in the portal settings.
  • 400 Bad Request — State-changing command endpoints require a valid JSON request body with Content-Type: application/json.
  • 403 Forbidden — The API key lacks the required capability scope (e.g. attempting to run a command with a read-only key).