Salespanel

API Documentation

RESTful API v1

Introduction

API Endpoint: https://salespanel.io/api/v1/

Salespanel's REST API gives you structured access to first-party GTM data: visitors, leads, visiting companies, activities, attribution, segments, and webhooks.

Use it to enrich internal tools, sync customer context into your stack, or give automation and agentic workflows reliable visitor, account, and journey data.

For a product overview and example workflows, see the Salespanel REST API landing page.

Authentication

Salespanel uses API tokens to allow access to the API. You can find your token on API token page in your dashboard, which you can access by logging in or signing up.

Salespanel expects for the API token to be included in all API requests to the server in a header that looks like the following:

Authorization: Token <API_TOKEN>

Example Request

curl "https://salespanel.io/api/v1/visitors/" \
  -H "Authorization: Token <API_TOKEN>"

Make sure to replace <API_TOKEN> with your API token.

API Token is required with every call to any Salespanel API endpoint. Do not share your API token with any third party.

Errors

The Salespanel API uses the following error codes:

Example Error Response

curl -i "https://salespanel.io/api/v1/visitors/"
HTTP/1.0 401 Unauthorized
Date: Wed, 11 Sep 2019 16:20:22 GMT
Content-Length: 58
Content-Type: application/json
WWW-Authenticate: Token

{"detail":"Authentication credentials were not provided."}
Code Title Description
400 Bad Request Your request is invalid.
401 Unauthorized Your API key is wrong.
403 Forbidden You do not have authorization to access the resource requested.
404 Not Found The requested resource could not be found.
405 Method Not Allowed You tried to access a resource with an invalid method.
406 Not Acceptable You requested a format that isn't json.
429 Too Many Requests Too many requests hit the API too quickly. See Rate Limits for throttle details and retry guidance.
50X Internal Server Error We had a problem with our server. Try again later.

Errors return both an appropriate HTTP status code and response object which contains a detail attribute.

Rate Limits

Salespanel applies throttling to REST API requests to keep the API stable for all users. The API uses both short-window burst throttling and longer-window sustained throttling.

Throttle Default Limit Description
Burst 60/minute Protects the API from too many requests in a short period.
Sustained 5000/day Protects the API from high request volume over a longer period.

Note: Your account may have custom REST API throttle settings. If you need higher limits for a production integration, contact Salespanel support.

429 Response

When a request is throttled, the API returns 429 Too Many Requests. Your integration should pause and retry later instead of immediately repeating the same request.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"detail":"Request was throttled."}

Retry Guidance

  • Use exponential backoff before retrying throttled requests.
  • Avoid tight retry loops, especially for scheduled jobs and bulk syncs.
  • Use pagination and only request the data your integration needs.
  • Log 429 responses so you can tune request volume before production rollout.

Pagination

API methods that return a collection of results are always paginated with pagination information inside a pagination object. Salespanel APIs use limit/offset based pagination. The default limit is 10 items, with the maximum limit being 100.

Example Response

{
  "pagination": {
    "count": 1234,
    "next": "https://salespanel.io/api/v1/visitors/?limit=10&offset=10",
    "previous": null
  },
  "results": [
    ...
  ]
}

Query Parameters

Parameter Type Default Description
limit integer 10 Number of results per call. Accepted values: 1 - 100. Default is 10.
offset integer 0 A cursor for use in pagination. offset indicates the starting position to return rows from a result set.

Pagination Object

Attribute Type Description
next string The corresponding URL is the link to the next page.
previous string The corresponding URL is the link to the previous page.
count integer The total number of records available for the resource requested.

Visitors Overview

A visitor represents a unique individual who has interacted with your website. They can be anonymous visitors, identified leads with email addresses, or visiting companies detected.

📚 Backward Compatibility

Note: Historically, visitors were called "contacts" in our technical documentation. All legacy /contacts/ endpoints still work and are fully compatible with the new /visitors/ endpoints. No code changes are required if you're using the old endpoints.

🔄 Visitor Lifecycle

Anonymous VisitorIdentified Lead (with email) → Enriched Profile (with person & company data)

Visitor Object

The visitor object is the core data structure that contains comprehensive information about each visitor. It consists of several nested objects that provide different aspects of visitor data.

Object Structure

