API Documentation

Programmatic access to Auggie's AI-powered account research.

Quick Start

from auggie import AuggieClient
client = AuggieClient("aug_your_key")
result = client.research_and_poll("https://example.com")

Install: pip install auggie

Python SDK

The official Python SDK wraps the REST API with convenient helpers for polling and error handling.

Installation

pip install auggie

Basic Usage

Submit a research job and poll until completion:

from auggie import AuggieClient

client = AuggieClient("aug_your_key")

# Research a company (blocks until complete)
result = client.research_and_poll("https://example.com")

print(result["scores"]["composite"])          # Overall score
print(result["scores"]["pain"])               # Pain score
print(result["scores"]["pain_categories"])    # {"security": 72, "engineering": 85, ...}
print(result["scores"]["pain_signals"][0])    # Top pain signal with severity + confidence
print(result["sections"]["talking_points"])   # Ready-to-use talking points

Bulk Research

urls = ["https://example.com", "https://acme.com", "https://widgets.io"]
bulk = client.bulk_research(urls, name="Q1 prospects")

# Poll until all complete
result = client.poll_bulk(bulk["bulk_job_id"])
for item in result["items"]:
    print(f"{item['company_url']}: {item['status']}")

Error Handling

from auggie import AuggieClient, AuggieError

client = AuggieClient("aug_your_key")

try:
    result = client.research_and_poll("https://example.com")
except AuggieError as e:
    print(f"Error {e.status_code}: {e.message}")
    # e.status_code — HTTP status (401, 402, 422, 429, etc.)
    # e.message — Human-readable error description

Getting Started

Base URL for all API requests:

https://auggie.app/v1

How it works

  1. Create an API key at /api-keys.
  2. Submit a company URL via POST /v1/research. This returns a job_id immediately.
  3. Poll for results via GET /v1/research/{job_id}, or register a webhook to be notified when the job completes.
  4. Generate outreach via POST /v1/research/{doc_id}/sequence using the completed document.

Authentication

All API requests require a Bearer token. Create API keys at /api-keys.

Include the key in the Authorization header:

Authorization: Bearer aug_your_api_key_here

Keys are shown once on creation. Store them securely — they cannot be retrieved later.

Understanding Scores

Every research result includes four scores from 0-100, plus a composite score that combines them.

Score types

Score Weight What it measures
pain 40% How much pain the company is likely experiencing in areas your product solves
fit 35% How well the company matches your ideal customer profile (ICP)
timing 25% Signals that the company is ready to buy now (hiring, funding, tech changes)
composite — Weighted combination: (pain × 0.4) + (fit × 0.35) + (timing × 0.25)

Score calibration

Range Interpretation
85-100 Very high. Strong, clear signals detected. Prioritize these accounts.
70-84 High. Good signals detected. Worth pursuing with personalized outreach.
50-69 Moderate. Some signals present. May need further qualification.
0-49 Low. Weak or absent signals. Likely not a strong fit right now.

Pain categories

Pain is broken down into five categories. Each category score (0-100) represents the highest-confidence signal detected in that area.

Category What it covers
security SSL gaps, auth fragmentation, compliance gaps, email authentication risk
engineering Tech debt, scaling pressure, database bottlenecks, frontend performance
operations Multi-cloud complexity, tool sprawl, observability gaps, hiring bottlenecks
marketing Identity fragmentation, tag bloat, marketing/product tech mismatch
data Data infrastructure growing pains, ETL/pipeline complexity

Pain signals

The pain_signals array contains machine-readable signals detected by the pain inference engine. Each signal includes:

{
  "title": "Database Scaling Pressure",
  "severity": "high",
  "confidence": 85,
  "category": "engineering"
}

Signals are sorted by confidence (highest first). Use these to filter accounts by specific pain types or build custom scoring models.

Research

POST /v1/research

Start an async research job. Returns immediately with a job ID. Costs 1 credit.

Request body

{
  "company_url": "https://example.com"
}

