Network & Insider Analytics

Understand how your Network

The Network & Insider Analytics API helps you understand your referral network dynamics and optimize your insider program performance through comprehensive network analysis and behavioral insights.

What is the Network & Insider Analytics API?

The Network & Insider Analytics API is like having a detailed map of your customer relationships. It gives you deep insights into how your insiders connect, share, and influence each other's purchasing behavior. This lets you identify your most valuable network nodes, track referral patterns, and optimize your insider program for maximum growth.

Why is Network & Insider Analytics useful?

Network analytics bridges individual customer data with relationship intelligence, helping businesses scale their referral programs while understanding true network value.

Marketing Teams: Identify top influencers and track campaign spread through networks, then target high-converting connection paths.
Finance Teams: Calculate true customer lifetime value including network effects, improving ROI forecasts and insider reward allocation.
Product Teams: Understand sharing patterns and connection behaviors to optimize referral flows and user experience.

The API works continuously in the background, tracking connections, analyzing sharing patterns, and measuring network performance metrics.

How does it work?

The API provides real-time access to your complete network structure through three main capabilities: full network dumps, incremental updates, and deep insider analysis. You can track everything from individual insider profiles to multi-degree network relationships.

What It Tracks: Network connections, sharing behavior, conversion rates, and relationship strength across your entire insider ecosystem.
Example: See that Sarah has a 73% connection weight with Mike, who then connects to 12 other high-value customers, creating a network worth $15K+ in generated revenue.
Access Patterns: Full dumps for analysis, incremental updates for real-time monitoring, and targeted queries for specific insights.

Team	Benefit	Example
Marketing	Network amplification	"Target Sarah's network - her connections have 68% higher conversion rates"
Finance	True value calculation	"This insider's network generated $12K beyond their personal purchases"
Product	Optimization insights	"Users share most on Instagram (92% strength) vs Twitter (65%)"

Error Responses

All endpoints can return the following HTTP status codes and error responses:

Authentication & Authorization Errors

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key.",
    "details": "string"
  },
  "meta": {}
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this resource.",
    "details": "string"
  },
  "meta": {}
}

Client Errors

400 Bad Request

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters.",
    "details": "string",
    "validation_errors": [
      {
        "field": "string",
        "message": "string"
      }
    ]
  },
  "meta": {}
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Insider not found or does not exist.",
    "details": "string"
  },
  "meta": {}
}

409 Conflict

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Request conflicts with current resource state.",
    "details": "string"
  },
  "meta": {}
}

422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": "string",
    "validation_errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string"
      }
    ]
  },
  "meta": {}
}

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after some time.",
    "details": "string",
    "retry_after": "number (seconds)"
  },
  "meta": {}
}

Server Errors

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred. Please try again later.",
    "details": "string",
    "request_id": "string"
  },
  "meta": {}
}

502 Bad Gateway

{
  "success": false,
  "error": {
    "code": "BAD_GATEWAY",
    "message": "Upstream service unavailable.",
    "details": "string"
  },
  "meta": {}
}

503 Service Unavailable

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable. Please retry later.",
    "details": "string",
    "retry_after": "number (seconds)"
  },
  "meta": {}
}

504 Gateway Timeout

{
  "success": false,
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "Request timeout. Please try again.",
    "details": "string"
  },
  "meta": {}
}

API Endpoints

Network Dump Endpoints

Full Network Dump

GET /api/v1/networks/dump
GET /api/v1/networks/dump?limit=100&sortBy=joined_date&sortOrder=desc&lastId=12345&lastValue=2025-02-03T14:17:00Z

Get a complete snapshot of your network structure with all insider connections and relationship weights.

Parameters:

limit (optional): 1-1000, default 100
sortBy (optional): joined_date, network_id, default joined_date
sortOrder (optional): asc, desc, default desc
lastId (optional): Last record ID for pagination
lastValue (optional): Last sort field value for pagination

Success Response (200 OK):