Attribute Type Description Availability
contact_id string (UUID) Unique identifier for the visitor Always
person_details object Person information (name, email, etc.) When identified and enriched
company_details object Company information When identified and enriched
acquisition_details object Traffic source and acquisition data Always
visitor_attributes object Custom attributes set via API When set
visitor_tags array Tags assigned to the visitor When set
qualified_segments array Segments the visitor qualifies for When qualified
web_activity_summary object Summary of website activity Always

Complete Example

{
  "contact_id": "be8364a3-59b2-d17e-988f-27fb997df240",
  "person_details": {
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "bio": "Senior Software Engineer with 8+ years experience",
    "location": "San Francisco, CA, USA",
    "title": "Senior Software Engineer",
    "organization": "TechCorp Inc",
    "website": "https://johndoe.dev",
    "facebook": null,
    "linkedin": "https://linkedin.com/in/johndoe",
    "twitter": "https://twitter.com/johndoe"
  },
  "company_details": {
    "name": "TechCorp Inc",
    "domain": "techcorp.com",
    "category": "Technology",
    "industry": "Software Development",
    "bio": "Leading provider of enterprise software solutions",
    "location": "San Francisco, CA, USA",
    "founded": 2015,
    "employees": 250,
    "facebook": "https://facebook.com/techcorp",
    "linkedin": "https://linkedin.com/company/techcorp",
    "twitter": "https://twitter.com/techcorp",
    "website": "https://techcorp.com"
  },
  "acquisition_details": {
    "source": "Google",
    "medium": "organic",
    "landing_ip_address": "192.168.1.100",
    "landing_location": {
      "city": "San Francisco",
      "region": "California",
      "region_code": "CA",
      "country": "United States",
      "country_code": "US",
      "continent": "North America",
      "continent_code": "NA",
      "emoji_flag": "🇺🇸",
      "emoji_unicode": "U+1F1FA U+1F1F8"
    },
    "landing_user_agent": {
      "browser": "Chrome 120.0.6099",
      "device": "Desktop",
      "device_os": "macOS 14.1"
    }
  },
  "visitor_attributes": {
    "plan_interest": "enterprise",
    "company_size": 250,
    "budget_range": "50000-100000",
    "is_decision_maker": true,
    "demo_requested": true
  },
  "visitor_tags": [
    "enterprise_prospect",
    "high_intent",
    "technical_buyer"
  ],
  "qualified_segments": [
    "Enterprise Leads",
    "Technical Decision Makers",
    "High Value Prospects"
  ],
  "web_activity_summary": {
    "total_page_visits": 47,
    "total_website_sessions": 8,
    "first_seen": "2024-01-15T10:30:00Z",
    "last_seen": "2024-01-20T16:45:00Z"
  }
}

Person Details Object

Contains enriched person information when a visitor is identified with an email address.

Field Type Description
namestringFull name of the person
first_namestringFirst name of the person
last_namestringLast name of the person
emailstringEmail address of the person
biostringBiography of the person
locationstringCurrent or most recent location of the person
titlestringCurrent or most recent job title of the person
organizationstringCurrent or most recent place of work
websitestringURL of the person's website
facebookstringURL of the person's Facebook profile
linkedinstringURL of the person's LinkedIn profile
twitterstringURL of the person's Twitter profile

Company Details Object

Contains enriched company information when available.

Field Type Description
namestringCompany name
domainstringCompany domain
categorystringCompany category
industrystringIndustry classification
biostringCompany biography
locationstringCompany location
foundedintegerYear founded
employeesintegerNumber of employees
facebookstringURL of the company's Facebook profile
linkedinstringURL of the company's LinkedIn profile
twitterstringURL of the company's Twitter profile
websitestringCompany website

Acquisition Details Object

Contains details like browser, location, etc. at the time when the contact was acquired for the first time.

Main Fields

Field Type Description
sourcestringEither the utm_source query parameter or the referrer website.
landing_ip_addressstringIP address. Availability depends on data governance policies applied to your Salespanel account.
landing_locationobjectGeographic location details from IP address. Availability depends on data governance policies applied to your Salespanel account.
landing_user_agentobjectBrowser and device information

Landing Location Object

