Companies API Guide

The Companies API allows you to manage organizations and businesses in Sure Send CRM programmatically. This guide covers everything you need to know about creating, updating, and organizing your B2B contacts and accounts.

Overview

Companies represent organizations, businesses, and accounts in your CRM. Each company can have:

Basic information (name, industry, website)
Multiple emails, phones, and addresses
Tags for categorization
Custom fields for additional data
Pipeline stage and assignment
Source tracking
Financial information (revenue, company size)
Business identifiers (registration number, tax ID)

Creating Companies

Basic Company Creation

Endpoint: POST /api/partner/companies

curl -X POST https://api.suresend.ai/api/partner/companies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "industry": "Technology",
    "website": "https://acme.com"
  }'

Response:

{
  "id": "company-uuid",
  "name": "Acme Corporation",
  "industry": "Technology",
  "website": "https://acme.com",
  "description": null,
  "companySize": null,
  "annualRevenue": null,
  "emails": [],
  "phones": [],
  "addresses": [],
  "tags": [],
  "stage": null,
  "source": null,
  "engagementScore": 0,
  "created": "2025-10-22T12:00:00Z",
  "updated": "2025-10-22T12:00:00Z"
}

Full Company with All Details

curl -X POST https://api.suresend.ai/api/partner/companies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "industry": "Technology",
    "website": "https://acme.com",
    "description": "Leading provider of innovative solutions",
    "companySize": "51-200",
    "annualRevenue": 5000000,
    "foundedDate": "2010-01-15T00:00:00Z",
    "registrationNumber": "12345678",
    "taxId": "98-7654321",
    "stage": "Prospect",
    "source": "Referral",
    "assignedUserId": "user-uuid",
    "emails": [
      {
        "value": "[email protected]",
        "type": "work",
        "isPrimary": true
      },
      {
        "value": "[email protected]",
        "type": "billing"
      }
    ],
    "phones": [
      {
        "value": "+1-555-1234",
        "type": "main",
        "isPrimary": true
      },
      {
        "value": "+1-555-5678",
        "type": "support"
      }
    ],
    "addresses": [
      {
        "type": "headquarters",
        "street": "123 Business St",
        "city": "San Francisco",
        "state": "CA",
        "code": "94105",
        "country": "US"
      }
    ],
    "tags": ["enterprise", "prospect", "tech-sector"]
  }'

Retrieving Companies

List All Companies

Endpoint: GET /api/partner/companies

curl "https://api.suresend.ai/api/partner/companies?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 25, max: 100)
name - Filter by company name (case-insensitive, partial match)
industry - Filter by industry (case-insensitive, partial match)
email - Filter by email address (case-insensitive, partial match)
phone - Filter by phone number (normalized search)

Response:

{
  "companies": [
    {
      "id": "company-uuid",
      "name": "Acme Corporation",
      "industry": "Technology",
      "website": "https://acme.com",
      "companySize": "51-200",
      "annualRevenue": 5000000,
      "emails": [...],
      "phones": [...],
      "addresses": [...],
      "tags": ["enterprise"],
      "stage": "Customer",
      "source": "Referral"
    }
  ],
  "meta": {
    "total_count": 150,
    "current_page": 1,
    "total_pages": 3,
    "per_page": 50
  }
}

Get a Specific Company

Endpoint: GET /api/partner/companies/{id}

curl https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter Companies

By Industry:

curl "https://api.suresend.ai/api/partner/companies?industry=Technology" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

By Name:

curl "https://api.suresend.ai/api/partner/companies?name=Acme" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

By Email:

curl "https://api.suresend.ai/api/partner/[email protected]" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Updating Companies

Partial Updates

Endpoint: PUT /api/partner/companies/{id}

Only provide fields you want to change - all fields are optional:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "stage": "Customer"
  }'

Updating Company Information

Update Industry and Revenue:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Software",
    "annualRevenue": 7500000
  }'

