PayPilot API
Live demoGitHub
HomeGuidesSDKsContext PluginAPI Reference
Growth

Run opportunity detection

POST
/api/v1/opportunities/detect

Runs the deterministic detector and upserts the results. Idempotent: re-running refreshes existing opportunities rather than duplicating them, and never rolls back an opportunity a human has already acted on.

Authorization

HTTPBearer
AuthorizationBearer <token>

JWT access token

In: header

Query Parameters

merchant_id?|

Optional merchant to act on. Must be one you are a member of.

Formatuuid

Header Parameters

X-Merchant-ID?string|null

Request Body

application/json

days?integer
Range7 <= value <= 180
Default30
force?boolean
Defaultfalse

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/opportunities/detect" \  -H "Content-Type: application/json" \  -d '{}'
{  "data": {    "generated_at": "2019-08-24T14:15:22Z",    "open_count": 0,    "opportunities": [      {        "agent_run_id": "c3317f32-e28b-4af1-a584-86ac8c788dd8",        "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",        "confidence": 0,        "created_at": "2019-08-24T14:15:22Z",        "detected_at": "2019-08-24T14:15:22Z",        "effort": "HIGH",        "estimated_value_monthly": 0,        "evidence": [          {            "change": "string",            "confidence": 0,            "detail": "string",            "metric": "string",            "reference": "string",            "source": "analytics",            "value": "string"          }        ],        "experiment_id": "916afd89-cac5-4339-9c59-dd068abdfa69",        "graph_path": [          "string"        ],        "hypothesis": "",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "impact": "HIGH",        "key": "string",        "kind": "string",        "period_end": "2019-08-24",        "period_start": "2019-08-24",        "priority_score": 0,        "reasoning": "",        "recommended_action": "",        "requires_approval": true,        "risk": "string",        "status": "DETECTED",        "summary": "string",        "tags": [          "string"        ],        "target_segment": {},        "title": "string",        "updated_at": "2019-08-24T14:15:22Z"      }    ],    "provenance": {      "data_source": "SEEDED",      "is_simulated": true,      "note": "Seeded demo dataset - not computed from a live PayPal merchant account."    },    "total_detected": 0,    "total_estimated_value_monthly": 0  },  "meta": {},  "success": true}

Add an opportunity by hand POST

For something the detector cannot see - a lease ending, a competitor closing, a supplier deal. It behaves like any detected opportunity from here on: it can be approved, turned into a campaign and measured. The nightly detection pass upserts by key and never touches a manual one.

Opportunity detail GET

Opportunity detail.