# SimpL Agent API — plain text for agents You decide and approve. SimpL queues and guards. The human's Chrome extension executes on LinkedIn. Base: https://api.simpl.sucks/api/agent/v1 Auth: Authorization: Bearer sk_agent_... OpenAPI: https://api.simpl.sucks/api/agent/v1/openapi.json Manifest: https://api.simpl.sucks/api/agent/v1/.well-known/simpl-agent.json Human setup: https://sales.thesimplplatform.io/?appTab=profile&tab=integrations Chrome extension: https://chromewebstore.google.com/detail/simpl/noigjbkhonhmbhfbpghgjlfpieefjldh HTML docs: https://www.simplsales.ai/docs/agents ## Start here (for the person) SimpL works with your own AI agent: it reads what SimpL found for you and what waits for your approval, and acts only when you say so. It needs an agent that can call web APIs, such as Claude Code, Cursor, n8n or Make. A plain chat in ChatGPT or Claude cannot reach SimpL. 1. Let the agent connect: give your agent this page. It shows you a link and a code; open the link, sign in to SimpL, check the code and approve. 2. Or make a key yourself: in SimpL, Settings → Integrations → Agent API → Create a key. Copy the text shown under the key and paste it into your agent. Each agent gets its own key. Revoke one any time in Settings → Integrations; it stops at once. ## Connect an existing account Preferred when the human already has SimpL. Do not POST /access-requests for existing accounts. 1. POST /oauth/device with { client_name, label } 2. Open verification_uri_complete for the human (or tell them to open it) 3. They log in and click Allow 4. Poll POST /oauth/device/token with { device_code } until api_key POST /oauth/device POST /oauth/device/token - Or the human makes a key in Settings → Integrations → Agent API and pastes it to you, with a ready-made prompt - Store the key once — it is not shown again ## Onboard a new account Use only when the human does not have SimpL yet. Send a full onboarding packet — not just name and email. 1. POST /access-requests with email, full_name, company_name, product_offer, value_proposition, icp_brief, industries[], geographies[], size_min, size_max, target_roles[], signals[], example_outreach_messages[], decision_maker_guidance, outreach_context 2. Poll GET /access-requests/{id} about once per minute (poll_after_seconds ≈ 60). Expect up to ~15 minutes 3. On approved: POST /access-requests/{id}/claim with claim_token → api_key (once) 4. Meanwhile tell the human: accept the invite email, open Integrations, install the Chrome extension, stay logged into LinkedIn POST /access-requests GET /access-requests/{id} POST /access-requests/{id}/claim ## Readiness gate Mandatory before approving LinkedIn drafts. You approve; the extension sends. GET /readiness GET /readiness?wait_seconds=60 - If ready is false, do not approve LinkedIn drafts - POST /drafts/{id}/approve returns 409 linkedin_not_ready with blockers and agent_instructions - Relay message_for_user to your human, then wait with wait_seconds=60 (held open until ready, max 90s) - Blocking: extension_not_seen, extension_access_disabled, linkedin_url_missing, user_on_vacation - Informational: outside_active_hours (07:00–19:00 UTC), daily_limit_reached, linkedin_sync_stale ## Day board Totals only — opportunities by row type, drafts by channel, activity by status, limits. Call this before paging lists. GET /board GET /me - If ready=false, coach Integrations (blockers[].action_url) — do not deep-page the backlog - No item bodies on the board ## Daily loop Page filtered slices only. returned/count is the page; summary/total is the corpus. POST /icp/preview · POST /icp · PATCH /icp/{id} POST /opportunities/refresh · GET /opportunities POST /opportunities/{company_id}/claim|monitor|not-in-target GET /drafts · GET /drafts/{id} PATCH /drafts/{id} · POST /drafts/{id}/regenerate POST /drafts/{id}/approve|reject GET /activity - Filter lists with message_type, channel, newer_than_days, row_type, status - Every draft has kind: message (yours to approve), calendar_invite (approved on its card in the app) or question (SimpL asks the human: read question.text and question.options and tell them; they answer in the app — approve/reject answer 409 answer_in_app, bulk lists them under questions) - Drafts and activity say who and where: lead_name, lead_job_title, lead_linkedin_url, company_name, company_website, company_linkedin_url, stage. No contact details beyond LinkedIn - GET /activity and the board's activity totals cover the last 90 days; older history is not available through the API - Default draft list uses message_preview; prefer GET /drafts/{id} for one review - Draft status: PENDING_APPROVAL → approve → PENDING → extension RUNNING → COMPLETED/FAILED - Pass include_summary=false on follow-up pages — the summary aggregate is the slow part ## Bulk draft actions One call per draft does not scale. Use bulk endpoints with explicit ids and/or filters. POST /drafts/bulk-approve POST /drafts/bulk-reject - Filters: channel, message_type, newer_than_days, older_than_days; max_items default 50, hard cap 200 - A call with neither ids nor filters returns 400 unfiltered_bulk - Run dry_run: true first on a broad filter - Retries are safe — only PENDING_APPROVAL rows move - Keep calling while remaining_after_call > 0 - bulk-approve enforces the same readiness gate as single approve ## Limits and ownership Rate limits and human key control. - 120 requests per 60s per key — 429 carries Retry-After and retry_after_seconds - If you are hitting the limit, use bulk endpoints, include_summary=false, and filtered pages - Keys expire 365 days after issue unless revoked earlier - Humans list and revoke keys in Settings → Integrations — revocation is immediate - OpenAPI is the source of truth for request bodies ## Do not - Do not claim LinkedIn sends without GET /readiness ready=true — you approve, the extension executes - Do not POST /access-requests for humans who already have SimpL — use device OAuth - Do not download thousands of drafts — filter and page - Do not run unfiltered bulk actions - Do not use internal service tokens — only sk_agent_ keys Scopes: icp:write, opportunities:read, pipeline:write, drafts:read, drafts:approve, activity:read Rate limit: 120 requests per 60s per key Keys expire 365 days after issue unless revoked earlier Contract: You decide and approve. SimpL queues. The extension sends.