Skip to main content

​
Overview

Prospects represent external users on messaging platforms. This guide covers retrieving prospect data, updating context, and using prospect information for lead management.

​
Prospect Data Model

interface Prospect {
  id: string;                    // Inbox prospect ID
  platformId: string;            // Platform user ID (e.g., X user ID)
  platform: 'x';                 // Platform type
  platformUsername: string;      // @handle
  name?: string;                 // Display name
  description?: string;          // Bio
  profileImageUrl?: string;      // Avatar URL
  verified: boolean;             // Platform verified status
  followersCount?: number;       // Follower count
  followingCount?: number;       // Following count
  location?: string;             // Profile location
  url?: string;                  // Profile URL

  // Custom context
  notes?: string;                // Your notes about this prospect
  valuation?: number;            // Deal value
  tags: Tag[];                   // Applied tags
  status?: Status;               // Pipeline status
  assignedToMemberId?: string;   // Assigned team member
  done: boolean;                 // Marked as complete
}

​
Finding Prospects

​
Lookup by Platform ID

Find a prospect using their X user ID: 
const { data } = await client.get('/prospects/lookup', {
  params: {
    platformId: '1234567890'  // X user ID
  }
});

if (data.prospect) {
  console.log(`Found: @${data.prospect.platformUsername}`);
  console.log(`Followers: ${data.prospect.followersCount}`);
} else {
  console.log('Prospect not in system');
}
Response: 
{
  "prospect": {
    "id": "prospect_abc123",
    "platformId": "1234567890",
    "platform": "x",
    "platformUsername": "johndoe",
    "name": "John Doe",
    "description": "Software Engineer | Building cool stuff",
    "verified": false,
    "followersCount": 5420,
    "followingCount": 892,
    "tags": [],
    "status": null,
    "done": false
  }
}

​
Get by Inbox ID

Retrieve a specific prospect: 
const { data } = await client.get(`/prospects/${prospectId}`);
console.log('Prospect:', data.prospect);
Prospects are automatically created when they message you or when you start a conversation with them.

​
Updating Prospect Context

Add your own data to prospects for tracking and organization.

​
Setting Notes and Valuation

await client.patch(`/prospects/${prospectId}/context`, {
  notes: 'Interested in Enterprise plan. Follow up next week.',
  valuation: 50000
});

​
Applying Tags

// Get tag IDs first
const { data: tagsData } = await client.get('/tags');
const hotLeadTag = tagsData.tags.find(t => t.name === 'Hot Lead');
const enterpriseTag = tagsData.tags.find(t => t.name === 'Enterprise');

// Apply tags to prospect
await client.patch(`/prospects/${prospectId}/context`, {
  tagIds: [hotLeadTag.id, enterpriseTag.id]
});

​
Setting Status

// Get status IDs first
const { data: statusData } = await client.get('/statuses');
const qualifiedStatus = statusData.statuses.find(s => s.name === 'Qualified');

// Set prospect status
await client.patch(`/prospects/${prospectId}/context`, {
  statusId: qualifiedStatus.id
});

​
Assigning to Team Member

// Get member IDs
const { data: membersData } = await client.get('/members');
const salesRep = membersData.members.find(m => m.email === 'sales@example.com');

// Assign prospect
await client.patch(`/prospects/${prospectId}/context`, {
  assignedToMemberId: salesRep.id
});

​
Complete Update

All context fields can be updated in a single request: 
await client.patch(`/prospects/${prospectId}/context`, {
  notes: 'Decision maker at Acme Corp',
  valuation: 75000,
  tagIds: ['tag_enterprise', 'tag_decision_maker'],
  statusId: 'status_qualified',
  assignedToMemberId: 'member_sales_lead',
  done: false
});
Response: 
{
  "prospect": {
    "id": "prospect_abc123",
    "platformUsername": "johndoe",
    "notes": "Decision maker at Acme Corp",
    "valuation": 75000,
    "tags": [
      { "id": "tag_enterprise", "name": "Enterprise", "color": "#4F46E5" },
      { "id": "tag_decision_maker", "name": "Decision Maker", "color": "#059669" }
    ],
    "status": { "id": "status_qualified", "name": "Qualified", "color": "#0EA5E9" },
    "assignedToMemberId": "member_sales_lead",
    "done": false
  }
}

​
Prospect Lookup vs Thread Lookup

Two lookup patterns exist for different use cases:
Use CaseEndpointReturns
Get prospect data/prospects/lookupProspect object
Find conversation/threads/lookupThread object
// When you need prospect profile data
const { data: prospectData } = await client.get('/prospects/lookup', {
  params: { platformId: '1234567890' }
});

// When you need the conversation
const { data: threadData } = await client.get('/threads/lookup', {
  params: {
    prospectPlatformId: '1234567890',
    accountLinkId: 'acc_abc123'
  }
});

​
Common Workflows

​
Lead Scoring