Response 202

{
  "job_id": 42,
  "status": "processing"
}

curl example

curl -X POST https://auggie.app/v1/research \
  -H "Authorization: Bearer aug_your_key" \
  -H "Content-Type: application/json" \
  -d '{"company_url": "https://example.com"}'
GET /v1/research/{job_id}

Poll for job status. Returns the full research document when completed.

Response — processing

{
  "job_id": 42,
  "status": "processing",
  "company_url": "https://example.com",
  "created_at": "2026-01-28T12:00:00",
  "completed_at": null
}

Response — completed

{
  "job_id": 42,
  "status": "completed",
  "company_url": "https://example.com",
  "created_at": "2026-01-28T12:00:00",
  "completed_at": "2026-01-28T12:01:30",
  "document_id": 15,
  "company_name": "Example Inc",
  "scores": {
    "composite": 78,
    "pain": 85,
    "fit": 72,
    "timing": 80,
    "summary": "Strong fit with active pain points.",
    "pain_evidence": [
      "Database scaling issues with PostgreSQL",
      "4 open backend engineering roles",
      "No observability tooling detected"
    ],
    "pain_categories": {
      "engineering": 85,
      "security": 72,
      "operations": 60
    },
    "pain_signals": [
      {
        "title": "Database Scaling Pressure",
        "severity": "high",
        "confidence": 85,
        "category": "engineering"
      },
      {
        "title": "Security Posture Gap",
        "severity": "medium",
        "confidence": 72,
        "category": "security"
      }
    ]
  },
  "sections": {
    "company_overview": "...",
    "projects_initiatives": "...",
    "confirmed_tech_stack": "...",
    "hiring_signals": "...",
    "business_problems": "...",
    "existential_data_points": "...",
    "product_fit": "...",
    "talking_points": "...",
    "recent_news": "...",
    "key_contacts": "...",
    "information_gaps": "..."
  }
}

curl example

curl https://auggie.app/v1/research/42 \
  -H "Authorization: Bearer aug_your_key"
GET /v1/research

List your recent research jobs.

Response

{
  "jobs": [
    {
      "job_id": 42,
      "company_url": "https://example.com",
      "status": "completed",
      "document_id": 15,
      "error": null,
      "created_at": "2026-01-28T12:00:00",
      "completed_at": "2026-01-28T12:01:30"
    }
  ]
}

curl example

curl https://auggie.app/v1/research \
  -H "Authorization: Bearer aug_your_key"

Sequences

POST /v1/research/{doc_id}/sequence

Generate a 3-email outreach sequence from a completed research document. Requires a completed document ID.

Response

{
  "success": true,
  "document_id": 15,
  "emails": [
    {
      "email_number": 1,
      "subject": "Quick question about your stack",
      "body": "Hi ..."
    },
    {
      "email_number": 2,
      "subject": "Following up",
      "body": "Hi ..."
    },
    {
      "email_number": 3,
      "subject": "Last note",
      "body": "Hi ..."
    }
  ]
}

curl example

curl -X POST https://auggie.app/v1/research/15/sequence \
  -H "Authorization: Bearer aug_your_key"

Bulk Research

Research multiple companies in a single request. Up to 100 URLs per batch, processed concurrently. Credits are reserved upfront and refunded for any failures.

POST /v1/research/bulk

Start a bulk research job. Returns immediately with a bulk job ID. Costs 1 credit per URL.

Request body

{
  "company_urls": [
    "https://example.com",
    "https://acme.com",
    "https://widgets.io"
  ],
  "name": "Q1 prospects"
}

Response 202

{
  "bulk_job_id": 7,
  "status": "processing",
  "total_items": 3
}

curl example

curl -X POST https://auggie.app/v1/research/bulk \
  -H "Authorization: Bearer aug_your_key" \
  -H "Content-Type: application/json" \
  -d '{"company_urls": ["https://example.com", "https://acme.com"], "name": "Q1 prospects"}'
