API Documentation
The Pathos Panel API is read only for now: your projects with their quotas and dispositions, respondent outcomes by RID, your own panel members and your monthly completes. Every endpoint returns JSON and uses standard HTTP status codes. Everything listed here is live; planned endpoints are under Coming soon.
Authentication
Create an API key in your account under API keys (an account manager switches API access on). Send it with every request as a bearer token, or in the X-API-Key header. The full key is shown once, when you create it; we store only a hash.
curl https://www.pathospanel.com/api/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY"Each key carries scopes. A request needs the scope its endpoint names; without it the answer is 403.
| Scope | Allows | New keys |
|---|---|---|
read:projects | Read projects, quota progress, dispositions and respondent completes | On |
read:panel | Read your own panel members (emails masked) | On |
read:usage | Read monthly completes per client | On |
pii | Show member emails and names unmasked (needs read:panel) | Off |
write:projects | Reserved for project write endpoints (none are live yet) | Off |
Errors are { "error": { "code", "message" } }: 401 for a missing, unknown, revoked or expired key; 403 for a missing scope; 404 for anything that is not yours; 429 over the rate limit. A key of an account that manages other client accounts also reads those accounts; pass client_id to pick one.
Projects
Projects, quotas, dispositions and respondent outcomes.
Panel
Your own panel members.
Usage
Monthly completes.
Webhooks
Register HTTPS endpoints on the Webhooks page of your account. Each endpoint picks the events it receives and has its own signing secret, shown once when it is created or rotated. Every delivery is a JSON POST with the headers `X-Webhook-Event`, `X-Webhook-Delivery`, `X-Webhook-Attempt` and `X-Webhook-Signature: sha256=<hex>`, where `<hex>` is the HMAC-SHA256 of the raw request body keyed with your signing secret. Answer with any 2xx status. Other answers and timeouts (10 seconds) are retried up to 5 times with growing delays. Events only ever cover your own projects.
Coming soon
Planned, not available yet. Do not build against these.
- Pause and resume a projectPOST /projects/{id}/status with the write:projects scope.
- Create projectsCreate and launch a project from your own systems.
Integration Guides
Connect Pathos Panel with your preferred survey platform. Each integration uses redirect URLs to track survey completions, terminations, and quota-full events.
How Survey Integration Works
Panelist clicks survey link in Pathos Panel dashboard
Panelist is redirected to your survey tool with a unique session ID
Survey tool redirects back to Pathos Panel with completion status
Pathos Panel awards points and updates project stats
Redirect / Callback URLs
Configure these URLs in your survey tool to redirect panelists back to Pathos Panelafter they finish (or are screened out of) your survey:
https://www.pathospanel.com/api/survey/end?rst=complete&rid=[RID]https://www.pathospanel.com/api/survey/end?rst=terminate&rid=[RID]https://www.pathospanel.com/api/survey/end?rst=quota_full&rid=[RID]SurveyMonkey
Step 1: Create your survey in SurveyMonkey
Design your questionnaire as you normally would.
Step 2: Enable Custom Variables
Go to Collect → Web Link → Custom Variables and add a variable named rid.
Step 3: Configure Redirect URLs
Under Collect → Web Link → Survey end page, select "Redirect to your own webpage" and enter:
Complete: https://www.pathospanel.com/api/survey/end?rst=complete&rid=[rid_value]
Disqualify: https://www.pathospanel.com/api/survey/end?rst=terminate&rid=[rid_value]
Quota: https://www.pathospanel.com/api/survey/end?rst=quota_full&rid=[rid_value]Step 4: Create Project in Pathos Panel
Use your SurveyMonkey collector URL as the survey URL, with ?rid={RID} appended.
https://www.surveymonkey.com/r/YOURSURVEY?rid={RID}Qualtrics
Step 1: Add Embedded Data
In your Survey Flow, add an Embedded Data element at the top with a field named rid.
Step 2: Configure End-of-Survey Redirect
Go to Survey options → Survey termination → Custom end-of-survey message. Use "Redirect to a URL" and pipe the Embedded Data:
Complete URL:
https://www.pathospanel.com/api/survey/end?rst=complete&rid=${e://Field/rid}
Screenout URL (Survey Flow > Branch Logic > End of Survey element):
https://www.pathospanel.com/api/survey/end?rst=terminate&rid=${e://Field/rid}
Quota Full URL (Quotas > Over Quota Options):
https://www.pathospanel.com/api/survey/end?rst=quota_full&rid=${e://Field/rid}Step 3: Create Project in Pathos Panel
Use your Qualtrics distribution link as the survey URL:
https://yourorg.qualtrics.com/jfe/form/SV_XXXX?rid={RID}Alchemer (SurveyGizmo)
Step 1: Add URL Variable
Go to Tools → URL Variables and create a variable named rid.
Step 2: Configure Redirect Actions
In Survey Settings → Results → Redirect Upon Completion:
Complete redirect:
https://www.pathospanel.com/api/survey/end?rst=complete&rid=[url("rid")]
For Disqualify/Screenout pages, add a URL Redirect action:
https://www.pathospanel.com/api/survey/end?rst=terminate&rid=[url("rid")]
For Quota actions:
https://www.pathospanel.com/api/survey/end?rst=quota_full&rid=[url("rid")]Step 3: Create Project in Pathos Panel
Use your Alchemer survey link with the rid parameter:
https://survey.alchemer.com/s3/XXXXXXX/YourSurvey?rid={RID}