You do not need these routes for a collection, but an integration can use them to manage who is in the organization. They take the organization id in the path ({orgId}). Changing anything needs an active plan (403 otherwise).
| Task | Route | Who may do it |
|---|---|---|
| List my organizations | GET /organization/user/organizations |
Any user |
| Read the organization | GET /organization/{orgId} |
Any member |
| Update it (name, address, preferences) | PATCH /organization/{orgId} |
Admin or owner |
| List members | GET /organization/{orgId}/members |
Any member |
| Invite people by email | POST /organization/{orgId}/invite |
Member or above. A plain member may invite only clients or members. |
| List invitations | GET /organization/invitations |
Any member |
| Resend an invitation | POST /organization/{orgId}/invitation/{invitationId}/resend |
Member or above |
| Delete a pending invitation | DELETE /organization/{orgId}/invitation/{invitationId} |
Member or above |
| Change members' roles, names or emails | PATCH /organization/{orgId}/user |
Admin or owner |
| Remove a member | DELETE /organization/{orgId}/user/{userId} |
Admin or owner |
Things to know:
- People are invited as
memberunless you give a role. - Inviting returns 403 when the plan's seat limit is reached. Removing a member frees a seat, and also removes that member's access to every case in the organization.
- A member's name and email can be changed only if they belong to no other organization; otherwise the whole request is refused.
- The members and invitations lists return
data: null, not an empty list, when nothing matches.
Invite a colleague:
curl -X POST "https://api.usehearsay.com/organization/$ORG_ID/invite" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"users": [{"email": "sam.lee@example.com", "name": "Sam Lee"}]}'