GET /v1/research/bulk/{bulk_job_id}

Get bulk job progress and all items with their status.

Response

{
  "bulk_job_id": 7,
  "name": "Q1 prospects",
  "status": "completed",
  "total_items": 3,
  "completed_items": 2,
  "failed_items": 1,
  "credits_reserved": 300,
  "created_at": "2026-01-28T12:00:00",
  "completed_at": "2026-01-28T12:05:00",
  "items": [
    {
      "id": 1,
      "company_url": "https://example.com",
      "status": "completed",
      "research_job_id": 50,
      "document_id": 20,
      "error": null,
      "created_at": "2026-01-28T12:00:00",
      "completed_at": "2026-01-28T12:01:30"
    }
  ]
}

curl example

curl https://auggie.app/v1/research/bulk/7 \
  -H "Authorization: Bearer aug_your_key"
GET /v1/research/bulk

List your recent bulk jobs (summaries only, no items).

Response

{
  "bulk_jobs": [
    {
      "bulk_job_id": 7,
      "name": "Q1 prospects",
      "status": "completed",
      "total_items": 3,
      "completed_items": 2,
      "failed_items": 1,
      "created_at": "2026-01-28T12:00:00",
      "completed_at": "2026-01-28T12:05:00"
    }
  ]
}

curl example

curl https://auggie.app/v1/research/bulk \
  -H "Authorization: Bearer aug_your_key"

Lists

Create persistent lists of companies, trigger bulk analysis, then query accounts with score filtering and sorting. Credits are reserved upfront and refunded for failures.

POST /v1/lists

Create a named list of company URLs. Set analyze: true to immediately start researching all accounts (1 credit each).

Request body

{
  "name": "Q1 Targets",
  "company_urls": ["https://example.com", "https://acme.com"],
  "analyze": true
}

Response 201

{
  "list_id": 5,
  "name": "Q1 Targets",
  "status": "analyzing",
  "total_accounts": 2
}

curl example

curl -X POST https://auggie.app/v1/lists \
  -H "Authorization: Bearer aug_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 Targets", "company_urls": ["https://example.com", "https://acme.com"], "analyze": true}'
POST /v1/lists/{list_id}/analyze

Trigger analysis on pending accounts in a list. Use this if you created a list without analyze: true, or to re-analyze accounts that haven't been processed yet.

Response 202

{
  "list_id": 5,
  "status": "analyzing",
  "pending_accounts": 2
}

curl example

curl -X POST https://auggie.app/v1/lists/5/analyze \
  -H "Authorization: Bearer aug_your_key"
GET /v1/lists/{list_id}

Get list details and accounts with optional filtering and sorting.

Query parameters

Parameter Description
min_pain_score Filter accounts with pain score ≥ value
min_composite_score Filter accounts with composite score ≥ value
sort_by Sort field: pain_score, composite_score, fit_score, timing_score, company_name
order asc or desc (default: desc)
limit Max accounts to return (default: 100)
offset Pagination offset (default: 0)

Response

{
  "list_id": 5,
  "name": "Q1 Targets",
  "status": "completed",
  "total_accounts": 50,
  "analyzed_accounts": 48,
  "failed_accounts": 2,
  "accounts": [
    {
      "id": 1,
      "company_url": "https://example.com",
      "company_name": "Example Inc",
      "status": "completed",
      "document_id": 15,
      "pain_score": 85,
      "fit_score": 72,
      "timing_score": 80,
      "composite_score": 78,
      "analyzed_at": "2026-01-28T12:01:30"
    }
  ]
}

curl example

curl "https://auggie.app/v1/lists/5?min_pain_score=70&sort_by=pain_score&order=desc" \
  -H "Authorization: Bearer aug_your_key"
GET /v1/lists

List your recent lists (summaries only, no accounts).

Response