{
  "success": "boolean",
  "data": {
    "network_id": "string",
    "snapshot_date": "ISO 8601 timestamp",
    "insiders": {
      "UUID": {
        "joined_date": "ISO 8601 timestamp",
        "connections": [
          {
            "target": "UUID",
            "weight": "number (0.0-1.0)"
          }
        ]
      }
    }
  },
  "message": "string",
  "pagination": {
    "hasNext": "boolean",
    "hasPrevious": "boolean",
    "nextKeyset": {
      "id": "number",
      "value": "ISO 8601 timestamp"
    },
    "previousKeyset": "object or null",
    "count": "number",
    "sortBy": "string",
    "sortOrder": "string"
  },
  "meta": "object"
}

Specific Error Cases:

400: Invalid limit value (must be 1-1000)
400: Invalid sortBy parameter
400: Invalid sortOrder parameter
400: Invalid lastValue format

Network Updates Since Date

GET /api/v1/networks/updates/since/{timestamp}
GET /api/v1/networks/updates/since/2025-07-15T00:00:00Z?limit=50&cursor=eyJsaW1pdCI6NTAsInNvcnRfYnkiOiJ0aW1lc3RhbXAifQ==

Track incremental changes to your network since a specific timestamp for real-time monitoring.

Parameters:

limit (optional): Number of updates per page (default: 50, max: 200)
cursor (optional): Cursor for navigation through updates

Success Response (200 OK):

{
  "success": "boolean",
  "data": {
    "since": "ISO 8601 timestamp",
    "generated_at": "ISO 8601 timestamp",
    "updates": [
      {
        "insider_id": "UUID",
        "update_type": "string",
        "joined_date": "ISO 8601 timestamp",
        "updated_at": "ISO 8601 timestamp",
        "connections": [
          {
            "target": "UUID",
            "weight": "number (0.0-1.0)",
            "change_type": "string"
          }
        ]
      }
    ]
  },
  "message": "string",
  "pagination": {
    "hasNext": "boolean",
    "hasPrevious": "boolean",
    "nextCursor": "string or null",
    "previousCursor": "string or null",
    "count": "number"
  },
  "meta": "object"
}

Specific Error Cases:

400: Invalid timestamp format in URL path
400: Invalid limit value (must be 1-200)
400: Invalid cursor format
422: Timestamp too far in the past (beyond data retention)

Insider Analysis Endpoints

Insider Profile & Achievements

GET /api/v1/insiders/{insider_id}
GET /api/v1/insiders/a1b2c3d4-e5f6-7890-1234-567890abcdef

Get comprehensive profile data including purchase history, sharing performance, and network metrics for a specific insider.

Success Response (200 OK):

{
  "success": "boolean",
  "data": {
    "insider_id": "UUID",
    "joined_date": "ISO 8601 timestamp",
    "time_updated": "ISO 8601 timestamp",
    "profile": {
      "instances_purchased": [
        {
          "instance_id": "string",
          "timestamp": "ISO 8601 timestamp",
          "campaign_id": "string",
          "time_updated": "ISO 8601 timestamp"
        }
      ],
      "instances_shared": [
        {
          "instance_id": "string",
          "shares": "number",
          "platforms": ["string"],
          "shared_with": ["UUID or string"],
          "signup": ["UUID"],
          "time_updated": "ISO 8601 timestamp"
        }
      ],
      "conversion_rate": "number (0.0-1.0)",
      "conversion_rate_updated": "ISO 8601 timestamp",
      "total_shares": "number",
      "shares_updated": "ISO 8601 timestamp",
      "user_value": "number",
      "value_updated": "ISO 8601 timestamp",
      "total_purchase_amount": "number",
      "purchase_amount_updated": "ISO 8601 timestamp",
      "total_generated_amount": "number",
      "generated_amount_updated": "ISO 8601 timestamp",
      "network_size": {
        "first_degree": "number",
        "second_degree": "number",
        "third_degree": "number",
        "time_updated": "ISO 8601 timestamp"
      }
    }
  },
  "message": "string",
  "meta": "object"
}

Specific Error Cases:

400: Invalid UUID format for insider_id
404: Insider not found
403: Insufficient permissions to view this insider's data