Field Type Description
citystringThe name of the city from where the IP Address is located. Availability depends on data governance policies applied to your Salespanel account.
regionstringThe name of the region where the IP Address is located. Availability depends on data governance policies applied to your Salespanel account.
region_codestringThe 3 letter ISO 3166-2 code for the region. Availability depends on data governance policies applied to your Salespanel account.
countrystringThe name of the country where the IP Address is located. Availability depends on data governance policies applied to your Salespanel account.
country_codestringThe 2 letter ISO 3166-1 alpha-2 code for the country. Availability depends on data governance policies applied to your Salespanel account.
continentstringThe name of the continent where the IP Address is located. One of Africa, Antarctica, Asia, Europe, North America, Oceania, South America. Availability depends on data governance policies applied to your Salespanel account.
continent_codestringThe 2 letter ISO 3166-1 alpha-2 code for the continent. One of AF, AN, AS, EU, NA, OC, SA. Availability depends on data governance policies applied to your Salespanel account.
emoji_flagstringAn emoji version of the flag of the country where the IP Address is located. Availability depends on data governance policies applied to your Salespanel account.
emoji_unicodestringThe Unicode for the emoji flag. Availability depends on data governance policies applied to your Salespanel account.

Landing User Agent Object

Field Type Description
browserstringBrowser with version used by the visitor.
devicestringDevice used by the visitor.
device_osstringOS of the device used by the visitor.

List Visitors

Retrieve a list of visitors from your account. Results are paginated and sorted by recent activity.

GET /api/v1/visitors/

curl "https://salespanel.io/api/v1/visitors/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Query Parameters

Parameter Type Description
limit integer Number of results (1-100, default: 10)
offset integer Starting position for pagination
select_by_first_activity boolean Filter by first activity date (default: false)

Retrieve Visitor

Get detailed information about a specific visitor by their ID.

GET /api/v1/visitors/{visitor_id}/

curl "https://salespanel.io/api/v1/visitors/be8364a3-59b2-d17e-988f-27fb997df240/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Identify Visitor

Convert an anonymous visitor to an identified lead by associating them with an email address.

POST /api/v1/visitors/{visitor_id}/identify/

curl -X POST "https://salespanel.io/api/v1/visitors/be8364a3-59b2-d17e-988f-27fb997df240/identify/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "identified_through": "form_submission"}'

Request Body

Parameter Type Required Description
email string Yes Valid email address to associate with visitor
identified_through string No How the visitor was identified (e.g., "form_submission", "email_click")

Visitor Attributes Object

Visitor attributes allow you to store custom data about your visitors. These attributes can be used for segmentation, lead scoring, and personalization.

Attribute Structure

The visitor_attributes object contains key-value pairs where:

  • Key: The attribute name/label (string)
  • Value: The attribute value (can be string, number, decimal, or boolean)

Attribute Creation

If an attribute doesn't exist in your account, it will be automatically created when you first set a value for it. The attribute type will be determined based on the first value provided.

Supported Value Types

Type Example Description
String "Enterprise" Text values like names, categories, etc.
Number 500 Integer values like employee count, age, etc.
Decimal 1.10, 2.21, 3.3 Float values like revenue, scores, percentages, etc.
Boolean true or false True/false values like subscription status

Example Attributes Object

{
  "company_size": "Enterprise",
  "employee_count": 500,
  "annual_revenue": 5000000.50,
  "is_customer": true,
  "conversion_rate": 3.45,
  "industry": "Software",
  "lead_source": "Google Ads",
  "interest_score": 85
}

Set Visitor Attributes

Set values for a visitor's attributes. If an attribute is not already created in your account, a new attribute will be automatically created based on the first value provided.

You need visitor_identifier which can be either the contact_id or email, which is the unique identifier for a particular contact.

HTTP Request

POST https://salespanel.io/api/v1/visitor-attributes/

POST Body Parameters

Parameter Type Required Description
visitor_identifier string required contact_id (uuid) or email of the contact
visitor_attributes object required Key-value pairs with key as attribute label and value as the value you want to set for the visitor. Visitor attributes object
create_new boolean optional Create a new visitor if it doesn't exist already with the identifier (email) provided. Default is false.
curl -X POST "https://salespanel.io/api/v1/visitor-attributes/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_identifier": "[email protected]",
    "visitor_attributes": {
      "company_size": "Enterprise",
      "employee_count": 500,
      "is_customer": true,
      "lead_source": "Google Ads"
    },
    "create_new": false
  }'