{
  "lists": [
    {
      "list_id": 5,
      "name": "Q1 Targets",
      "status": "completed",
      "total_accounts": 50,
      "analyzed_accounts": 48,
      "failed_accounts": 2,
      "created_at": "2026-01-28T12:00:00",
      "updated_at": "2026-01-28T12:05:00"
    }
  ]
}

curl example

curl https://auggie.app/v1/lists \
  -H "Authorization: Bearer aug_your_key"
DELETE /v1/lists/{list_id}

Delete a list and all its accounts. Returns 204 on success.

curl example

curl -X DELETE https://auggie.app/v1/lists/5 \
  -H "Authorization: Bearer aug_your_key"

Webhooks

Register a webhook URL to receive notifications when research jobs complete, instead of polling.

POST /v1/webhooks/register

Register or update your webhook URL. Returns a secret for HMAC signature verification.

Request body

{
  "url": "https://yourserver.com/webhook"
}

Response

{
  "url": "https://yourserver.com/webhook",
  "secret": "a1b2c3...hex...",
  "active": true
}

curl example

curl -X POST https://auggie.app/v1/webhooks/register \
  -H "Authorization: Bearer aug_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourserver.com/webhook"}'
GET /v1/webhooks

Get your current webhook configuration.

Response

{
  "url": "https://yourserver.com/webhook",
  "active": true
}

curl example

curl https://auggie.app/v1/webhooks \
  -H "Authorization: Bearer aug_your_key"
DELETE /v1/webhooks

Remove your webhook. Returns 204 on success.

curl example

curl -X DELETE https://auggie.app/v1/webhooks \
  -H "Authorization: Bearer aug_your_key"

Verifying webhook signatures

Each webhook delivery includes an X-Auggie-Signature header containing an HMAC-SHA256 hex digest. Verify it using the secret returned at registration:

import hashlib, hmac, json

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """Verify an Auggie webhook signature."""
    body = json.dumps(
        json.loads(payload),
        separators=(",", ":"),
        sort_keys=True
    ).encode()
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Clay Integration

Use Auggie as an HTTP enrichment column in Clay to automatically research companies in your table. The dedicated /v1/clay/enrich endpoint runs synchronously and returns a flat response optimized for Clay column mapping.

Important: Set your Clay HTTP column timeout to 120 seconds. Research typically completes in 30-60 seconds, but complex companies may take longer.

POST /v1/clay/enrich

Synchronous enrichment endpoint. Runs the full research pipeline and returns a flat JSON response. Includes 24-hour caching — re-enriching the same company within 24h returns the cached result at no credit cost. Rate limited to 5 requests per 60 seconds.

Request body

{
  "company_url": "{{/Company Website}}"
}

Response

{
  "success": true,
  "company_name": "Acme Corp",
  "company_url": "https://acme.com",
  "pain_score": 87,
  "fit_score": 75,
  "timing_score": 82,
  "composite_score": 82,
  "score_summary": "Strong pain signals...",
  "pain_reasons": "PostgreSQL scaling + 4mo backend role...",
  "business_problems": "...",
  "product_fit": "...",
  "talking_points": "...",
  "existential_data_points": "...",
  "pain_category_security": 72,
  "pain_category_engineering": 87,
  "pain_category_operations": 60,
  "pain_category_marketing": null,
  "pain_category_data": null,
  "top_pain_signal": "Database Scaling Pressure",
  "document_id": 1523,
  "cached": false,
  "research_duration_seconds": 47.32,
  "error": null
}

curl example

curl -X POST https://auggie.app/v1/clay/enrich \
  -H "Authorization: Bearer aug_your_key" \
  -H "Content-Type: application/json" \
  -d '{"company_url": "https://example.com"}'

Field mapping

All response fields are flat — no nested paths needed. Map these fields in Clay:

