Advanced API integration

Metrikia REST API: automate everything

The Metrikia API gives you full programmatic access to your advertising and CRM data. Whether you want to automate your weekly reports, connect an unsupported CRM, or feed your own BI tool, the API is your gateway.

Base URL

The API is accessible at: https://api.metrikia.io/api/v1/

Interactive documentation (OpenAPI/Swagger) is available at: https://api.metrikia.io/api/v1/docs

Authentication

All requests must include an Authorization header:

Authorization: Bearer YOUR_API_KEY

Create and manage your API keys from Settings > API Keys. You can create read-only keys (recommended for dashboards and reports) or read-write keys (for creating leads and deals).

Pro tip: Create one API key per application or service. If a key is compromised, you can revoke it without impacting other integrations.

Exchange format

• Requests: JSON (Content-Type: application/json)
• Responses: JSON-LD (standard JSON compatible)
• Pagination: cursor-based (page and itemsPerPage parameters)
• Errors: Problem Details format (RFC 7807)
• Versioning: /api/v1/ prefix, breaking changes are versioned

Main endpoints

Leads

GET /api/v1/leads : Paginated list of your CRM leads

Query parameters:

• status: filter by status (new, contacted, qualified, proposal, won, lost)
• source: filter by source (meta, google, tiktok, organic, referral)
• page: page number (default: 1)
• itemsPerPage: items per page (default: 30, max: 100)
• order[createdAt]: sort by date (asc or desc)

POST /api/v1/leads : Create a lead

Body:

• firstName (required): First name
• lastName (required): Last name
• email: Email (used for matching and deduplication)
• phone: Phone (E.164 format recommended)
• source: Ad source (meta, google, tiktok, etc.)
• notes: Free text notes

PATCH /api/v1/leads/{id} : Partial update

Deals

GET /api/v1/deals : List of deals with pagination and status filters

POST /api/v1/deals : Create a deal linked to a lead

Body:

• leadId (required): Associated lead ID
• title (required): Deal title
• amount: Amount (in cents)
• status: open, won, lost

Campaigns

GET /api/v1/campaigns : List of campaigns synced from ad platforms. Read-only (campaigns are created via ad platforms).

Performance

GET /api/v1/performance : Aggregated metrics

Parameters:

• dateFrom: Start date (YYYY-MM-DD format)
• dateTo: End date
• platform: meta, google, tiktok, or all
• groupBy: day, week, month

Returns: spend, impressions, clicks, leads, revenue, CPL, CPA, ROAS.

Concrete use cases

1. Automated weekly reporting

Create a script that fetches data every Monday morning and sends it by email or Slack:

1. Call GET /api/v1/performance?dateFrom=LAST_MONDAY&dateTo=SUNDAY&platform=all&groupBy=day
2. Call GET /api/v1/leads?status=won&order[createdAt]=desc&itemsPerPage=100 for new customers
3. Generate your report (PDF, email, Slack, Google Sheets...)
4. Schedule execution via cron, Zapier, Make, or n8n

2. Custom CRM sync

If your CRM is not directly supported by Metrikia:

1. Configure an outgoing webhook from your CRM ("new lead" and "deal won" events)
2. Create a middleware (Zapier, Make, n8n, or a script) that transforms the payload
3. Call POST /api/v1/leads to create the lead in Metrikia with source fields
4. The lead is automatically attributed and metrics updated

3. Custom BI dashboard

Integrate Metrikia data into Power BI, Looker, or Google Data Studio:

1. Create a read-only API key
2. Use GET /api/v1/performance to feed your charts
3. Refresh data at regular intervals (once/hour recommended)
4. Combine with your other data sources for a unified dashboard

4. Custom alerts

Create a script that checks your KPIs daily:

1. Call GET /api/v1/performance for the day's metrics
2. Compare ROAS to your profitability threshold
3. If ROAS < threshold, send a Slack/email alert
4. Add checks for CPL, lead volume, etc.

Rate Limiting

When exceeded, the API returns a 429 code with a Retry-After header indicating the number of seconds to wait.

Best practices

1. Cache results: Performance data only changes after each sync (every hour), no need to query every second
2. Use pagination: Do not fetch all leads at once, use itemsPerPage=30 and paginate
3. Handle errors: Implement retry with exponential backoff (1s, 2s, 4s, 8s, max 60s)
4. Separate keys: One key per application/service, revoke independently
5. Read-only when possible: Reduce the attack surface of your integrations
6. Webhooks > Polling: For real-time events, use webhooks rather than API polling