Example Response

{
  "visitor_id": "b9f0f074-d765-4b7f-8a7a-cf94071026a8",
  "message": "Visitor attributes updated successfully",
  "created_attributes": ["company_size", "employee_count"],
  "updated_attributes": ["is_customer", "lead_source"]
}

Activity Object

Activities track visitor interactions with your website and campaigns. There are three types of activities, each with different data structures based on the interaction type.

Activity Types

Type Description Source
links Website page visits and form submissions Tracking script
email Email opens and interactions Email tracking pixel
custom_activity Custom events logged via API/SDK REST API, JavaScript SDK, Zapier

Links Activity Object

Tracks website page visits, form submissions, and user interactions.

Field Type Description
activity_typestringAlways "links"
page_titlestringHTML title of the page
linkstringFull URL of the page visited
formbooleanWhether a form was submitted on this page
page_durationintegerTime spent on page in seconds
utm_paramsobjectUTM parameters from the URL
referrer_linkstringReferring URL (if any)
created_ondatetimeWhen the activity occurred
{
  "activity_type": "links",
  "page_title": "Pricing - Salespanel",
  "link": "https://salespanel.io/pricing",
  "form": false,
  "page_duration": 45,
  "utm_params": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "enterprise_leads"
  },
  "referrer_link": "https://google.com/search",
  "created_on": "2024-01-20T14:30:00Z"
}

Email Activity Object

Tracks email opens and interactions from your email campaigns.

Field Type Description
activity_typestringAlways "email"
subjectstringSubject line of the email
created_ondatetimeWhen the email was opened
{
  "activity_type": "email",
  "subject": "Your Free Trial is Expiring Soon",
  "created_on": "2024-01-20T09:15:00Z"
}

Custom Activity Object

Tracks custom events that you log via API, JavaScript SDK, or Zapier integrations.

Field Type Description
activity_typestringAlways "custom_activity"
categorystringCategory for grouping activities
labelstringSpecific action performed
activity_identifierstringOptional identifier for the activity
metadataobjectAdditional custom data
created_ondatetimeWhen the activity was logged
{
  "activity_type": "custom_activity",
  "category": "product_interaction",
  "label": "demo_video_watched",
  "activity_identifier": "Product Demo - Homepage",
  "metadata": {
    "video_duration": 180,
    "completion_percentage": 85,
    "video_id": "demo_v1_2024"
  },
  "created_on": "2024-01-20T11:42:00Z"
}

List Activities

Retrieve all activities for a specific visitor, including page visits, email interactions, and custom activities.

GET /api/v1/visitors/{visitor_id}/activities/
GET /api/v1/visitors/{email}/activities/

# By visitor ID
curl "https://salespanel.io/api/v1/visitors/be8364a3-59b2-d17e-988f-27fb997df240/activities/" \
  -H "Authorization: Token YOUR_API_TOKEN"

# By email
curl "https://salespanel.io/api/v1/visitors/[email protected]/activities/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Example Response

[
  {
    "activity_type": "links",
    "page_title": "Pricing - Salespanel",
    "link": "https://salespanel.io/pricing/",
    "form": false,
    "created_on": "2024-01-20T10:30:15Z",
    "page_duration": 180,
    "referrer_link": "https://google.com/search?q=salespanel+pricing",
    "utm_params": {
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "pricing_campaign"
    }
  },
  {
    "activity_type": "email",
    "subject": "Welcome to Salespanel - Getting Started Guide",
    "created_on": "2024-01-20T09:15:30Z"
  },
  {
    "activity_type": "custom_activity",
    "category": "product_interaction",
    "label": "demo_video_watched",
    "activity_identifier": "Product Demo - Homepage",
    "metadata": {
      "video_duration": 180,
      "completion_percentage": 85,
      "video_id": "demo_v1_2024"
    },
    "created_on": "2024-01-20T08:42:00Z"
  },
  {
    "activity_type": "links",
    "page_title": "Contact Form",
    "link": "https://salespanel.io/contact/",
    "form": true,
    "created_on": "2024-01-19T16:20:45Z",
    "page_duration": 45,
    "referrer_link": "https://salespanel.io/features/"
  }
]

Response Fields