Update Company Size:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companySize": "201-500"
  }'

Updating Contact Information

Update Email:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "value": "[email protected]",
        "type": "work",
        "isPrimary": true
      }
    ]
  }'

Update Phone:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": [
      {
        "value": "+1-555-9999",
        "type": "main",
        "isPrimary": true
      }
    ]
  }'

Update Address:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      {
        "type": "headquarters",
        "street": "456 New Corporate Blvd",
        "city": "Seattle",
        "state": "WA",
        "code": "98101",
        "country": "US"
      }
    ]
  }'

Working with Tags

Tags help you categorize and filter companies. Common use cases:

Company type (enterprise, smb, startup)
Relationship status (customer, prospect, partner)
Industry segment (saas, fintech, e-commerce)
Campaign tracking (webinar-2025, trade-show)
Account status (vip, at-risk, expansion-opportunity)

Apply Tags (Add Without Removing)

Endpoint: POST /api/partner/companies/{id}/tags/apply

curl -X POST https://api.suresend.ai/api/partner/companies/company-uuid/tags/apply \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["vip", "enterprise", "quarterly-review"]
  }'

This adds the tags without removing existing ones.

Remove Tags

Endpoint: POST /api/partner/companies/{id}/tags/delete

curl -X POST https://api.suresend.ai/api/partner/companies/company-uuid/tags/delete \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["prospect", "cold-lead"]
  }'

Replace All Tags

Use PUT /companies/{id} with mergeTags=false (default):

curl -X PUT "https://api.suresend.ai/api/partner/companies/company-uuid?mergeTags=false" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["customer", "enterprise"]
  }'

Add Tags While Keeping Existing

Use PUT /companies/{id} with mergeTags=true:

curl -X PUT "https://api.suresend.ai/api/partner/companies/company-uuid?mergeTags=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["expansion-opportunity"]
  }'

Email, Phone, and Address Types

Email Types

work - General work email
billing - Billing and invoicing
support - Customer support
other - Other email

Email Status

active - Valid, can receive emails
bounced - Email bounced, invalid

Phone Types

main - Main phone number
support - Support line
sales - Sales line
other - Other phone

Phone Status

active - Valid, can receive calls
disconnected - Phone number no longer valid

Address Types

headquarters - Main headquarters
branch - Branch office
billing - Billing address
other - Other address

Primary Contact Methods

Each company can have one primary email, phone, and address:

{
  "emails": [
    {
      "value": "[email protected]",
      "isPrimary": true
    },
    {
      "value": "[email protected]",
      "isPrimary": false
    }
  ]
}

Company Size Options

The companySize field accepts the following values:

1-10 - Micro business
11-50 - Small business
51-200 - Mid-size business
201-500 - Large business
501-1000 - Enterprise
1001-5000 - Large enterprise
5001+ - Major enterprise

Pipeline Management

Stages

Track where companies are in your sales pipeline:

Common B2B stages:

Lead - New lead, not qualified
Prospect - Qualified prospect
Proposal - Proposal sent
Negotiation - In negotiation
Customer - Active customer
Closed Lost - Deal lost

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "Customer"
  }'

Assignment

Assign companies to specific account executives:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignedUserId": "user-uuid"
  }'

Source Tracking

Track where company leads come from:

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "LinkedIn Campaign"
  }'

Custom Fields

Extend company records with custom data fields. See Custom Fields Guide for details.

curl -X PUT https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customContractValue": 250000,
    "customRenewalDate": "2026-01-15",
    "customAccountTier": "Gold"
  }'

Deleting Companies

Endpoint: DELETE /api/partner/companies/{id}

curl -X DELETE https://api.suresend.ai/api/partner/companies/company-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN"

⚠️ Warning: Deleting a company is permanent and cannot be undone. All associated data (notes, tasks, documents, people relationships) will also be deleted.

Common Use Cases

1. Import Companies from CSV

