Surveys

Get a survey

Fetches one survey with its questions and their options. Requires the hoa_surveys:read permission.

GET

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

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.

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.

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

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

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

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

A draft's questions are not yet tied to the survey

Questions are bound to their survey when it is published. While a survey is still Draft, its question list is resolved across every unpublished question in the company — so if you keep two drafts open at once, both will show both sets of questions. Publish a draft before relying on its question list, or keep one draft at a time.

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.