REST API¶

Askalot provides a REST API for programmatic access to all platform capabilities. The API enables you to automate survey workflows, integrate with external systems, and build custom applications on top of the Askalot platform.

Getting Started¶

Base URL¶

https://portor.<tenant>.askalot.io/api

Replace <tenant> with your organization's tenant name (e.g., portor.acme.askalot.io).

Authentication¶

All API requests require authentication using a personal API token.

Generating a Token:

Log in to https://roundtable.<tenant>.askalot.io
Navigate to Profile Settings
Scroll to "API Tokens" section
Click "Generate New Token"
Copy the token (shown only once)

Keep Your Token Secure

API tokens provide full access to your account. Never share tokens or commit them to version control.

Using Your Token:

Include your token in the X-Api-Token header:

curl -H "X-Api-Token: your_token_here" \
  https://portor.<tenant>.askalot.io/api/projects

Token Properties:

Configurable expiration (30 days, 90 days, 1 year, or never)
Inherits your account's roles and permissions
Can be revoked at any time from Profile Settings
Works with both REST API and MCP interface (same token, different header format)

Unified Access

The same API token works for both the REST API and the MCP interface. Use X-Api-Token header for REST API calls, and Authorization: Bearer header for MCP connections.

Interactive Documentation¶

Explore the API interactively using Swagger UI at:

https://portor.<tenant>.askalot.io/api/docs

The interactive documentation lets you:

Browse all available endpoints
View request/response schemas
Test API calls directly in your browser

Core Resources¶

Projects¶

Projects are top-level containers for organizing your survey research.

Method	Endpoint	Description
`GET`	`/api/projects`	List all projects
`POST`	`/api/projects`	Create a new project
`GET`	`/api/projects/{id}`	Get project by ID
`PUT`	`/api/projects/{id}`	Update a project
`DELETE`	`/api/projects/{id}`	Delete a project

Example: Create a Project

curl -X POST https://portor.<tenant>.askalot.io/api/projects \
  -H "X-Api-Token: your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Satisfaction Study",
    "description": "Q1 2026 customer feedback survey"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Customer Satisfaction Study",
  "description": "Q1 2026 customer feedback survey",
  "created_at": "2026-01-02T10:30:00Z",
  "questionnaire_ids": [],
  "campaign_ids": []
}

Questionnaires¶

Questionnaires define survey structure using QML (Questionnaire Markup Language).

Method	Endpoint	Description
`GET`	`/api/questionnaires`	List all questionnaires
`POST`	`/api/questionnaires`	Create a new questionnaire
`GET`	`/api/questionnaires/{id}`	Get questionnaire by ID
`PUT`	`/api/questionnaires/{id}`	Update a questionnaire
`DELETE`	`/api/questionnaires/{id}`	Delete a questionnaire

Query Parameters:

project_id - Filter by project
status - Filter by status (draft, active, paused, completed)

Campaigns¶

Campaigns link questionnaires to respondents for data collection.

Method	Endpoint	Description
`GET`	`/api/campaigns`	List all campaigns
`POST`	`/api/campaigns`	Create a new campaign
`GET`	`/api/campaigns/{id}`	Get campaign by ID
`PUT`	`/api/campaigns/{id}`	Update a campaign
`DELETE`	`/api/campaigns/{id}`	Delete a campaign
`PUT`	`/api/campaigns/{id}/pool`	Assign a respondent pool to the campaign
`GET`	`/api/campaigns/{id}/pool`	Get the campaign's assigned pool

Query Parameters:

project_id - Filter by project
questionnaire_id - Filter by questionnaire
status - Filter by status
expand=true - Include related objects (project, questionnaire, respondents)

Campaign Modes:

Askalot supports two campaign modes:

Direct Mode: Respondents complete surveys independently via unique links
Interviewer-Assisted Mode: Interviewers administer surveys to respondents by phone or in person

The mode is determined automatically based on whether interviewers are assigned to the campaign.

Respondents¶

Respondents are the survey targets—the people being surveyed.

Method	Endpoint	Description
`GET`	`/api/respondents`	List all respondents
`POST`	`/api/respondents`	Create a new respondent
`GET`	`/api/respondents/{id}`	Get respondent by ID
`PUT`	`/api/respondents/{id}`	Update a respondent
`DELETE`	`/api/respondents/{id}`	Delete a respondent

Query Parameters:

source_system - Filter by source (e.g., crm, panel_provider)
campaign_id - Filter by campaign

Note: Interviewers are Users with the interviewer role. They are managed through the /api/users endpoint.

Example: Import a Respondent

