API Access

Programmatic control of your surveys

API Access

Access your survey data and manage surveys programmatically. Build custom integrations, automate workflows, and connect Srvey to your applications.

Getting Started

Create an API Token

  1. Go to Team Settings > API Tokens
  2. Click "Create Token"
  3. Name your token (e.g., "Production Server")
  4. Select abilities (permissions)
  5. Optionally set an expiration date
  6. Copy and store the token securely (it will not be shown again)

Authentication

Include your token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

All API requests must also include:

Accept: application/json

Token Abilities

When creating a token, you can grant specific abilities:

Ability Description Endpoints
Full Access Complete access to all endpoints All
surveys:read List and view survey details GET /surveys, GET /surveys/{id}
surveys:write Create, update, delete surveys POST, PUT, DELETE /surveys
responses:read View survey responses GET /surveys/{id}/responses
responses:write Submit and manage responses POST, PUT, DELETE /responses
invitations:read List survey invitations GET /surveys/{id}/invitations
invitations:write Create survey invitations POST /surveys/{id}/invitations

API Endpoints

Surveys

Method Endpoint Description Ability Required
GET /api/v1/surveys List all surveys (paginated) surveys:read
GET /api/v1/surveys/{id} Get survey with sections surveys:read
POST /api/v1/surveys Create a new survey surveys:write
PUT /api/v1/surveys/{id} Update an existing survey surveys:write
DELETE /api/v1/surveys/{id} Delete a survey surveys:write

Responses

Method Endpoint Description Ability Required
GET /api/v1/surveys/{id}/responses List responses (paginated) responses:read
GET /api/v1/surveys/{id}/responses/{response} Get a specific response responses:read
POST /api/v1/surveys/{id}/responses Create a new response responses:write
PUT /api/v1/surveys/{id}/responses/{response} Update a response responses:write
DELETE /api/v1/surveys/{id}/responses/{response} Delete a response responses:write

Invitations

Method Endpoint Description Ability Required
GET /api/v1/surveys/{id}/invitations List invitations invitations:read
GET /api/v1/surveys/{id}/invitations/{token} Get invitation by token invitations:read
POST /api/v1/surveys/{id}/invitations Create an invitation invitations:write

Rate Limiting

API requests are rate limited to 120 requests per minute per token.

When rate limited, the API returns 429 Too Many Requests.

Pagination

List endpoints return paginated results:

Parameter Default Range Description
page 1 1+ Page number
per_page 15 1-100 Items per page

Response Format

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 150
  }
}

Filtering

Survey Filters

Filter surveys by status:

GET /api/v1/surveys?status=draft
GET /api/v1/surveys?status=active
GET /api/v1/surveys?status=closed

Error Handling

Errors return appropriate HTTP status codes:

Status Description
400 Bad request (invalid parameters)
401 Unauthorized (invalid or missing token)
403 Forbidden (insufficient permissions)
404 Not found
422 Validation error
429 Rate limit exceeded
500 Server error

Example Request

curl -X GET "https://srvey.io/api/v1/surveys" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json"

Example Response

{
    "data": [
        {
            "id": 1,
            "name": "Customer Feedback",
            "status": "active",
            "default_language": "en",
            "created_at": "2024-01-15T10:30:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 1
    }
}

Token Management

Viewing Tokens

The API Tokens page shows:

  • Token name and prefix
  • Granted abilities
  • Expiration date (if set)
  • Last used timestamp
  • Creation date

Revoking Tokens

To revoke a token:

  1. Go to API Tokens
  2. Find the token in the list
  3. Click "Revoke"
  4. Confirm the action

Revoked tokens immediately lose API access.

Token Expiration

Tokens can be set to expire on a specific date. Expired tokens are marked in the list and cannot be used for API access.

Plan Availability

Feature Free Pro Business Enterprise
API access - - Read Full
Token creation - - Yes Yes
Read endpoints - - Yes Yes
Write endpoints - - - Yes

API access requires the api_access feature. Business plans get read-only access; Enterprise plans get full read/write access.

Best Practices

  • Use specific abilities - Grant only the permissions needed
  • Set expiration dates - For temporary integrations
  • Rotate tokens regularly - Create new tokens and revoke old ones
  • Store securely - Never commit tokens to version control
  • Monitor usage - Check "Last Used" to identify unused tokens