---
title: "Surveys API"
description: "Create and check surveys from JSON. In private preview; draft shape."
url: https://developer.tendralhealth.com/docs/early-access/surveys-api
---

# Surveys API

Create and check surveys from JSON. The Surveys API is in **private preview**: these endpoints are not served yet, and a call to one returns `404`.

> **Draft — may change.** Everything on this page describes the intended shape. Field names and behaviour can change before release, without notice.

## Planned endpoints

| Endpoint | What it will do |
| --- | --- |
| `POST /v1/surveys` | Create a survey from JSON. It is saved as a draft. |
| `POST /v1/surveys/validate` | Check survey JSON without saving it. Returns the question count or field-level errors. |
| `GET /v1/uploads/presign` | Get a short-lived upload URL for a PDF a survey case refers to. |

## Question types

A survey's `questions` take these types, the same ones Tendral's survey importer accepts today: `text`, `single-choice`, `multiple-choice`, `scale`, `yes-no`, `number`, `maxdiff`, `compound`.

## Example request body

```json Draft request
{
  "title": "Managing hypertension in primary care",
  "briefDescription": "12 minutes",
  "format": "standard",
  "estimatedTime": {
    "min": 10,
    "max": 14
  },
  "incentive": 75,
  "questions": [
    {
      "type": "single-choice",
      "text": "How often do you use home blood pressure readings to adjust treatment?",
      "options": [
        "Never",
        "Rarely",
        "Sometimes",
        "Often",
        "Always"
      ],
      "required": true
    },
    {
      "type": "scale",
      "text": "How confident are you choosing a second agent when one drug is not enough?",
      "points": 5,
      "labels": {
        "start": "Not confident",
        "end": "Very confident"
      },
      "required": true
    }
  ],
  "targeting": {
    "audiences": [
      {
        "name": "Family medicine",
        "specialtyCodes": [
          "207Q00000X"
        ],
        "states": [
          "CA",
          "NY",
          "TX"
        ],
        "quota": 50
      }
    ]
  }
}
```

## Get access

The preview is open to organizations we work with directly. [Request access](https://tendralhealth.com/contact) and tell us what you want to build.