Skip to main content
The Snitcher REST API allows you to programmatically access and manage your Snitcher data. Use it to build custom integrations, automate workflows, or sync data with your other business tools.

​
Authentication

All API requests require authentication using a Personal Access Token (PAT) passed as a Bearer token.

​
Generate an API Token

  1. Go to your Snitcher Dashboard
  2. Navigate to Settings > Account > API
  3. Click Generate New Token
  4. Copy and securely store your token
Treat your API token like a password. Never expose it in client-side code or public repositories.

​
Making Authenticated Requests

Include your token in the Authorization header: 
curl -X GET 'https://api.snitcher.com/v1/workspaces' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

​
Base URL

All API endpoints use this base URL: 
https://api.snitcher.com/v1

​
Rate Limits

To ensure fair usage and platform stability, the REST API enforces the following rate limits:
  • 60 requests per minute (per API token)
When you exceed the rate limit, the API returns: 
{
  "message": "Too Many Attempts."
}
Status Code: 429 Too Many Requests
Implement exponential backoff in your application to handle rate limiting gracefully. Start with a 1-second delay, then double it on each retry.
Need higher rate limits? Contact support to discuss your requirements.

​
Response Format

All responses are JSON. Successful responses include the requested data: 
{
  "data": {
    // Response data
  }
}
Error responses include a message: 
{
  "message": "Error description",
  "errors": {
    "field": ["Validation error"]
  }
}

​
Common HTTP Status Codes

StatusDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
422Validation Error - Check errors object
429Rate Limited - Too many requests
500Server Error - Contact support

​
Available Endpoints

The REST API provides access to:

Workspaces

List, create, and manage your workspaces

Organisations

Access identified companies and their data

Sessions

Retrieve visitor session data

Contacts

Access contacts and reveal emails or phone numbers

Segments

List and manage segments

Tags

Create and manage company tags

​
Example: List Workspaces

curl -X GET 'https://api.snitcher.com/v1/workspaces' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'
Response: 
{
  "data": [
    {
      "uuid": "ws_abc123",
      "name": "My Website",
      "url": "https://example.com",
      "status": "active"
    }
  ]
}

​
Example: Get Sessions with Events

Sessions now include an events array containing all tracking events (pageviews, form submissions, custom events, clicks, and downloads). The views array is deprecated and only contains pageviews. 
curl -X GET 'https://api.snitcher.com/v1/workspaces/{workspaceUuid}/organisations/{organisationUuid}/sessions?date=2025-03-01' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'
Response (abbreviated): 
{
  "data": [
    {
      "uuid": "...",
      "organisation_uuid": "...",
      "started_at": "2025-03-01T10:00:00+00:00",
      "ended_at": "2025-03-01T10:05:00+00:00",
      "events": [
        {
          "event_type": "pageview",
          "url": "https://acme.com/pricing",
          "triggered_at": "2025-03-01T10:00:00+00:00",
          "time_on_page": 45
        },
        {
          "event_type": "form_submit",
          "url": "https://acme.com/contact",
          "triggered_at": "2025-03-01T10:02:00+00:00",
          "form_id": "contact-form",
          "form_name": "Contact Form",
          "fields": [
            { "name": "email", "value": "j@acme.com" }
          ]
        },
        {
          "event_type": "track",
          "url": "https://acme.com/pricing",
          "triggered_at": "2025-03-01T10:03:00+00:00",
          "name": "plan_selected",
          "properties": [
            { "name": "plan", "value": "enterprise" }
          ]
        },
        {
          "event_type": "click",
          "url": "https://acme.com/page",
          "triggered_at": "2025-03-01T10:04:00+00:00",
          "name": "CTA Button",
          "properties": [
            { "name": "elementText", "value": "Get Started" }
          ]
        },
        {
          "event_type": "download",
          "url": "https://acme.com/whitepaper.pdf",
          "triggered_at": "2025-03-01T10:05:00+00:00",
          "name": "$download",
          "properties": [
            { "name": "url", "value": "https://acme.com/whitepaper.pdf" }
          ]
        }
      ],
      "views": [
        {
          "url": "https://acme.com/pricing",
          "visited_at": "2025-03-01T10:00:00+00:00",
          "time_on_page": 45
        }
      ]
    }
  ]
}
Each event has a common event_type, url, and triggered_at field. Additional fields depend on the event type:
Event TypeAdditional Fields
pageviewtime_on_page
form_submitform_id, form_name, fields
trackname, properties
clickname, properties
downloadname, properties

​
Example: Get Organisations

curl -X GET 'https://api.snitcher.com/v1/workspaces/{workspaceUuid}/organisations' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

​
Pagination

List endpoints support pagination using query parameters:
ParameterTypeDefaultDescription
pageinteger1Page number
per_pageinteger25Items per page (max 100)
curl -X GET 'https://api.snitcher.com/v1/workspaces/{workspaceUuid}/organisations?page=2&per_page=50' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

​
Filtering & Searching

Many endpoints support filtering. Use the POST method with a JSON body for advanced searches: 
curl -X POST 'https://api.snitcher.com/v1/workspaces/{workspaceUuid}/organisations' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "filters": {
      "industry": "Software",
      "size": ["51-200 employees", "201-500 employees"]
    }
  }'

​
SDK & Libraries

While we don’t provide official SDK libraries, the REST API is straightforward to use with any HTTP client:
  • JavaScript/Node.js: fetch, axios
  • Python: requests, httpx
  • PHP: Guzzle, cURL
  • Ruby: HTTParty, Faraday

​
Best Practices

  1. Store tokens securely: Use environment variables, not hardcoded values
  2. Handle rate limits: Implement retry logic with exponential backoff
  3. Cache responses: Reduce API calls by caching data locally when appropriate
  4. Use pagination: Don’t try to fetch all data in one request
  5. Monitor usage: Track your API usage to stay within limits

​
Need Help?

API Reference

Browse the full API documentation

Support

Contact our support team