Field Type Description
activity_type string Type of activity: "links", "email", or "custom_activity"
created_on string ISO 8601 timestamp when the activity occurred
page_title string Title of the visited page (for link activities)
link string URL of the visited page (for link activities)
form boolean Whether a form was submitted on this page (for link activities)
page_duration integer Time spent on page in seconds (for link activities)
referrer_link string URL of the referring page (for link activities)
utm_params object UTM tracking parameters (for link activities)
subject string Subject line of the opened email (for email activities)
category string Category of the custom activity (for custom activities)
label string Label describing the custom activity (for custom activities)
activity_identifier string Identifier for the custom activity (for custom activities)
metadata object Additional data associated with the custom activity

Log Custom Activity

Create custom activity records to track specific events, interactions, or milestones beyond standard page visits and email opens. Custom activities are essential for comprehensive visitor behavior tracking and can be used for lead scoring, segmentation, and triggering automated workflows.

For tracking button clicks and menu interactions, see our JS SDK Guide.

💡 Use Cases

  • • Track product demo views, trial signups, or feature usage
  • • Log offline interactions like phone calls or meetings
  • • Record engagement with specific content or resources
  • • Monitor purchase intent signals and conversion events
  • • Integrate data from external systems and platforms

POST /api/v1/custom-activity/create/

Request Body Parameters

Parameter Type Required Description
visitor_identifier string Yes Email address or visitor ID to associate the activity with
category string Yes Category to group similar activities (e.g., "product_interaction", "sales_call")
label string Yes Specific action or event name (e.g., "demo_viewed", "trial_started")
activity_identifier string Optional Human-readable description or identifier for the activity
metadata object Optional Additional data as key-value pairs for context and analysis
curl -X POST "https://salespanel.io/api/v1/custom-activity/create/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_identifier": "[email protected]",
    "category": "product_interaction",
    "label": "viewed_demo",
    "activity_identifier": "Product Demo Video",
    "metadata": {"video_duration": 120, "completed": true}
  }'

Example Response

{
  "visitor_id": "b9f0f074-d765-4b7f-8a7a-cf94071026a8",
  "success": true
}

📝 Best Practices

  • • Use consistent naming conventions for categories and labels
  • • Include relevant metadata to provide context for analysis
  • • Timestamp activities as close to when they occur as possible
  • • Consider the impact on lead scoring and segmentation rules
  • • Test with a small dataset before implementing at scale

List Leads

Returns a list of leads that were active within the last 24 hours in your Salespanel account. The leads are returned in sorted order, with the most recent active appearing first.

This endpoint returns a paginated list of visitor objects for identified visitors (leads). Each object contains the complete visitor information.

By default, Salespanel API returns the leads who were last active in the given time period (last 24 hours). However, you can choose to retrieve only those leads who were first active in the given time period, so leads which were active 1 hour ago, but were actually first seen 7 days ago, won't be returned. The select_by_first_activity query parameter can be used for this purpose.

GET /api/v1/leads/

Query Parameters

Parameter Default Description
select_by_first_activity false optional
Retrieve leads based on their first activity.
limit 10 optional
Number of results per call. Accepted values: 1 - 100. Default is 10.
offset 0 optional
A cursor for use in pagination. offset indicates the starting position to return rows from a result set.
curl "https://salespanel.io/api/v1/leads/" \
  -H "Authorization: Token YOUR_API_TOKEN"

List Visiting Companies

Returns a list of visiting companies that were active within the last 24 hours in your Salespanel account. The visiting companies are returned in sorted order, with the most recent active appearing first.

This endpoint returns a paginated list of company objects for visiting companies. Each object contains the complete company information identified.

By default, Salespanel API returns the visiting companies who were last active in the given time period (last 24 hours). However, you can choose to retrieve only those visiting companies who were first active in the given time period, so visiting companies which were active 1 hour ago, but were actually first seen 7 days ago, won't be returned. The select_by_first_activity query parameter can be used for this purpose.

GET /api/v1/visiting-companies/

Query Parameters

Parameter Default Description
select_by_first_activity false optional
Retrieve visiting companies based on their first activity.
limit 10 optional
Number of results per call. Accepted values: 1 - 100. Default is 10.
offset 0 optional
A cursor for use in pagination. offset indicates the starting position to return rows from a result set.
curl "https://salespanel.io/api/v1/visiting-companies/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Get Attribution

