Skip to content
MothershipDevelopers

API referenceUsers

Invite a user

Invites someone to join your organization. Mothership emails them a link to set their password, and they join with the role you pick once they accept. Every call sends a real email. It fails with a 400 when the email already belongs to a Mothership user or already has a pending invite to your organization. Requires the organization:user.create permission.

POST/users/invites
Environment
https://sandbox.api.mothership.com/beta
curl --request POST \
  --url 'https://sandbox.api.mothership.com/beta/users/invites' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "logistics@example.com",
  "firstName": "Dana",
  "lastName": "Reyes",
  "role": "manager"
}'
Reads your token from $MOTHERSHIP_API_TOKEN
Response
{
: {
: "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
: "logistics@example.com",
: "Dana",
: "Reyes",
: "manager",
: "2026-03-19T17:00:00.000Z",
: "2026-03-19T17:00:00.000Z",
: true
}
}

Hover a key to see what it means. Click it to jump to the field.

Authorization

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Request body

application/json · required
  • emailstring<email>Required

    Email address the invite goes to

    max length 254
  • firstNamestringRequired

    First name of the person being invited

    min length 1max length 100pattern \S
  • lastNamestringRequired

    Last name of the person being invited

    min length 1max length 100pattern \S
  • rolestringRequired

    Role the person gets once they accept the invite. manager: Manage all features for your organization. shipper: Book shipments. Read-access to other features. accountant: Manage and edit billing. View-only for other features. viewer: View-only account access. Nobody is invited as an owner.

    managershipperaccountantviewer

Responses

    • dataobjectRequired
      • idstringRequired

        ID of the invite

      • emailstringRequired

        Email address the invite was sent to

      • firstNamestringRequired
      • lastNamestringRequired
        nullable
      • rolestringRequired

        Role the person gets once they accept the invite. manager: Manage all features for your organization. shipper: Book shipments. Read-access to other features. accountant: Manage and edit billing. View-only for other features. viewer: View-only account access. Nobody is invited as an owner.

        managershipperaccountantviewer
      • createdAtstring<date-time>Required

        When the invite was sent

      • expiresAtstring<date-time>Required

        When the invite link stops working

      • expiredbooleanRequired

        True when the invite link has expired. The person can't accept it; revoke it and invite them again.

What's next

GETList pending invites

See who has been invited and not joined yet.