Reporting API

1. Create a key

Only the office owner creates keys: Integrations → Reporting API → New key. Choose a name, the scopes and an expiry. The key (it starts with evak_) is shown once. Store it like a password. Revoke it any time and it stops at once.

2. Send the key

In the Authorization header, either way. Never put the key in the URL.

curl -H "Authorization: Bearer evak_YOUR_KEY" \
  "https://app.evacore.io/api/v1/leads?limit=100"

# Basic auth. Any user name, the key as the password (what Power BI uses):
curl -u "api:evak_YOUR_KEY" "https://app.evacore.io/api/v1/deals?updated_since=2026-10-01T00:00:00Z"

# CSV for Excel / Power BI. Every matching row in one response:
curl -u "api:evak_YOUR_KEY" "https://app.evacore.io/api/v1/properties?format=csv&fields=title,city,price,status" -o properties.csv

3. The response

UTF-8 JSON with Arabic text as-is. Times are UTC ISO 8601; SAR amounts are strings with two decimals ("1500000.00") so no precision is lost. An empty field is null.

{
  "object": "list",
  "resource": "leads",
  "data": [
    {
      "id": "0e7b6a52-3c55-4a8e-b0a4-7c4d1f2e9a31",
      "name": "محمد العتيبي",
      "phone": "+966501234567",
      "status": "جديد",
      "budget": "1500000.00",
      "created_at": "2026-10-01T09:15:01.902Z",
      "updated_at": "2026-10-03T12:40:22.118Z"
    }
  ],
  "has_more": true,
  "next_cursor": "WyIyMDI2LTEwLTAzVDEyOjQwOjIyLjExODQ1MVoiLCIwZTdi…",
  "next": "/api/v1/leads?limit=100&cursor=WyIyMDI2…"
}

A page has 100 rows by default and up to 1000 with limit. Pick columns with fields (comma-separated; id is always included). format=csv returns every row in one response, field names on the first line.

4. Incremental sync

1. Rows come oldest change first. Fetch the first page, then pass next_cursor as cursor until has_more is false.
2. Keep the last next_cursor. Next sync, send it and you get only what was created or changed after it. Every row comes whole, so upsert by id.
3. Or use updated_since with your last sync time minus 5 minutes (to cover changes that commit late) and upsert by id.
4. Deleted rows are not reported incrementally: do a full pull now and then (weekly, say).

5. Connect Power BI

1. Power BI Desktop → Get data → Web.
2. Paste a table's CSV URL, e.g. https://app.evacore.io/api/v1/leads?format=csv
3. In the sign-in dialog choose Basic: any user name (e.g. api) and the key as the password. Apply it to https://app.evacore.io so every table uses the key.
4. If the Arabic looks garbled: in the preview set File origin = 65001: Unicode (UTF-8).
5. Repeat Web for each table you need (deals, properties, projects, units, reservations, activities, tasks, agents, teams) and relate them on the *_id fields.
6. After publishing to the Power BI Service: Settings → Data source credentials → Basic with the same key, then turn on Scheduled refresh.

Excel works the same way: Data → From Web → the same URL → Basic.

Writes and retries

Use POST /api/v1/leads or POST /api/v1/properties to create; PATCH the same path with /{id} to update. Requires leads:write or properties:write; read never grants writes. Update a lead's status or assign a sales user in the same office, or update a property's details and status. See OpenAPI for allowed fields and values.

Send JSON with a unique Idempotency-Key per operation (1 to 128 printable ASCII characters). Retrying the same request and key returns the original response without repeating the mutation. A changed body or path returns 409. Retry 503 with the same key. Project-linked property status uses the reservation workflow; resolve active shared lead assignments in the office first.

Owners see daily counts per key for the last 30 Riyadh days on the API keys page. Every authenticated read, write, replay or refusal counts once. All share a 120/minute budget; CSV costs 10 budget units and counts as one request.

6. Limits and errors

Every error has the shape: { "error": { "code": "…", "message": "…" } }. Writes require a separate scope and an Idempotency-Key.

7. Tables and fields

The full OpenAPI 3.1 specification: https://app.evacore.io/api/v1/openapi.json