MagicDoorAPI
SupportOpen MagicDoor
Surveys

Publish a survey

Opens a draft survey for responses and fixes who may answer it. Requires the hoa_surveys:write permission.

POST
https://services.magicdoor.com/hoa/company-portal/associations/surveys/{surveyId}/publish

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.

Path parameters

surveyIdstringrequired

The survey to act on.

example: 1830472847398410240

Response

200 · The survey, now `Open`.

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 · The survey is not `Draft`, or it has no questions.

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.

404 · No survey with that id belongs to the calling company.

Legal from `Draft` only

A survey that is already Open or Closed returns 400 Bad Request with the detail Only draft surveys can be published. There is no endpoint that turns a published survey back into a draft.

What publishing does

Publishing binds the questions to the survey, so from here on its question list is its own. It also decides who counts as a respondent:

  • BoardMembers — everyone holding an active board seat at the moment you publish is recorded as eligible. Appointing or deactivating a board member afterwards does not change that list, and it is what eligibleCount and the response rate are measured against.
  • CommunityMembers — no eligible list is recorded, so the survey's results report an eligibleCount of 0 and a response rate of 0.
`closesAt` does not close it

The date is carried onto the vote so the owner portal can show it, but nothing closes the survey automatically. Call Close a survey when you are ready to stop taking responses.

`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.