Field Description
pain_score Pain score (0-100)
composite_score Overall opportunity score (0-100)
fit_score ICP fit score (0-100)
timing_score Buying timing score (0-100)
score_summary One-line score explanation
pain_reasons Key pain signals identified
business_problems Identified business problems
product_fit Product fit analysis
talking_points Ready-to-use talking points
pain_category_security Security pain score (0-100, null if none detected)
pain_category_engineering Engineering pain score (0-100, null if none detected)
pain_category_operations Operations pain score (0-100, null if none detected)
pain_category_marketing Marketing pain score (0-100, null if none detected)
pain_category_data Data infrastructure pain score (0-100, null if none detected)
top_pain_signal Title of highest-confidence pain signal
document_id Document ID (use with sequence endpoint)

You can also use the async POST /v1/research endpoint with polling if you prefer — see Research above.

Full step-by-step Clay guide →

Integrations

Auggie connects to your sales tools so you can push sequences and contacts directly from your lists. Connect integrations from the Integrations page.

One-click integrations

These integrations connect with a single click via OAuth. No API key needed.

Outreach

Click Connect, sign in to Outreach, and authorize Auggie. Sequences are pushed as Outreach sequences with email steps.

SalesLoft

Click Connect, sign in to SalesLoft, and authorize Auggie. Sequences are pushed as SalesLoft cadences.

ZoomInfo

Click Connect and sign in to ZoomInfo. Used for company search and list import.

API key integrations

These integrations require an API key from the provider. Here's where to find each one.

Apollo

Used for list import, firmographic enrichment, and pushing sequences.

  1. Log in to app.apollo.io
  2. Click your avatar in the bottom-left corner, then Settings
  3. Navigate to Integrations → API Keys in the left sidebar
  4. Click Create API Key, select Master Key, give it a name, and copy the key
  5. Paste the master key into the Apollo field on the Integrations page

Instantly

Used for pushing enriched contacts to Instantly campaigns.

  1. Log in to app.instantly.ai
  2. Click the Settings gear icon in the left sidebar
  3. Go to API under the Integrations section
  4. Copy your API key (or generate one if you haven't already)
  5. Paste the key into the Instantly field on the Integrations page

Smartlead

Used for pushing enriched contacts to Smartlead campaigns.

  1. Log in to app.smartlead.ai
  2. Click your profile icon in the top-right corner
  3. Select Settings, then go to API Keys
  4. Copy your API key
  5. Paste the key into the Smartlead field on the Integrations page

People Data Labs

Used for company search by industry, size, and location.

  1. Sign up or log in at peopledatalabs.com
  2. Go to Dashboard → API Keys
  3. Copy your API key
  4. Paste the key into the People Data Labs field on the Integrations page

Automation Platforms

Use Auggie's REST API in any automation tool that supports HTTP requests. See our dedicated guides for step-by-step setup:

n8n

n8n

Step-by-step guide with webhook & polling workflows, bulk import, and node-by-node setup.

 Make

Make

Step-by-step guide with webhook & polling scenarios, bulk import, and module-by-module setup.

 Zapier

Zapier

Step-by-step guide with webhook & polling Zaps, bulk import, and step-by-step setup.

Error Codes

Status Meaning
401 Missing or invalid API key.
402 No credits remaining. Purchase more at /billing/buy-credits.
404 Resource not found (job, document, or webhook).
422 Invalid request body or company URL (e.g., private IP, malformed URL).
429 Rate limit exceeded. Check the Retry-After header.

Rate Limits

Limits are per API key, using a sliding window. Exceeding a limit returns 429 with a Retry-After header.

Endpoint Group Limit
POST /v1/clay/enrich 5 requests / 60 seconds
POST /v1/research, POST /v1/enrich 10 requests / 60 seconds
POST /v1/research/bulk, POST /v1/lists, POST /v1/lists/{id}/analyze 2 requests / 60 seconds
POST /v1/research/{id}/sequence 20 requests / 60 seconds
All other endpoints (GET /v1/research, GET /v1/ping, webhooks) 60 requests / 60 seconds

Resources

Clay Problem-Signal Prospecting Guide

Step-by-step guide to using Auggie with Clay for problem-signal prospecting.

API Keys

Create and manage your API keys, view usage statistics.