1. Membership
Handwrite Team
  • Handwrite Regular Accounts
    • Schemas
      • Error
      • Principal
      • Role
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • CreateDocument
      • UpdateDocument
      • FileInfo
      • CommitUpload
      • Upload
      • DownloadLink
      • Extracted
      • ExtractionFailed
      • CommittedDocument
      • ExtractedDocument
      • SearchHit
      • SearchPage
      • Export
      • Permission
      • Share
      • ChangeRole
      • Invitation
      • Permissions
      • ReceivedInvitation
      • AcceptedInvitation
      • Me
      • WebhookEventType
      • Webhook
      • CreateWebhook
      • CreatedWebhook
      • WebhookDelivery
      • AudioFormat
      • Speech
      • WordTiming
      • SpeechMarks
      • AudioLink
      • Voice
      • Quota
      • SettingEntry
      • Settings
      • SettingsPatch
      • PatchedSettings
      • OAuthToken
      • OAuthError
  • Handwrite Team
    • Teams
      • README — GET /api/v1/orgs
      • README — POST /api/v1/orgs
      • README — GET /api/v1/orgs/{id}
      • README — PATCH /api/v1/orgs/{id}
      • README — DELETE /api/v1/orgs/{id}
      • Your teams and classes
      • Create a team or class
      • One of your organisations
      • Rename a team (owner or admin)
      • Delete with its memberships, invitations, documents and shares (owner)
    • Membership
      • README — GET /api/v1/orgs/invitations
      • README — POST /api/v1/orgs/invitations/{inviteId}/accept
      • README — POST /api/v1/orgs/invitations/{inviteId}/decline
      • README — GET /api/v1/orgs/{id}/members
      • README — POST /api/v1/orgs/{id}/members
      • README — PATCH /api/v1/orgs/{id}/members/{principal}
      • README — DELETE /api/v1/orgs/{id}/members/{principal}
      • README — POST /api/v1/orgs/{id}/leave
      • README — GET /api/v1/orgs/{id}/invitations
      • README — POST /api/v1/orgs/{id}/invitations
      • README — DELETE /api/v1/orgs/{id}/invitations/{inviteId}
      • Organisation invitations to your verified email
        GET
      • Join with the invited role
        POST
      • Decline an organisation invitation
        POST
      • Members (students see teachers and themselves)
        GET
      • Add a person (managers)
        POST
      • Change a role; owner transfers a team
        PATCH
      • Remove a member (managers) or yourself
        DELETE
      • Leave (not the owner)
        POST
      • Pending email invitations (managers)
        GET
      • Invite an email (managers)
        POST
      • Withdraw an invitation (managers)
        DELETE
    • Documents
      • README — GET /api/v1/orgs/{id}/documents
      • Documents the organisation owns
    • Billing and usage
      • README — GET /api/v1/orgs/{id}/billing
      • README — GET /api/v1/orgs/{id}/usage
      • README — GET /api/v1/orgs/{id}/usage/live
      • README — GET /api/v1/orgs/{id}/members/{principal}/usage
      • README — GET /api/v1/orgs/{id}/insights
      • Plan, status and seats per role (billing.read)
      • Usage per day and member (admins, managers, billing)
      • The last 60 minutes per member (admins, managers, billing)
      • One member's usage (usage.read, or yourself)
      • How people collaborate on the org's documents
    • Policies
      • README — GET /api/v1/orgs/{id}/policies
      • README — PUT /api/v1/orgs/{id}/policies
      • README — GET /api/v1/orgs/{id}/members/{principal}/policy
      • README — PUT /api/v1/orgs/{id}/members/{principal}/policy
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/policy
      • Org-wide policy rules (policies.read)
      • Replace the org-wide rules (admins)
      • A member's override and what applies to them
      • Replace a member's override (admins; managers for members)
      • Remove a member's override
    • Managed tokens
      • README — GET /api/v1/orgs/{id}/members/{principal}/tokens
      • README — POST /api/v1/orgs/{id}/members/{principal}/tokens
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/tokens/{tokenId}
      • Managed tokens issued to a member (tokens.read)
      • Issue a managed fine-grained token (admins, billing)
      • Revoke a managed token (admins, billing)
    • Guides
      • Start here — Team app integration
      • Team API specification notes
      • Team socket specification notes
      • Team live socket — README
      • Team roles and access model
      • Team credentials and developer setup
      • Team SSO and portal workflows
      • Team policies, plans and seats
      • Team usage and collaboration insights
      • Team webhook delivery — README
    • Schemas
      • Error
      • Principal
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • OrgKind
      • OrgRole
      • Organisation
      • CreateOrganisation
      • RenameOrganisation
      • Member
      • AddMember
      • ChangeMember
      • InviteMember
      • OrgInvitation
      • ReceivedOrgInvitation
  • Handwrite Classroom
    • Schemas
      • Error
      • Principal
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • OrgKind
      • OrgRole
      • Organisation
      • CreateOrganisation
      • RenameOrganisation
      • Member
      • AddMember
      • ChangeMember
      • InviteMember
      • OrgInvitation
      • ReceivedOrgInvitation
  1. Membership

