Persana AI Plugin for OpenPets

A comprehensive OpenPets plugin for the Persana AI API that provides B2B contact and company data enrichment, AI-powered waterfall enrichment, verified emails, phone numbers, and detailed firmographic insights.

Features

• People Search: Find contacts by title, company, location, industry, and more
• Person Enrichment: Enrich profiles with emails, phones, social links, and work history
• Company Intelligence: Get detailed company data, growth metrics, and employee information
• Email Lookup: Find verified email addresses using waterfall enrichment
• Phone Lookup: Get verified phone numbers for contacts
• Job Change Tracking: Monitor recent job movements and hiring trends
• Company Growth Analytics: Track employee growth and hiring patterns over time

Setup

1. Get API Key

1. Sign up at Persana AI Platform
2. Navigate to the API section to generate your API key
3. You may need to request access or book a demo for enterprise plans

2. Configure Environment

Create a .env file in the persana plugin directory:

# Required: API key from Persana AI platform
PERSANA_API_KEY=your_api_key_here

# Optional: Custom base URL (default: https://prod.api.persana.ai)
# PERSANA_BASE_URL=https://prod.api.persana.ai

3. Test Connection

cd pets/persana
opencode run "test persana connection" --format json --print-logs

Available Tools

Core Tools

• persana-test-connection: Test API connection and configuration
• persana-search-people: Search for people by various criteria
• persana-enrich-person: Enrich a person's profile using identifiers
• persana-get-company: Get detailed company information
• persana-search-companies: Search for companies by criteria

Enrichment Tools

• persana-lookup-email: Find verified email addresses
• persana-lookup-phone: Find verified phone numbers
• persana-get-job-changes: Get recent job changes and movements
• persana-get-company-growth: Get company growth metrics

Usage Examples

Search for CEOs at Software Companies

opencode run "search for people with CEO title at software companies" --format json

Enrich a Contact Profile

opencode run "enrich person profile with email [email protected]" --format json

Get Company Information

opencode run "get company information for microsoft.com" --format json

Find Verified Emails

opencode run "lookup email for John Smith at Google" --format json

Track Job Changes

opencode run "get job changes for tech companies in last 30 days" --format json

Tool Parameters

persana-search-people

Search for people using multiple criteria:

• person_titles: Array of job titles (e.g., ["CEO", "Product Manager"])
• company_names: Array of company names
• seniorities: Seniority levels (e.g., ["Chief X Officer (CxO)", "Vice President (VP)"])
• locations: Geographic locations
• industries: Industries to filter by
• company_size: Company size range (e.g., "50:200")
• revenue: Revenue range (e.g., "1000000:10000000")
• keywords: Keywords in profiles
• page: Page number (default: 1)
• per_page: Results per page (max 100, default: 20)

persana-enrich-person

Enrich person profiles:

• email: Email address to enrich
• first_name: First name
• last_name: Last name
• company_name: Current company
• title: Job title
• linkedin_url: LinkedIn profile URL
• include_email: Include email in results (default: true)
• include_phone: Include phone number (default: true)

persana-get-company

Get company information:

• domain: Company website domain (e.g., "microsoft.com")
• company_name: Company name
• linkedin_url: Company LinkedIn URL
• include_employees: Include employee data (default: false)
• include_funding: Include funding data (default: false)

persana-lookup-email

Find verified emails:

• first_name: First name (required)
• last_name: Last name (required)
• company_name: Company name (required)
• title: Job title (optional, improves accuracy)
• verify_deliverability: Verify email deliverability (default: true)

persana-lookup-phone

Find verified phone numbers:

• first_name: First name (required)
• last_name: Last name (required)
• company_name: Company name (required)
• title: Job title (optional, improves accuracy)
• phone_type: Type of phone number ("mobile", "landline", "all")

Response Format

All tools return JSON responses with this structure:

{
  "success": true,
  "data": { /* tool-specific data */ },
  "message": "Operation completed successfully"
}

Error responses:

{
  "success": false,
  "error": "Error message",
  "details": { /* additional context */ }
}

Rate Limits

Rate limits depend on your Persana subscription plan. Check your Persana dashboard for specific limits and usage quotas based on your credits.

Best Practices

1. Start Broad, Then Narrow: Begin with broader searches, then apply specific filters
2. Use Multiple Identifiers: Provide as much information as possible for enrichment
3. Verify Results: Use the verification status information for emails and phones
4. Monitor Usage: Keep track of your API usage to avoid hitting limits
5. Cache Results: Consider caching frequently accessed company data

Troubleshooting

Common Issues

1. "Not Configured" Error: Ensure PERSANA_API_KEY is set in your environment
2. Rate Limit Errors: Check your subscription limits and usage quotas
3. No Results Found: Try broadening search criteria or checking spelling
4. Verification Failures: Some emails/phones may not be verifiable due to privacy settings

Debug Mode

Enable debug logging by setting the log level:

opencode run "test persana connection" --format json --print-logs

Support

• Persana Documentation: https://persana.ai/full-contact-api
• Platform Login: https://www.platform.persana.ai/login
• Book a Demo: https://calendly.com/d/2xg-4vb-t3c/persana-ai-onboarding
• Help Center: https://persana.ai/help-center

Development

To modify or extend this plugin:

1. Edit index.ts to add new tools or modify existing ones
2. Update package.json with new environment variables or queries
3. Test changes locally before publishing
4. Follow OpenPets development guidelines for consistency

License

This plugin is part of the OpenPets ecosystem and follows the same licensing terms.