curl -X POST https://portor.<tenant>.askalot.io/api/respondents \
  -H "X-Api-Token: your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "[email protected]",
    "age": 35,
    "gender": "female",
    "location": "New York",
    "external_id": "CRM-12345",
    "source_system": "salesforce"
  }'

Demographics Fields:

Respondents support demographic data for targeting and analysis:

age - Respondent age
gender - Gender identity
location - Geographic location
external_id - Your system's identifier
source_system - Source of the respondent data

Surveys¶

Surveys track individual survey sessions and responses.

Method	Endpoint	Description
`GET`	`/api/surveys`	List all surveys
`POST`	`/api/surveys`	Create a new survey session
`GET`	`/api/surveys/{id}`	Get survey by ID
`PUT`	`/api/surveys/{id}`	Update survey status
`DELETE`	`/api/surveys/{id}`	Delete a survey

Query Parameters:

questionnaire_id - Filter by questionnaire
campaign_id - Filter by campaign
status - Filter by status (in_progress, complete)
expand=true - Include related objects

Respondent Pools¶

Respondent pools organize respondents into reusable groups for campaigns.

Method	Endpoint	Description
`GET`	`/api/respondent-pools`	List all respondent pools
`POST`	`/api/respondent-pools`	Create a new pool
`GET`	`/api/respondent-pools/{id}`	Get pool by ID
`PUT`	`/api/respondent-pools/{id}`	Update a pool
`DELETE`	`/api/respondent-pools/{id}`	Delete a pool
`POST`	`/api/respondent-pools/{id}/respondents`	Add respondents to pool
`DELETE`	`/api/respondent-pools/{id}/respondents`	Remove respondents from pool

Query Parameters:

project_id - Filter by project

Sampling Strategies¶

Sampling strategies define target demographic distributions for creating representative samples.

Method	Endpoint	Description
`GET`	`/api/sampling-strategies`	List all strategies
`POST`	`/api/sampling-strategies`	Create a new strategy
`GET`	`/api/sampling-strategies/{id}`	Get strategy by ID
`PUT`	`/api/sampling-strategies/{id}`	Update a strategy
`DELETE`	`/api/sampling-strategies/{id}`	Delete a strategy

Query Parameters:

project_id - Filter by project

Example: Create a Sampling Strategy

curl -X POST https://portor.<tenant>.askalot.io/api/sampling-strategies \
  -H "X-Api-Token: your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Representative Sample",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "target_size": 100,
    "factors": [
      {
        "name": "Gender",
        "attribute_path": "gender",
        "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}
      },
      {
        "name": "Age Group",
        "attribute_path": "age",
        "factor_type": "bucketed",
        "target_distribution": {"18-34": 0.35, "35-54": 0.40, "55+": 0.25}
      }
    ]
  }'

Response Format¶

Success Responses¶

All successful responses return JSON with standard HTTP status codes:

Status	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`204 No Content`	Resource deleted successfully

Error Responses¶

Errors include a descriptive message:

{
  "error": "Project not found",
  "code": 404
}

Validation Errors:

{
  "error": "Validation failed",
  "code": 400,
  "errors": {
    "name": ["Field is required"],
    "email": ["Invalid email format"]
  }
}

OpenAPI Specification¶

The complete API specification is available in OpenAPI 3.0 format:

GET /api/openapi.json

Use this specification to generate typed API clients in your preferred programming language.

Common Workflows¶

Automating Campaign Creation¶

# 1. Create a project
PROJECT_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/projects \
  -H "X-Api-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 Survey"}' | jq -r '.id')

# 2. Create a questionnaire
QUESTIONNAIRE_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/questionnaires \
  -H "X-Api-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Customer Feedback\", \"qml_name\": \"feedback.qml\", \"project_id\": \"$PROJECT_ID\"}" | jq -r '.id')

# 3. Create a campaign
curl -X POST https://portor.<tenant>.askalot.io/api/campaigns \
  -H "X-Api-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Q1 Campaign\", \"project_id\": \"$PROJECT_ID\", \"questionnaire_id\": \"$QUESTIONNAIRE_ID\"}"

Importing Respondents from Your CRM¶

# Import respondents from a CSV or your CRM system
for respondent in "${RESPONDENTS[@]}"; do
  curl -X POST https://portor.<tenant>.askalot.io/api/respondents \
    -H "X-Api-Token: $TOKEN" \
    -H "Content-Type: application/json" \
    -d "$respondent"
done

Next Steps¶

MCP Interface

Enable AI agents to interact with the platform

MCP Docs
Creating Surveys

Learn QML syntax for questionnaire design

Guide
Campaign Management

Configure and launch survey campaigns

Targetor Guide