MagicDoorAPI
SupportOpen MagicDoor
Surveys

Create a survey

Writes a new survey and its questions. It starts as a draft, so nobody can answer it until you publish it. Requires the hoa_surveys:write permission.

POST
https://services.magicdoor.com/hoa/company-portal/associations/surveys

Authorization

Authorizationstringrequired
Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Body

application/json

titlestringrequired

The survey's title. At most 200 characters.

descriptionstringrequired

What the survey is about. At most 4000 characters.

audiencestringrequired

Who the survey is for, spelled exactly as shown.

BoardMembersCommunityMembers
closesAtstring · date-time

When the survey should close. Send an ISO 8601 timestamp with an offset, for example 2026-09-16T09:00:00-04:00. Omit it and it is set 30 days out.

questionsobject[]required

At least one question.

Response

200 · The new survey, as a draft.

idstring

The survey. A 64-bit id sent as a decimal string.

titlestring

The survey's title.

descriptionstring

What the survey is about.

audiencestring

BoardMembers polls the seated board; CommunityMembers polls the wider community.

BoardMembersCommunityMembers
statusstring

Draft while it is being written, Open once published, Closed once responses are shut off.

DraftOpenClosed
closesAtstring · date-time

When the survey is scheduled to close, in the company's timezone. Set to 30 days out when the survey is created without one, and it cannot be cleared afterwards.

questionsobject[]

The survey's questions, sorted by order.

responseCountinteger

Always 0 on this endpoint — it is not computed here. Read the survey's results for the real number.

eligibleCountinteger

Never returned by this endpoint, so it is always absent. Read the survey's results for it.

createdstring · date-time

When the survey was created, in the company's timezone.

updatedstring · date-time

When the survey last changed, in the company's timezone.

400 · `title` or `description` is blank or too long, `questions` is empty, two questions share an `order`, a `MultipleChoice` question has fewer than two options, a `YesNo` or `FreeText` question carries options, or `audience`/`type` is not one of the listed values.

401 · The bearer token is missing, expired, or not valid.

403 · The token is valid but the caller does not hold the `hoa_surveys:write` permission.

Question rules

TypeOptions
YesNoMust not be sent. The answer is a yes or a no.
MultipleChoiceAt least two, each with a unique order.
FreeTextMust not be sent. The answer is typed text.

order has to be unique across the questions in one survey, and unique across the options within one question. Nothing requires the numbers to start at 1 or run without gaps — they are only used for sorting.

`responseCount` is always zero here

This endpoint returns the survey shape with responseCount hard-set to 0 and eligibleCount omitted, whatever the real numbers are. Call Get survey results when you need them, or read them off the list.

These values are case-sensitive

audience, status, and a question's type are plain strings here, not the camelCase enumerations used elsewhere in the API. They are matched exactly as written — BoardMembers works, boardMembers gets 400 Bad Request.