Retrieve detailed attribution information including first-touch and last-touch marketing attribution.

GET /api/v1/visitors/attribution/{visitor_id}/
GET /api/v1/visitors/attribution/{email}/

📊 Enhanced Response

These endpoints return the standard visitor object plus additional attribution fields. The response includes extra data not available in regular visitor endpoints.

# By visitor ID
curl "https://salespanel.io/api/v1/visitors/attribution/be8364a3-59b2-d17e-988f-27fb997df240/" \
  -H "Authorization: Token YOUR_API_TOKEN"

# By email
curl "https://salespanel.io/api/v1/visitors/attribution/[email protected]/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Additional Fields in Attribution Response

In addition to all standard visitor object fields, the attribution endpoints include these enhanced fields:

Field Type Description
attribution_details object Advanced attribution tracking data
web_activity_summary object Enhanced activity summary with additional metrics

Attribution Details Object

Contains detailed first-touch and last-touch attribution data:

Field Type Description
landing_pagestringFirst page visited
landing_page_sourcestringTraffic source for first visit
landing_page_mediumstringTraffic medium for first visit
first_touch_utm_parametersobjectUTM parameters from first visit
last_touch_sourcestringTraffic source for most recent visit
last_touch_mediumstringTraffic medium for most recent visit
last_touch_utm_parametersobjectUTM parameters from most recent visit

Enhanced Web Activity Summary

The attribution endpoints provide an enhanced version with additional time tracking:

Field Type Description
total_page_visitsintegerTotal number of page views
total_website_sessionsintegerTotal number of sessions
total_time_spentintegerTotal time spent on site (seconds)
first_seendatetimeFirst visit timestamp
last_seendatetimeMost recent visit timestamp

Example Attribution Response

{
  // ... all standard visitor object fields ...
  "attribution_details": {
    "landing_page": "https://salespanel.io/pricing",
    "landing_page_source": "Google",
    "landing_page_medium": "cpc",
    "first_touch_utm_parameters": {
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "enterprise_leads",
      "utm_content": "pricing_page"
    },
    "last_touch_source": "Direct",
    "last_touch_medium": "none",
    "last_touch_utm_parameters": null
  },
  "web_activity_summary": {
    "total_page_visits": 47,
    "total_website_sessions": 8,
    "total_time_spent": 2847,
    "first_seen": "2024-01-15T10:30:00Z",
    "last_seen": "2024-01-20T16:45:00Z"
  }
}

Segment Object

Segments allow you to categorize and group visitors based on their characteristics, behavior, or custom criteria. Each segment represents a specific subset of your visitor base.

Object Structure

Field Type Description
segment_id string Unique identifier for the segment (UUID)
name string Display name of the segment
created_on datetime When the segment was created
last_modified_on datetime When the segment was last modified

Example Segment Object

{
  "segment_id": "be8364a3-59b2-d17e-988f-27fb997df240",
  "name": "Enterprise Prospects",
  "created_on": "2024-01-15T10:30:00Z",
  "last_modified_on": "2024-01-20T14:22:00Z"
}

List Segments

Retrieve all visitor segments/feeds that you have created for organizing and filtering your visitors.

GET /api/v1/segments/

curl "https://salespanel.io/api/v1/segments/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Webhooks

Webhooks allow you to receive real-time notifications when specific events occur in your Salespanel account. Instead of repeatedly polling our API for changes, webhooks push data to your application automatically when events happen.

When an event occurs, we'll send an HTTP POST request to the webhook URL you've configured, containing detailed information about the event and the associated visitor data.

Getting Started

To start using webhooks, you'll need to set up webhook endpoints in your Salespanel dashboard.

View Setup Guide

Available Events

Salespanel supports webhooks for both person and company events. You can subscribe to specific events based on your integration needs.

Person Events

Event Description When Triggered
person.identified A visitor has been identified with person information When email or person details are captured
person.page_visit An identified person visited a specific page When URL filters match visited pages
person.segment_qualified A person qualified for a specific segment When segment criteria are met

Company Events

Event Description When Triggered
company.identified A visiting company has been identified When company information is enriched
company.page_visit A company visitor accessed a specific page When URL filters match visited pages
company.segment_qualified A company qualified for a specific segment When segment criteria are met

