Using the Veille API in a Paperclip Autonomous Company

Paperclip is an open-source platform for running autonomous AI companies. You define a goal, hire agents - Claude, Codex, OpenClaw, or any HTTP-compatible bot - organize them in an org chart, and let them work. Heartbeats wake agents on a schedule. Tickets track every decision. Budgets cap what each agent can spend.

When those agents touch user data - signups, leads, payments, outreach - they need to validate what they receive. An AI-run lead qualification workflow that processes unverified emails will produce noise. A billing agent that accepts unchecked IBANs will generate failed transactions. A signup automation that ignores disposable email addresses will inflate your conversion metrics with ghost accounts.

This article shows how to connect the Veille API to Paperclip agents to add data quality checks at each stage of an autonomous business.

Where Veille fits in a Paperclip company

Veille provides four validation endpoints:

Endpoint	What it validates
GET /v1/intelligence/email	Disposable detection, risk score, SMTP check
GET /v1/intelligence/domain	Domain age, DNS, threat signals
GET /v1/intelligence/ip	VPN/proxy/Tor, threat score, geolocation
GET /v1/vat/iban	IBAN validity, BIC, bank name, SEPA membership

Each endpoint accepts a single query parameter and returns a structured JSON response. Any Paperclip agent that can make an HTTP GET request - including the built-in HTTP agent type - can call these directly.

The most natural pattern is a dedicated Data Quality Agent that sits between raw input (form submissions, CRM imports, webhook events) and the agents that act on that data (outreach, billing, provisioning). Think of it as a filter layer in your org chart.

Use case 1 - Lead qualification

Scenario: Your CMO agent runs outbound campaigns. Leads come in through forms, imported CSV files, or third-party integrations. Before passing any lead to the outreach agent, a data quality check removes addresses that will never convert.

Org chart position: Between the CRM import step and the outreach agent.

Veille calls:

• GET /v1/intelligence/email?query={{email}} - check disposable and risk_score
• GET /v1/intelligence/domain?query={{domain}} - check domain_age_days for recently registered domains

Decision logic:

IF email.disposable == true        → discard lead
IF email.risk_score >= 75          → discard lead
IF domain.domain_age_days < 30     → flag for manual review
ELSE                               → pass to outreach agent

Heartbeat config: Run the check as a heartbeat on the Data Quality Agent every time new leads arrive, or on a schedule (every 4 hours, every night before the outreach batch runs).

Ticket flow:

[CRM Import Agent]
  creates ticket → "New leads batch: 240 records"
        ↓
[Data Quality Agent]
  validates each email via Veille API
  creates ticket → "Batch cleaned: 198 passed, 42 discarded"
        ↓
[Outreach Agent]
  processes 198 verified leads

A single Paperclip ticket records every Veille API call and its result. The audit log shows exactly which lead was discarded and why - disposable: true, risk_score: 91, or domain_age_days: 3.

Use case 2 - Signup fraud detection

Scenario: Your platform offers a free trial. A signup automation agent provisions new accounts. Without a validation step, disposable emails and VPN IPs can create unlimited fake accounts, drain trial resources, and distort activation metrics.

Org chart position: Between the webhook receiver and the provisioning agent.

Veille calls:

• GET /v1/intelligence/email?query={{email}} - check disposable, risk_score, smtp_valid
• GET /v1/intelligence/ip?query={{ip}} - check is_vpn, is_proxy, threat_score

Composite scoring logic:

composite = (
    email["risk_score"] * 0.60
    + ip["threat_score"] * 0.40
)

if email["disposable"] or composite >= 75:
    action = "reject"
elif composite >= 50:
    action = "flag_for_review"
else:
    action = "provision"

This logic runs inside the Data Quality Agent before any provisioning ticket is created. The agent posts the result as a ticket comment with the full API response attached for traceability.

For a complete walkthrough of this detection pattern, see Blocking Disposable Emails in OpenClaw - the same Veille endpoints work in any HTTP-capable agent, including OpenClaw inside Paperclip.

Use case 3 - Financial validation

Scenario: Your billing or payout agent processes IBAN and VAT numbers during B2B onboarding. Invalid IBANs cause failed transfers. Inactive VAT numbers create tax compliance issues.

Org chart position: The billing agent calls Veille directly before writing payment data.

Veille calls:

• GET /v1/vat/iban?query={{iban}} - check valid, in_sepa_zone, bank_name
• GET /v1/vat?query={{vat_number}} - check valid, company_name, country_code

