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.

ScopeAllowsNew keys
read:projectsRead projects, quota progress, dispositions and respondent completesOn
read:panelRead your own panel members (emails masked)On
read:usageRead monthly completes per clientOn
piiShow member emails and names unmasked (needs read:panel)Off
write:projectsReserved 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 project
    POST /projects/{id}/status with the write:projects scope.
  • Create projects
    Create 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

1. Route

Panelist clicks survey link in Pathos Panel dashboard

2. Survey

Panelist is redirected to your survey tool with a unique session ID

3. Callback

Survey tool redirects back to Pathos Panel with completion status

4. Reward

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:

Complete
https://www.pathospanel.com/api/survey/end?rst=complete&rid=[RID]
Terminate / Screenout
https://www.pathospanel.com/api/survey/end?rst=terminate&rid=[RID]
Quota Full
https://www.pathospanel.com/api/survey/end?rst=quota_full&rid=[RID]
SM

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}
Q

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}
A

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}

Need help integrating?

Write to us and we will help you get set up.

Contact support