Announcements

Get an announcement

Returns one announcement with its full text, its attachments, and every recipient it was addressed to.

GET

https://api.portal.magicdoor.com/company-app/announcements/{announcementId}

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

announcementIdstringrequired

The announcement to fetch.

example: 1831291846747709440

Response

200 · The announcement.

idstring

The announcement.

companyIdstring

The company that sent it.

subjectstring

The subject line used for the email. Up to 250 characters.

chatMessagestring

The text posted into each recipient's chat and sent as an SMS.

emailMessagestring

The body of the email that was sent.

sendTextboolean

Whether the chat message was also sent as an SMS.

sentAtstring · date-time

When the announcement went out, or is due to go out if it is still scheduled.

statusenum<string>

pending means it is scheduled and has not gone out yet. partiallyFailed means some recipients got it and some did not.

pendingsentpartiallyFailedfailed

failureReasonstring

How many recipients failed, when any did. Absent on a clean send.

chatAttachmentsFile[]

Files attached to the chat message and the SMS.

emailAttachmentsFile[]

Files attached to the email.

targetsobject

Who it went to.

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

404 · No announcement with that id belongs to your company.

targets groups the recipients: leases and their tenants hang under portfolio, then property, then unit; owners, vendors, and tenants addressed directly sit at the top level.

canDeliver and blockReasons on each recipient are evaluated when you preview a send. On an announcement that has already gone out they are not re-evaluated, so canDeliver reads true with no reasons.

Request

curl --request GET \
  --url 'https://api.portal.magicdoor.com/company-app/announcements/1831291846747709440' \
  --header 'Authorization: Bearer <token>'

Response

{
  "id": "1831291846747709440",
  "companyId": "1810119284757463040",
  "subject": "Water shut-off Thursday",
  "chatMessage": "Water will be off Thursday 9am to 1pm for a repair.",
  "emailMessage": "<p>Water will be off Thursday 9am to 1pm for a repair.</p>",
  "sendText": true,
  "sentAt": "2026-08-17T14:05:00",
  "status": "sent",
  "targets": {
    "targetTypes": [
      "lease"
    ],
    "portfolioTargets": [
      {
        "portfolio": {
          "id": "1823772785993383936",
          "name": "Boise Residential",
          "active": true,
          "propertyCount": 6,
          "icons": []
        },
        "properties": [
          {
            "property": {
              "id": "1824559920033832960",
              "name": "Willow Creek",
              "displayName": "Willow Creek",
              "portfolioId": "1823772785993383936",
              "type": "multiFamily",
              "address": {
                "streetAddress1": "1420 Willow Creek Rd",
                "city": "Boise",
                "state": "ID",
                "zipCode": "83702",
                "country": "US",
                "isValid": true
              },
              "unitCount": 12,
              "recentRentalApplications": 2,
              "active": true,
              "icons": []
            },
            "units": [
              {
                "unit": {
                  "id": "1828440183928913920",
                  "name": "4B",
                  "propertyId": "1824559920033832960",
                  "portfolioId": "1823772785993383936",
                  "address": {
                    "streetAddress1": "1420 Willow Creek Rd",
                    "city": "Boise",
                    "state": "ID",
                    "zipCode": "83702",
                    "country": "US",
                    "isValid": true
                  },
                  "beds": 2,
                  "baths": 1,
                  "marketRent": 1850,
                  "active": true,
                  "icons": []
                },
                "tenants": [
                  {
                    "id": "1827991044238376960",
                    "active": true,
                    "firstName": "Marcus",
                    "lastName": "Webb",
                    "email": "marcus.webb@example.com",
                    "phone": "(208) 555-0117",
                    "language": "en",
                    "chatId": "1830472847398404096",
                    "portalStatus": "active",
                    "lastSeen": "2026-08-16T19:41:07",
                    "icons": [],
                    "created": "2026-02-11T10:05:33",
                    "updated": "2026-07-30T16:22:09",
                    "canDeliver": true,
                    "blockReasons": []
                  }
                ],
                "leases": [
                  {
                    "id": "1829833104612495360",
                    "portfolioId": "1823772785993383936",
                    "propertyId": "1824559920033832960",
                    "unitId": "1828440183928913920",
                    "start": "2026-03-01",
                    "end": "2027-02-28",
                    "ended": false,
                    "monthToMonth": false,
                    "eviction": false,
                    "draft": false,
                    "status": "lease",
                    "expiringStatus": "none",
                    "chatId": "1830472847398404096",
                    "tenants": [
                      {
                        "tenantId": "1827991044238376960",
                        "moveIn": "2026-03-01"
                      }
                    ],
                    "balance": 0,
                    "postedBalance": 0,
                    "currentRent": 1850,
                    "securityDepositRequested": 1850,
                    "securityDepositPaid": 1850,
                    "securityDepositDue": 0,
                    "lastPaymentDate": "2026-08-01",
                    "icons": [],
                    "canDeliver": true,
                    "blockReasons": []
                  }
                ],
                "vendors": [],
                "owners": []
              }
            ]
          }
        ]
      }
    ],
    "tenants": [],
    "owners": [],
    "vendors": []
  }
}