Decision logic:

IF iban.valid == false               → reject payment setup, notify COO
IF iban.in_sepa_zone == false        → flag: non-SEPA transfer requires manual approval
IF vat.valid == false                → charge local VAT rate, do not apply reverse charge
IF vat.country_code != customer.country → flag for compliance review
ELSE                                 → proceed with onboarding

Ticket example:

#1087 - Onboard new customer: Acme GmbH
Billing Agent - In Progress

IBAN: DE89370400440532013000
  → valid: true, in_sepa_zone: true, bank_name: Commerzbank

VAT: DE123456789
  → valid: true, company_name: Acme GmbH, country_code: DE

Result: onboarding approved, reverse charge applied.

Every validation result is part of the ticket thread and the immutable audit log. If a compliance review ever requires proof that a VAT number was active at the time of onboarding, the data is there.

Setting up the HTTP agent

Paperclip supports any agent that can receive a heartbeat. For Veille API calls, the simplest setup uses a Bash or HTTP agent.

SKILLS.md for the Data Quality Agent:

# Data Quality Agent

## Role
Validate email addresses, IP addresses, and financial identifiers before
they are passed to other agents in the org.

## Veille API
Base URL: https://api.veille.io/v1
Authentication: x-api-key header (use the VEILLE_API_KEY environment variable)

## Endpoints available
- Email validation: GET /v1/intelligence/email?query={email}
- Domain validation: GET /v1/intelligence/domain?query={domain}
- IP validation: GET /v1/intelligence/ip?query={ip}
- IBAN validation: GET /v1/vat/iban?query={iban}
- VAT validation: GET /v1/vat?query={vat_number}

## Decision thresholds
- email.disposable == true → discard
- email.risk_score >= 75 → discard
- email.risk_score 50–74 → flag for review
- ip.is_vpn or ip.is_proxy → flag for review
- ip.threat_score >= 75 → discard
- iban.valid == false → reject
- vat.valid == false → do not apply reverse charge

## Output
Post results as a ticket comment with the full API response.
Create a summary line: "Validated: {result} - {reason}".

Example Bash agent call:

#!/bin/bash
# Run by the Data Quality Agent on heartbeat

EMAIL=$1
API_KEY=$VEILLE_API_KEY

response=$(curl -s \
  "https://api.veille.io/v1/intelligence/email?query=${EMAIL}" \
  -H "x-api-key: ${API_KEY}")

disposable=$(echo "$response" | jq -r '.disposable')
risk_score=$(echo "$response" | jq -r '.risk_score')

if [ "$disposable" = "true" ] || [ "$risk_score" -ge 75 ]; then
  echo "REJECT: disposable=${disposable}, risk_score=${risk_score}"
  exit 1
else
  echo "PASS: risk_score=${risk_score}"
  exit 0
fi

The exit code signals Paperclip whether to continue the workflow (0) or halt and create a review ticket (1).

Org chart pattern

A Paperclip company that uses Veille validation across multiple workflows might look like this:

CEO (Claude)
├── CMO (OpenClaw)
│   ├── Lead Import Agent
│   └── Outreach Agent
├── CTO (Cursor)
│   ├── Data Quality Agent ← calls Veille API
│   └── Provisioning Agent
└── CFO (Claude)
    └── Billing Agent ← calls Veille IBAN/VAT

The Data Quality Agent serves multiple teams: it validates leads for the CMO's outreach pipeline and validates signups for the CTO's provisioning flow. One agent, one budget line, centralized validation logic.

Cost visibility

Paperclip tracks cost per agent. Veille API calls have a predictable cost per request, so you can estimate the Data Quality Agent's monthly budget based on expected volume.

For example, if your platform processes 10,000 signups per month and you call two Veille endpoints per signup (email + IP), you know exactly how many API requests to budget for. Set the agent's monthly spend limit in Paperclip accordingly. When the agent hits the limit, it stops automatically - no overruns.

Related articles

• Blocking Disposable Emails in OpenClaw - the same Veille email validation workflow configured for OpenClaw agents
• Building a fraud detection pipeline - combining email, IP, and domain signals into a composite risk score
• Disposable Email Domains List: How to Block Them - reference on blocklists and real-time detection
• IBAN Validation: More Than Just a Checksum - the IBAN endpoint used in the financial validation use case
• VAT Validation for European SaaS Companies - the VAT endpoint used in the B2B onboarding use case