Calculate a score based on prospect profile: 
function calculateLeadScore(prospect: Prospect): number {
  let score = 0;

  // Follower count scoring
  if (prospect.followersCount > 100000) score += 30;
  else if (prospect.followersCount > 10000) score += 20;
  else if (prospect.followersCount > 1000) score += 10;

  // Verification bonus
  if (prospect.verified) score += 15;

  // Bio keywords
  const bio = prospect.description?.toLowerCase() || '';
  const keywords = ['founder', 'ceo', 'director', 'head of', 'vp'];
  if (keywords.some(k => bio.includes(k))) score += 25;

  // Has website
  if (prospect.url) score += 10;

  return score;
}

// Usage
const score = calculateLeadScore(prospect);
console.log(`Lead score: ${score}/100`);

// Auto-tag based on score
if (score >= 70) {
  await client.patch(`/prospects/${prospect.id}/context`, {
    tagIds: ['tag_high_value']
  });
}

​
Bulk Prospect Update

Update multiple prospects efficiently: 
async function bulkUpdateProspects(
  updates: Array<{ prospectId: string; context: Record<string, any> }>
) {
  const results = [];

  for (const { prospectId, context } of updates) {
    try {
      await client.patch(`/prospects/${prospectId}/context`, context);
      results.push({ prospectId, success: true });

      // Respect rate limits
      await new Promise(r => setTimeout(r, 100));
    } catch (error) {
      results.push({ prospectId, success: false, error: error.message });
    }
  }

  return results;
}

// Usage
const updates = [
  { prospectId: 'prospect_1', context: { statusId: 'status_qualified' } },
  { prospectId: 'prospect_2', context: { statusId: 'status_qualified' } },
  { prospectId: 'prospect_3', context: { statusId: 'status_nurture' } }
];

await bulkUpdateProspects(updates);

​
Finding Prospects by Tag

Find all threads with prospects that have specific tags: 
// Get all enterprise prospects with active conversations
const { data } = await client.get('/threads', {
  params: {
    inboxView: 'default',
    'filter[tagIds][0]': 'tag_enterprise'
  }
});

// Extract prospect info
const enterpriseProspects = data.threads.map(thread => ({
  prospectId: thread.prospectId,
  username: thread.prospect.platformUsername,
  threadId: thread.id
}));

console.log(`${enterpriseProspects.length} active enterprise conversations`);

​
Exporting Prospect Data

Export prospects to CSV format: 
async function exportProspects() {
  const allThreads = [];
  let cursor = undefined;

  // Fetch all threads with prospects
  do {
    const { data } = await client.get('/threads', {
      params: {
        limit: 100,
        ...(cursor && {
          'cursor[id]': cursor.id,
          'cursor[timestamp]': cursor.timestamp
        })
      }
    });

    allThreads.push(...data.threads);
    cursor = data.nextCursor;
  } while (cursor);

  // Build CSV
  const rows = allThreads.map(t => ({
    prospectId: t.prospect.id,
    platformId: t.prospect.platformId,
    username: t.prospect.platformUsername,
    name: t.prospect.name || '',
    followers: t.prospect.followersCount || 0,
    verified: t.prospect.verified,
    tags: t.prospect.tags.map(tag => tag.name).join('; '),
    status: t.prospect.status?.name || '',
    notes: t.prospect.notes || ''
  }));

  return rows;
}

​
Platform Profile Data

Prospect profile data is synced from the platform and includes:
FieldDescriptionUpdates
platformUsername@handleOn each interaction
nameDisplay nameOn each interaction
descriptionBioOn each interaction
followersCountFollowersPeriodically
verifiedBlue checkPeriodically
profileImageUrlAvatarOn each interaction
Profile data may be slightly stale. Followers count and other stats are updated periodically, not in real-time.

​
Best Practices

Tags are multi-select. Use them for attributes that can overlap:
  • Lead source (Twitter Ad, Referral, Organic)
  • Industry (SaaS, Finance, Healthcare)
  • Interest (Product A, Product B)
Statuses are single-select and ordered. Use them for linear progression:
  • New → Qualified → Demo Scheduled → Proposal → Closed
Use the notes field for context that doesn’t fit structured fields:
await client.patch(`/prospects/${id}/context`, {
  notes: `Meeting 1/15: Discussed pricing. Need to follow up with case study.
Key decision maker. Budget approved Q1.`
});
Set valuation to prioritize high-value prospects:
// Filter threads and sort by valuation
const sorted = threads
  .filter(t => t.prospect.valuation)
  .sort((a, b) => b.prospect.valuation - a.prospect.valuation);

Lookup Prospect

GET /prospects/lookup

Get Prospect

GET /prospects/

Update Context

PATCH /prospects//context

Tags & Statuses

Organizing with tags and statuses

​
Next Steps

Tags & Statuses

Organize prospects with tags and pipeline statuses

Error Codes

Handle errors properly

Rate Limits

Understand API limits

Managing Threads

Work with conversations