Invitation API

Invite users to an organization, check invitation status, and respond to invitations.

Endpoints

Method	Path	Description
GET	/api/invitations/invite-status	Check invitation status
GET	/api/invitations/respond	Accept or decline an invitation
GET	/api/invitations/:orgId/list	List all invitations for an org
GET	/api/invitations/:orgId/:invitationId	Get invitation by ID

Path Parameters

Parameter	Type	Description
orgId	string	Organization ID
invitationId	string	Invitation ID

Query Parameters

Endpoint	Parameter	Type	Description
invite-status	token	string	Invitation token
invite-status	email	string	Invitee email address
respond	token	string	Invitation token
respond	email	string	Invitee email address
respond	action	string	accept or decline

---

Check Invitation Status

GET /api/invitations/invite-status?token=abc123&email=rahul@example.com

Response — 200 OK

{
  "success": true,
  "data": {
    "_id": "665d4e5f6a7b8c9d0e1f2a3b",
    "email": "rahul@example.com",
    "orgId": {
      "_id": "663f1a2b3c4d5e6f7a8b9c0d",
      "name": "Grand Palace Hotel"
    },
    "role": {
      "_id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Front Desk"
    },
    "status": "pending",
    "invitedBy": {
      "_id": "665c3d4e5f6a7b8c9d0e1f2b",
      "name": "Priya Patel"
    },
    "expiresAt": "2026-03-02T10:00:00.000Z",
    "createdAt": "2026-02-23T10:00:00.000Z"
  }
}

---

Respond to Invitation

GET /api/invitations/respond?token=abc123&email=rahul@example.com&action=accept

Response — 200 OK (accepted)

{
  "success": true,
  "message": "Invitation accepted successfully",
  "data": {
    "_id": "665d4e5f6a7b8c9d0e1f2a3b",
    "email": "rahul@example.com",
    "status": "accepted",
    "respondedAt": "2026-02-23T11:00:00.000Z"
  }
}

Response — 200 OK (declined)

{
  "success": true,
  "message": "Invitation declined",
  "data": {
    "_id": "665d4e5f6a7b8c9d0e1f2a3b",
    "email": "rahul@example.com",
    "status": "declined",
    "respondedAt": "2026-02-23T11:00:00.000Z"
  }
}

---

List Invitations

GET /api/invitations/:orgId/list

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "_id": "665d4e5f6a7b8c9d0e1f2a3b",
      "email": "rahul@example.com",
      "role": {
        "_id": "665b2c3d4e5f6a7b8c9d0e1f",
        "name": "Front Desk"
      },
      "status": "accepted",
      "invitedBy": {
        "_id": "665c3d4e5f6a7b8c9d0e1f2b",
        "name": "Priya Patel"
      },
      "expiresAt": "2026-03-02T10:00:00.000Z",
      "createdAt": "2026-02-23T10:00:00.000Z"
    },
    {
      "_id": "665d4e5f6a7b8c9d0e1f2a3c",
      "email": "neha@example.com",
      "role": {
        "_id": "665b2c3d4e5f6a7b8c9d0e20",
        "name": "Housekeeping"
      },
      "status": "pending",
      "invitedBy": {
        "_id": "665c3d4e5f6a7b8c9d0e1f2b",
        "name": "Priya Patel"
      },
      "expiresAt": "2026-03-02T10:00:00.000Z",
      "createdAt": "2026-02-23T10:05:00.000Z"
    }
  ]
}

---

Get Invitation by ID

GET /api/invitations/:orgId/:invitationId

Response — 200 OK

{
  "success": true,
  "data": {
    "_id": "665d4e5f6a7b8c9d0e1f2a3b",
    "email": "rahul@example.com",
    "orgId": "663f1a2b3c4d5e6f7a8b9c0d",
    "role": {
      "_id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Front Desk"
    },
    "status": "accepted",
    "invitedBy": {
      "_id": "665c3d4e5f6a7b8c9d0e1f2b",
      "name": "Priya Patel"
    },
    "expiresAt": "2026-03-02T10:00:00.000Z",
    "respondedAt": "2026-02-23T11:00:00.000Z",
    "createdAt": "2026-02-23T10:00:00.000Z",
    "updatedAt": "2026-02-23T11:00:00.000Z"
  }
}