Note: Page visit events require URL filters to be configured. Segment events require the visitor to be associated with the specific segment/feed.

Webhook Object Structure

When an event occurs, Salespanel sends a POST request to your webhook URL with the following structure:

Webhook Payload

Field Type Description
hook object Metadata about the webhook and event
payload object Complete visitor data including all available information

Hook Metadata Object

Field Type Description
id string Unique identifier for the webhook configuration
event string The event that triggered this webhook
target string The webhook URL that received this payload
title string Human-readable name for the webhook

Example Webhook Payload

{
  "hook": {
    "id": "2ac9c790-9431-4609-9696-cac25b9b5ad3",
    "event": "person.segment_qualified",
    "target": "https://your-app.com/webhooks/salespanel",
    "title": "New Lead Qualification"
  },
  "payload": {
    "contact_id": "c1e82a57-bc6f-ad03-d6c1-2a2cc23948fe",
    "person_details": {
      "name": "Akshay Darekar",
      "first_name": "Akshay",
      "last_name": "Darekar",
      "email": "[email protected]",
      "title": "Developer",
      "organization": "Webspdy",
      "website": "https://webspdy.com/",
      "bio": "web tech enthusiast",
      "location": null,
      "linkedin": null,
      "twitter": null,
      "facebook": null
    },
    "company_details": {
      "name": "Webspdy",
      "domain": "webspdy.com",
      "website": "https://webspdy.com",
      "industry": "Technology",
      "employees": 15,
      "founded": 2018,
      "location": "Mumbai, India",
      "bio": "Web development agency",
      "linkedin": "https://linkedin.com/company/webspdy",
      "twitter": null,
      "facebook": null,
      "category": "Software Development"
    },
    "acquisition_details": {
      "source": "Direct",
      "medium": "organic",
      "campaign": null,
      "landing_page": "/pricing",
      "landing_ip_address": "*.*.27.241",
      "landing_user_agent": {
        "device": "PC",
        "device_os": "Mac OS X 10.15.7",
        "browser": "Chrome 94.0.4606"
      },
      "landing_location": {
        "city": "Pune",
        "region": "Maharashtra",
        "region_code": "MH",
        "country": "India",
        "country_code": "IN",
        "continent": "Asia",
        "continent_code": "AS",
        "emoji_flag": "🇮🇳",
        "emoji_unicode": "U+1F1EE U+1F1F3"
      }
    },
    "lead_scoring": {
      "lead_score": 85
    },
    "visitor_attributes": {
      "plan_interest": "Enterprise",
      "budget_range": "10000-25000"
    },
    "visitor_tags": ["hot-lead", "enterprise"],
    "qualified_segments": [
      {
        "id": 42,
        "name": "Enterprise Prospects"
      }
    ],
    "web_activity_summary": {
      "total_page_views": 12,
      "total_sessions": 3,
      "first_visit": "2024-01-15T10:30:00Z",
      "last_visit": "2024-01-20T14:22:00Z"
    },
    "segment": {
      "segment_id": "9887ba45-b350-42eb-ac1e-062b4f55328a",
      "title": "Enterprise Prospects"
    }
  }
}

Note: The payload contains the complete visitor object as described in the Visitors section, plus additional event-specific data like segment information for segment qualification events.

Setup Guide

Follow these steps to configure webhooks for your Salespanel account:

1

Access Webhook Settings

Navigate to your Salespanel dashboard and go to Settings → Tools and Apps → Webhooks to configure your webhook endpoints.

2

Create Webhook Endpoint

Set up an HTTPS endpoint in your application to receive webhook payloads. Your endpoint should:

  • Accept POST requests
  • Return a 200 status code for successful processing
  • Process requests within 10 seconds
  • Handle duplicate deliveries gracefully
3

Configure Events

Select which events you want to receive notifications for:

  • Choose person or company events (or both)
  • Set URL filters for page visit events
  • Associate with specific segments if needed
4

Test Your Integration

Use the test feature in the Salespanel dashboard to send sample webhook payloads to your endpoint and verify everything is working correctly.

Security Best Practices

  • Use HTTPS endpoints to ensure data security
  • Validate webhook signatures using the provided webhook ID
  • Implement proper error handling and logging
  • Consider implementing idempotency to handle duplicate events

For detailed setup instructions and troubleshooting, visit our comprehensive webhook guide .