Insider Network Analysis

GET /api/v1/insiders/{insider_id}/network?degree=1
GET /api/v1/insiders/{insider_id}/network?degree=2&activitiesLimit=50&since=2025-07-15T00:00:00Z

Analyze connection relationships and performance metrics at different network degrees (1st, 2nd, 3rd degree connections).

Parameters:

degree (required): Connection degree (1, 2, or 3)
activitiesLimit (optional): Number of activity entries (default: 50, max: 200)
activitiesToken (optional): Token for paginating activities
since (optional): Show updates since this timestamp

Success Response (200 OK) for degree=1:

{
  "success": "boolean",
  "data": {
    "insider_id": "UUID",
    "time_updated": "ISO 8601 timestamp",
    "degree": "number",
    "network_analysis": {
      "partner_activity": {
        "last_shared_with_partner": {
          "timestamp": "ISO 8601 timestamp",
          "partner_id": "string",
          "instance_id": "string",
          "time_updated": "ISO 8601 timestamp"
        },
        "last_shared_across_network": {
          "timestamp": "ISO 8601 timestamp",
          "summary": "string",
          "order_id": "string",
          "reach": "number",
          "time_updated": "ISO 8601 timestamp"
        },
        "cross_partner_conversion_rate": "number (0.0-1.0)",
        "cross_partner_updated": "ISO 8601 timestamp"
      },
      "connections": [
        {
          "insider_id": "UUID",
          "signup_status": "string",
          "platform_strengths": {
            "instagram": "number (0.0-1.0)",
            "tiktok": "number (0.0-1.0)",
            "twitter": "number (0.0-1.0)",
            "facebook": "number (0.0-1.0)"
          },
          "performance_metrics": {
            "partner_conversion_rate": "number (0.0-1.0)",
            "total_generated": "number",
            "conversion_rate_updated": "ISO 8601 timestamp"
          },
          "last_shared": {
            "partner": {
              "timestamp": "ISO 8601 timestamp",
              "instance_id": "string"
            },
            "other_partners": {
              "data": [
                {
                  "timestamp": "ISO 8601 timestamp",
                  "order_summary": "string",
                  "campaign_summary": "string",
                  "behavior_summary": "string",
                  "approximate_spending": "number"
                }
              ],
              "pagination": {
                "hasNext": "boolean",
                "hasPrevious": "boolean",
                "nextToken": "string or null",
                "previousToken": "string or null",
                "count": "number",
                "sortBy": "string",
                "sortOrder": "string"
              }
            }
          },
          "time_updated": "ISO 8601 timestamp"
        }
      ]
    }
  },
  "message": "string",
  "meta": "object"
}

Success Response (200 OK) for degree=2:

{
  "success": "boolean",
  "data": {
    "insider_id": "UUID",
    "time_updated": "ISO 8601 timestamp",
    "degree": "number",
    "network_analysis": {
      "connections": [
        {
          "insider_id": "UUID",
          "signup_status": "string",
          "connecting_through": "UUID",
          "platform_strengths": {
            "instagram": "number (0.0-1.0)",
            "facebook": "number (0.0-1.0)"
          },
          "performance_metrics": {
            "partner_conversion_rate": "number (0.0-1.0)",
            "total_generated": "number",
            "conversion_rate_updated": "ISO 8601 timestamp"
          },
          "last_shared": {
            "partner": {
              "timestamp": "ISO 8601 timestamp",
              "instance_id": "string"
            },
            "other_partners": {
              "data": [
                {
                  "timestamp": "ISO 8601 timestamp",
                  "order_summary": "string",
                  "campaign_summary": "string",
                  "behavior_summary": "string",
                  "approximate_spending": "number"
                }
              ],
              "pagination": {
                "hasNext": "boolean",
                "hasPrevious": "boolean",
                "nextToken": "string or null",
                "previousToken": "string or null",
                "count": "number",
                "sortBy": "string",
                "sortOrder": "string"
              }
            }
          },
          "time_updated": "ISO 8601 timestamp"
        }
      ]
    }
  },
  "message": "string",
  "meta": "object"
}