const fs = require('fs');
const csv = require('csv-parser');
const axios = require('axios');

const API_TOKEN = process.env.API_TOKEN;
const API_URL = 'https://api.suresend.ai/api/partner';

async function importCompanies(csvFile) {
  const companies = [];

  fs.createReadStream(csvFile)
    .pipe(csv())
    .on('data', (row) => {
      companies.push({
        name: row['Company Name'],
        industry: row['Industry'],
        website: row['Website'],
        emails: [{ value: row['Email'], type: 'work', isPrimary: true }],
        phones: [{ value: row['Phone'], type: 'main', isPrimary: true }],
        companySize: row['Company Size'],
        annualRevenue: parseFloat(row['Annual Revenue']),
        source: 'CSV Import'
      });
    })
    .on('end', async () => {
      for (const company of companies) {
        try {
          await axios.post(`${API_URL}/companies`, company, {
            headers: { Authorization: `Bearer ${API_TOKEN}` }
          });
          console.log(`✓ Imported: ${company.name}`);
        } catch (error) {
          console.error(`✗ Failed: ${company.name}`, error.message);
        }
      }
    });
}

importCompanies('companies.csv');

2. Sync Companies to External System

const axios = require('axios');

const API_TOKEN = process.env.API_TOKEN;
const API_URL = 'https://api.suresend.ai/api/partner';

async function syncCompanies() {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await axios.get(`${API_URL}/companies`, {
      params: { page, limit: 100 },
      headers: { Authorization: `Bearer ${API_TOKEN}` }
    });

    const { companies, meta } = response.data;

    // Sync to your external system
    for (const company of companies) {
      await syncToExternalSystem(company);
    }

    hasMore = page < meta.total_pages;
    page++;
  }
}

async function syncToExternalSystem(company) {
  // Your sync logic here
  console.log('Syncing:', company.name);
}

syncCompanies();

3. Segment Companies by Industry

async function getCompaniesInIndustry(industry) {
  const response = await axios.get(`${API_URL}/companies`, {
    params: { industry, limit: 100 },
    headers: { Authorization: `Bearer ${API_TOKEN}` }
  });

  return response.data.companies;
}

getCompaniesInIndustry('Technology').then(companies => {
  console.log(`Found ${companies.length} tech companies`);
});

4. Identify High-Value Accounts

async function getEnterpriseAccounts() {
  let page = 1;
  let enterpriseAccounts = [];

  while (true) {
    const response = await axios.get(`${API_URL}/companies`, {
      params: { page, limit: 100 },
      headers: { Authorization: `Bearer ${API_TOKEN}` }
    });

    const { companies, meta } = response.data;

    // Filter by company size and revenue
    const filtered = companies.filter(c =>
      (c.companySize === '201-500' || c.companySize === '501-1000' || c.companySize === '5001+') &&
      c.annualRevenue >= 1000000
    );

    enterpriseAccounts = enterpriseAccounts.concat(filtered);

    if (page >= meta.total_pages) break;
    page++;
  }

  return enterpriseAccounts;
}

getEnterpriseAccounts().then(accounts => {
  console.log(`Found ${accounts.length} enterprise accounts`);
});

5. Auto-Tag Based on Company Attributes

async function autoTagCompany(companyId, company) {
  const tags = [];

  // Tag based on company size
  if (company.companySize === '5001+') {
    tags.push('major-enterprise');
  } else if (['501-1000', '1001-5000'].includes(company.companySize)) {
    tags.push('enterprise');
  }

  // Tag based on revenue
  if (company.annualRevenue >= 10000000) {
    tags.push('high-value');
  }

  // Tag based on industry
  if (company.industry === 'Technology') {
    tags.push('tech-sector');
  }

  if (tags.length > 0) {
    await axios.post(
      `${API_URL}/companies/${companyId}/tags/apply`,
      { tags },
      { headers: { Authorization: `Bearer ${API_TOKEN}` } }
    );
    console.log(`Auto-tagged company ${company.name}:`, tags);
  }
}

