OpenAPI Reference

SealMetrics API v1.0

First-party, cookie-free analytics API for accurate marketing attribution and conversion tracking.

Download OpenAPI Spec

Get API Access

---

What's Included

The SealMetrics OpenAPI specification provides machine-readable documentation for all API endpoints:

Category	Endpoints	Description
Authentication	/auth/login, /auth/accounts	Obtain tokens and list accounts
Pages	/report/pages	Page view analytics and traffic data
Conversions	/report/conversions	Conversion events with attribution
Microconversions	/report/microconversions	Pre-conversion engagement events
Funnel	/report/funnel	Conversion funnel analysis
ROAS	/report/roas-evolution	Return on Ad Spend over time
Offline	/auth/v1.0/set-click	Record offline conversions

---

Quick Start

1. Download the Specification

# Download via curl
curl -O https://docs.sealmetrics.com/openapi.yaml

# Or wget
wget https://docs.sealmetrics.com/openapi.yaml

2. Import into Your Tools

The OpenAPI spec works with popular API tools:

Postman

Import → OpenAPI

Insomnia

Import/Export → Import

Swagger UI

Explore → URL

OpenAPI Generator

Generate SDKs

3. Generate Client SDKs

Use OpenAPI Generator to create client libraries:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate Python client
openapi-generator-cli generate -i openapi.yaml -g python -o ./sealmetrics-python

# Generate JavaScript/TypeScript client
openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./sealmetrics-ts

# Generate PHP client
openapi-generator-cli generate -i openapi.yaml -g php -o ./sealmetrics-php

---

API Overview

Base URL

https://app.sealmetrics.com/api/

Authentication

All endpoints (except /auth/login) require a Bearer token:

curl -X POST https://app.sealmetrics.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_at": "2024-12-31T23:59:59Z"
}

Use the token in subsequent requests:

curl https://app.sealmetrics.com/api/auth/accounts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Rate Limits

Tier	Requests/min	Records/request	Throughput
Standard	60	10,000	600K records/min
Enterprise	120	10,000	1.2M records/min

Rate limit headers are included in every response:

• X-RateLimit-Limit - Max requests per window
• X-RateLimit-Remaining - Remaining requests
• X-RateLimit-Reset - Unix timestamp when limit resets

---

Endpoint Reference

Authentication

POST /auth/login

Authenticate and receive a Bearer token.

curl -X POST https://app.sealmetrics.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

GET /auth/accounts

List all accounts linked to your credentials.

curl https://app.sealmetrics.com/api/auth/accounts \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Analytics Endpoints

GET /report/pages

Retrieve page view analytics.

Parameter	Type	Required	Description
account_id	string	Yes	Account identifier
date_range	string	Yes	Date range (e.g., 20241101,20241130 or last_30_days)
limit	integer	No	Max 10,000 (default: 1,000)
skip	integer	No	Pagination offset
country	string	No	ISO country code (e.g., US)
utm_source	string	No	Filter by source
utm_medium	string	No	Filter by medium
utm_campaign	string	No	Filter by campaign
show_utms	boolean	No	Include UTM data in response

curl "https://app.sealmetrics.com/api/report/pages?account_id=YOUR_ID&date_range=last_30_days&limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

GET /report/conversions

Retrieve conversion events with full attribution.

Parameter	Type	Required	Description
account_id	string	Yes	Account identifier
date_range	string	Yes	Date range
limit	integer	No	Max 100 (default: 100)
skip	integer	No	Pagination offset
country	string	No	ISO country code
utm_source	string	No	Filter by source
utm_medium	string	No	Filter by medium
utm_campaign	string	No	Filter by campaign

curl "https://app.sealmetrics.com/api/report/conversions?account_id=YOUR_ID&date_range=last_7_days" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "ok",
  "data": [
    {
      "_id": "conv_abc123",
      "amount": 149.99,
      "utm_medium": "cpc",
      "utm_source": "google",
      "utm_campaign": "black-friday",
      "country": "US",
      "country_name": "United States",
      "date": "2024-11-29",
      "label": "purchase"
    }
  ]
}

---

GET /report/microconversions

Retrieve pre-conversion engagement events.

curl "https://app.sealmetrics.com/api/report/microconversions?account_id=YOUR_ID&date_range=last_30_days" \
  -H "Authorization: Bearer YOUR_TOKEN"

Common labels: add-to-cart, checkout, newsletter-signup, form-submit

---

GET /report/funnel

Analyze conversion funnel by traffic source.

Parameter	Type	Required	Description
account_id	string	Yes	Account identifier
date_range	string	Yes	Date range
report_type	string	Yes	Source, Medium, or Campaign

curl "https://app.sealmetrics.com/api/report/funnel?account_id=YOUR_ID&date_range=last_30_days&report_type=Source" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

GET /report/roas-evolution

Track ROAS metrics over time.

Parameter	Type	Required	Description
account_id	string	Yes	Account identifier
date_range	string	Yes	Date range
time_unit	string	No	daily, weekly, or monthly

curl "https://app.sealmetrics.com/api/report/roas-evolution?account_id=YOUR_ID&date_range=last_30_days&time_unit=daily" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

POST /auth/v1.0/set-click

Record offline conversions (phone calls, CRM events).

curl -X POST https://app.sealmetrics.com/api/auth/v1.0/set-click \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'account_id=YOUR_ID' \
  -d 'url_parameters={"utm_medium":"cpc","utm_source":"google","utm_campaign":"calls"}' \
  -d 'click_time=1701234567890' \
  -d 'settings={"email":"customer@example.com"}'

---

Date Range Options

Value	Description
YYYYMMDD,YYYYMMDD	Custom range (e.g., 20241101,20241130)
today	Current day
yesterday	Previous day
last_7_days	Past 7 days
last_14_days	Past 14 days
last_30_days	Past 30 days
last_60_days	Past 60 days
last_90_days	Past 90 days
this_week_monday_sunday	Current week (Mon-Sun)
this_week_sunday_saturday	Current week (Sun-Sat)
this_month	Current month
last_month	Previous month
this_year	Current year
last_year	Previous year

---

Error Handling

All errors follow a consistent format:

{
  "status": "error",
  "message": "Human-readable error description"
}

Status Code	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
403	Forbidden - Insufficient permissions
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limit Error

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded.",
    "details": {
      "limit": 60,
      "window": "1 minute",
      "retry_after": 60
    }
  }
}

---

Need Help?

Implementation Guide

Step-by-step examples in Python, JavaScript, and more.

Rate Limits

Best practices for handling rate limits and pagination.

Troubleshooting

Common issues and how to resolve them.

---

Questions? Contact us at support@sealmetrics.com