Surveys

Update a survey

Rewrites a draft survey. Every field is optional — send only what changes. Requires the hoa_surveys:write permission.

PUT

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

Body

application/json

Anything you leave out keeps its current value. There is no way to clear a field back to empty.

titlestring

The survey's title.

descriptionstring

What the survey is about.

audiencestring

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.

questionsobject[]

Questions to rewrite or add. Send a question's id to rewrite it, and leave the id off to add a new one. A question you do not list is left exactly as it is — nothing here deletes a question. Omit questions entirely to change only the survey's own fields.

Response

200 · The updated draft, with the questions from this call.

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`, `questions` was sent but empty, 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.

404 · No survey with that id belongs to the calling company, or a question or option `id` in the body does not exist.

Drafts only

A published or closed survey returns 400 Bad Request with the detail Only draft surveys can be edited. Once a survey is Open its wording is fixed.

`questions` adds and rewrites — it never deletes

A question you leave out of the array is not removed from the survey; there is no endpoint that deletes a question. Options behave the other way round: within a question you send, any existing option you do not list is deleted, and changing that question's type deletes all of its options. Leave a question's options out entirely to keep them untouched.

The response shows only what you sent

questions in the response lists the questions from this call, not the survey's whole set. Read the survey back to see everything on it.

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.

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