Specific Error Cases:

400: Invalid UUID format for insider_id
400: Invalid degree parameter (must be 1, 2, or 3)
400: Invalid activitiesLimit value (must be 1-200)
400: Invalid since timestamp format
400: Invalid activitiesToken format
404: Insider not found
403: Insufficient permissions to view network analysis
422: Network analysis not available for this insider

Insider Purchase Behavior

GET /api/v1/insiders/{insider_id}/behavior
GET /api/v1/insiders/{insider_id}/behavior?limit=50&store_filter=all&since=2025-07-15T00:00:00Z

Track detailed purchase patterns and behavior analytics for individual insiders across all connected stores.

Parameters:

limit (optional): Number of purchase entries (default: 50, max: 200)
sortBy (optional): Sort field (timestamp, store_name, etc.) - default: timestamp
sortOrder (optional): Sort direction (asc, desc) - default: desc
lastId (optional): Last record ID for keyset pagination
lastValue (optional): Last sort field value for keyset pagination
store_filter (optional): Filter for current partner store or all stores (default: all)
since (optional): Show purchases since this timestamp

Success Response (200 OK):

{
  "success": "boolean",
  "data": {
    "insider_id": "UUID",
    "time_updated": "ISO 8601 timestamp",
    "store_filter": "string",
    "purchase_behavior": {
      "data": [
        {
          "timestamp": "ISO 8601 timestamp",
          "store_name": "string",
          "store_category": "string",
          "instance_id": "string",
          "order_summary": "string",
          "campaign_summary": "string",
          "behavior_summary": "string",
          "spending_range": "string"
        }
      ],
      "pagination": {
        "hasNext": "boolean",
        "hasPrevious": "boolean",
        "nextKeyset": {
          "id": "number",
          "value": "ISO 8601 timestamp"
        },
        "previousKeyset": "object or null",
        "count": "number",
        "sortBy": "string",
        "sortOrder": "string"
      },
      "summary_stats": {
        "total_purchases": "number",
        "current_partner_purchases": "number",
        "other_partner_purchases": "number",
        "total_approximate_spending": "string",
        "avg_spending_per_purchase": "string",
        "most_active_period": "string",
        "purchase_frequency": "string"
      }
    }
  },
  "message": "string",
  "meta": "object"
}

Specific Error Cases:

400: Invalid UUID format for insider_id
400: Invalid limit value (must be 1-200)
400: Invalid sortBy parameter
400: Invalid sortOrder parameter
400: Invalid store_filter parameter
400: Invalid since timestamp format
400: Invalid lastId or lastValue for pagination
404: Insider not found
403: Insufficient permissions to view purchase behaviorHow Network Authentication Works

When users access your platform through insider referral links, our system automatically maps their network relationships using device fingerprinting and referral tracking. This happens seamlessly in the background, enabling you to immediately understand their network position and connection strength without requiring additional authentication steps.

Anonymous Network Mapping: See basic connection data and referral source without sign-in requirements.
Authenticated Network Boost: Full network analysis with detailed relationship metrics and cross-platform activity tracking.
Example: Anonymous user shows as "connected through Sarah" with basic metrics; after authentication, you see their complete 3-degree network with $15K+ influence potential.

Network & Insider Analytics

What is the Network & Insider Analytics API? Copied

Why is Network & Insider Analytics useful? Copied

How does it work? Copied

Error Responses Copied

Authentication & Authorization Errors Copied

Client Errors Copied

Server Errors Copied

API Endpoints Copied

Network Dump Endpoints Copied

Full Network Dump

Network Updates Since Date

Insider Analysis Endpoints Copied

Insider Profile & Achievements

Insider Network Analysis

Insider Purchase Behavior

What is the Network & Insider Analytics API?

Why is Network & Insider Analytics useful?

How does it work?

Error Responses

Authentication & Authorization Errors

Client Errors

Server Errors

API Endpoints

Network Dump Endpoints

Insider Analysis Endpoints