6. Account Health Monitoring

async function monitorAccountHealth() {
  const response = await axios.get(`${API_URL}/companies`, {
    params: { limit: 100 },
    headers: { Authorization: `Bearer ${API_TOKEN}` }
  });

  const customers = response.data.companies.filter(c =>
    c.stage === 'Customer'
  );

  for (const customer of customers) {
    // Check engagement score
    if (customer.engagementScore < 20) {
      // Apply at-risk tag
      await axios.post(
        `${API_URL}/companies/${customer.id}/tags/apply`,
        { tags: ['at-risk'] },
        { headers: { Authorization: `Bearer ${API_TOKEN}` } }
      );
      console.log(`⚠️ ${customer.name} is at risk (low engagement)`);
    } else if (customer.engagementScore > 80) {
      // Apply expansion-opportunity tag
      await axios.post(
        `${API_URL}/companies/${customer.id}/tags/apply`,
        { tags: ['expansion-opportunity'] },
        { headers: { Authorization: `Bearer ${API_TOKEN}` } }
      );
      console.log(`✨ ${customer.name} is an expansion opportunity`);
    }
  }
}

Best Practices

Data Quality

Always provide primary contact method - Mark at least one email/phone as primary
Validate email formats - Use regex or validation library before submitting
Normalize phone numbers - Use consistent format (E.164 recommended)
Keep company data current - Regularly update company information
Use consistent industry names - Standardize industry classifications

Performance

Use pagination - Don't fetch all companies at once
Batch operations - Group updates when possible
Cache frequently accessed data - Reduce API calls
Use webhooks - Get real-time updates instead of polling
Implement rate limiting - Respect API rate limits

Tagging Strategy

Use consistent naming - Lowercase with hyphens (e.g., "enterprise-account")
Create tag taxonomy - Organize tags by category
Don't over-tag - Keep tags focused and meaningful
Clean up old tags - Remove outdated or unused tags
Document tag meanings - Maintain a tag glossary

B2B Account Management

Track decision makers - Link contacts to companies
Monitor account health - Use engagement scores
Segment by company size - Target appropriately
Track revenue metrics - Update annual revenue regularly
Identify expansion opportunities - Tag high-potential accounts

Security

Never expose API tokens - Keep tokens secret
Use environment variables - Don't hardcode credentials
Rotate tokens regularly - Create new tokens periodically
Limit token scope - Use team-specific tokens when possible
Monitor API usage - Watch for suspicious activity

Error Handling

Common Errors

404 Not Found:

{
  "errorMessage": "Company not found"
}

422 Validation Error:

{
  "errorMessage": "Name can't be blank"
}

429 Rate Limit:

{
  "errorMessage": "Rate limit exceeded",
  "retry_after": 3600
}

Error Handling Example

async function createCompany(data) {
  try {
    const response = await axios.post(`${API_URL}/companies`, data, {
      headers: { Authorization: `Bearer ${API_TOKEN}` }
    });
    return response.data;
  } catch (error) {
    if (error.response) {
      switch (error.response.status) {
        case 422:
          console.error('Validation error:', error.response.data.errorMessage);
          break;
        case 429:
          const retryAfter = error.response.data.retry_after;
          console.error(`Rate limited. Retry after ${retryAfter} seconds`);
          break;
        case 401:
          console.error('Invalid API token');
          break;
        default:
          console.error('API error:', error.response.data.errorMessage);
      }
    } else {
      console.error('Network error:', error.message);
    }
    throw error;
  }
}

Next Steps

Learn about People API to track contacts at companies
Set up Webhooks for real-time company updates
Explore Custom Fields to extend company data
Check Events API to track company interactions

Need Help?

API Reference: See full Companies endpoints in sidebar
Support: [email protected]
Examples: Check our GitHub examples (coming soon)