Docs/Developer/API Reference

API Reference

Marginly API endpoints, authentication, and integration options for developers building on top of Marginly data.

Overview

The Marginly API is available on Business plans. It allows you to programmatically access your deal appraisal data, project information, and budget data — for integration with your own systems, custom reporting, or automation workflows.

Authentication

The API uses API key authentication. Generate your API key from Account Settings → API → Generate Key. Keep your API key secure — treat it like a password.

Include your API key in all requests as a header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://api.marginly.co.uk/v1

Endpoints

Scenarios (Deal Appraisals)

List scenarios

GET /scenarios

Returns all deal scenarios in your account.

Response:
[
  {
    "id": "sc_abc123",
    "name": "4 Birch Lane",
    "createdAt": "2025-03-15T10:30:00Z",
    "updatedAt": "2025-04-01T14:22:00Z",
    "purchasePrice": 280000,
    "gdv": 450000,
    "grossProfit": 68400,
    "marginOnGdv": 15.2
  }
]

Get scenario

GET /scenarios/:id

Returns the full scenario data including all inputs and calculated results.

Create scenario

POST /scenarios

Create a new deal scenario. Supply the scenario inputs as a JSON body.

Update scenario

PATCH /scenarios/:id

Update an existing scenario. Supply only the fields you want to change.

Delete scenario

DELETE /scenarios/:id

Projects

List projects

GET /projects

Returns all projects in your account.

Get project budget summary

GET /projects/:id/budget

Returns budget vs. actuals by category for the project.

List invoices

GET /projects/:id/invoices

Returns all logged invoices for the project.

Rate limits

API requests are limited to 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response. The response headers include X-RateLimit-Remaining and X-RateLimit-Reset to help you manage your request rate.

Webhooks

Webhooks allow Marginly to notify your application when events occur — for example, when a deal appraisal is updated, a new invoice is added, or a project milestone is completed. Configure webhook endpoints from Account Settings → API → Webhooks.

SDKs

Official SDKs are planned for JavaScript/TypeScript and Python. In the meantime, the REST API can be accessed using any HTTP client. Get in touch if you need help building an integration — we're happy to support developers building on top of Marginly.

Team Access