README — POST /api/v1/orgs/{id}/members

Add a person (managers)#

POST /api/v1/orgs/{id}/members · Operation ID: addMember

App purpose#

Adds the given user principal immediately without an acceptance step. Use only a principal the user has intentionally selected; use the invitation endpoint when you have an email. Seats and maximum team size (500) are enforced.

Authentication and authority#

Bearer credential with orgs:manage. Owner/admin can assign non-owner team roles; managers can add members only.
Scopes do not replace role, ownership, plan, current membership or effective-policy checks. The team edition uses the shared organisation route with a team ID; it does not change the backend schema for classes.

Example#

Replace all REPLACE_* values and use an authorised disposable team for tests. Read-only examples still require the appropriate data access. Mutating examples change team state; policy PUT examples are complete replacements.
curl --fail-with-body -X POST 'https://handwrites.io/api/v1/orgs/REPLACE_TEAM_ID/members' \
  -H "Authorization: Bearer $HANDWRITE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"principal":"user:REPLACE_USER_ID","role":"member"}'

Parameters#

NameInRequiredMeaning
idpathYesAn organisation ID (org_…).
Idempotency-KeyheaderNo1–255 visible ASCII characters (a UUID per operation). A retry with the same key and identical request within 24 hours replays the first 2xx response with Idempotent-Replayed: true; a different request with the key gets 422 idempotency_mismatch; a retry while the first runs gets 409 idempotency_in_progress.

Request body#

application/json (required).
FieldRequiredShape
principalYesA person.
roleYesTeam roles: owner, admin, billing, manager, developer, member. Class roles: teacher, co-teacher, billing, student.

Responses and recovery#

StatusMeaningFormat
201The membership.application/json
400invalid_request (the message names the field), validation_failed.application/json
401unauthorized: no token, or it's invalid, revoked or expired.application/json
403insufficient_scope, forbidden (you can see it but not do this), app_test_restricted, account_deleted (the account is scheduled for deletion; any request).application/json
404not_found: it doesn't exist or you can't see it (never 403 for documents you can't see).application/json
409conflict (changed meanwhile, already a member) or idempotency_in_progress (with Retry-After).application/json
422limit_reached, idempotency_mismatch, unreadable_file, no_text, empty_document.application/json
429rate_limited (burst or daily cap) or quota_exceeded (no characters left).application/json
500internal_error.application/json
Treat 403 as a current authority/policy failure and 404 as unavailable to this caller, without probing other accounts. Plan and seat checks may add 402 failures beyond generic reference responses. Retry only when the operation semantics permit it; keep Request-Id for support. Do not parse a 204 or 304 as JSON.
Read Team API specification notes, roles and access, and credential boundaries for the shared rules.
Modified at 2026-10-26 13:21:46
Previous
README — GET /api/v1/orgs/{id}/members
Next
README — PATCH /api/v1/orgs/{id}/members/{principal}
Built with