# A2PCheck — full agent reference

> A2PCheck is an independent A2P 10DLC campaign-readiness checker. Agents use it to
> validate a campaign draft against common Twilio / TCR / carrier rejection patterns
> BEFORE submitting it through a provider.

## Core rule

Agents should not submit A2P 10DLC campaigns blindly. The flow is:
1. Build the campaign as JSON (schema below).
2. Strip any PII or secrets — send public metadata and public URLs only.
3. POST it to /api/agent/validate.
4. Read overallTier + criticalIssues + fieldResults.
5. Remediate RED/YELLOW findings, re-validate, loop until GREEN.
6. Hand the cleared draft back to the human to submit through their provider.

## Caveats (do not misrepresent)

- Independent. Not affiliated with, endorsed by, or operated by Twilio, The Campaign
  Registry, or any wireless carrier.
- Does not submit campaigns. Users submit through their own provider.
- Does not guarantee approval. Only the official carrier/TCR review approves a campaign.
- Not legal advice or a compliance certification.
- Never send real end-user phone numbers, customer records, API keys, provider tokens,
  or signed/internal URLs. Campaign metadata and public URLs only.

## Endpoints

Base URL: https://www.a2pcheck.com

### POST /api/agent/validate  (stable agent surface)

JSON-only. Forwards to the same scan engine as the web app.
Request body:
  {
    "tier": "basic" | "full",   // optional, default "basic". "full" crawls URLs (~15-20s).
    "campaign": { ...ScanRequest... },   // required, see Campaign schema
    "campaignName": "string",   // optional, <=200 chars, for your own audit trail
    "idempotencyKey": "string"  // optional, <=128 chars, dedupes repeat authed calls
  }
Auth: optional. Without a token you get anonymous basic validation (rate-limited; fixes may be locked).
For full/headless use, create a self-serve key at https://www.a2pcheck.com/dashboard/api-keys
and send it as `Authorization: Bearer a2p_live_...`; scans then spend that account's credits.
Returns: a scan result object (see Response fields). Errors are JSON (see Errors).

### POST /api/scan  (browser/app surface)

Used by the web UI. Same engine, richer envelope (attribution, campaignId, source).
Body: { tier: 'basic'|'full', request: ScanRequest, ... }. Prefer /api/agent/validate
for programmatic agent use; /api/scan is documented for completeness.

## Campaign schema (ScanRequest)

Required:
  useCaseType        string    e.g. MARKETING, MIXED, CUSTOMER_CARE, 2FA, ACCOUNT_NOTIFICATION
  campaignDescription string   what you send, to whom, and why (most-rejected field)
  sampleMessages     string[]  2-5 real examples; include brand + opt-out + rate disclosure
  messageFlow        string    how recipients opt in (the consent path)
Optional:
  businessName       string
  privacyPolicyUrl   string    public URL, crawled on full tier
  websiteUrl         string    public URL, crawled on full tier
  termsOfServiceUrl  string    public URL
  optInKeywords      string[]  e.g. ["START"]
  optOutKeywords     string[]  e.g. ["STOP"]
  helpKeywords       string[]  e.g. ["HELP"]
  optInMessage       string
  optOutMessage      string
  helpMessage        string
  embeddedLinks         boolean
  embeddedPhoneNumbers  boolean
  ageGatedContent       boolean
  directLending         boolean
  numberPool            boolean

## Response fields

  scanId          string         scanner id
  overallTier     RED|YELLOW|GREEN   readiness verdict (RED = likely rejected)
  overallSummary  string
  criticalIssues  []{ severity, message, twilioErrorCode }   campaign-wide blockers
  warnings        []{ severity, message }                    campaign-wide risks
  fieldResults    []{ field, displayName, tier, rationale, issues[], suggestions[] }
  suggestions     []{ issue, fix, example? }   (inside each fieldResult)
  suggestedUpdates []{ field, suggestedValue, rationale }   structured rewrites (may be locked)
  metadata        { scanDurationMs, fieldsAnalyzed, urlsCrawled[], quickScan? }

## Errors

All errors are JSON: { error: { code, message, details?, retryAfterSeconds?, traceId } }
  BAD_REQUEST      400   malformed body / invalid tier / missing campaign
  AUTH_REQUIRED    401   this scan tier needs a signed-in account or developer API key
  ANON_SCAN_LIMIT  429   anonymous per-IP daily limit hit (see retryAfterSeconds)
  INVALID_API_KEY 401   developer API key is missing, unknown, or revoked
  INSUFFICIENT_CREDITS 402   account needs more scan credits
  SCAN_FAILED      5xx   upstream scan failure (retry later)

## Skill assets

An agent skill package lives in the source repo under skill/ (generic),
skills/hermes/ (Hermes variant), and .agents/skills/a2pcheck/ (mirror). It is not
yet published to a skills registry. Pages:
- https://www.a2pcheck.com/agents
- https://www.a2pcheck.com/openclaw-a2pcheck-skill
- https://www.a2pcheck.com/claude-code-a2p-registration