Skip to main content
POST
https://api.bunship.com
/
api
/
v1
/
organizations
/
{orgId}
/
invitations
Send Invitation
curl --request POST \
  --url https://api.bunship.com/api/v1/organizations/{orgId}/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "role": "<string>"
}
'
{
  "invitation": {
    "id": "inv_abc123",
    "organizationId": "org_cld2abc123def456",
    "email": "[email protected]",
    "role": "member",
    "invitedBy": {
      "id": "usr_cld2abc123def456",
      "email": "[email protected]",
      "fullName": "John Doe"
    },
    "expiresAt": "2024-01-22T10:00:00Z",
    "createdAt": "2024-01-15T10:00:00Z",
    "status": "pending"
  },
  "inviteUrl": "https://app.bunship.com/invite/tok_abc123def456..."
}
Sends an email invitation to join the organization with a specified role. The invitation expires after 7 days. Cannot send an invitation if the user is already a member or has a pending invitation. Requires the invitations:create permission.

​
Auth

Requires a valid Bearer token with invitations:create permission.

​
Path Parameters

​
orgId
string
required
Organization identifier.

​
Request Body

​
email
string
required
Email address to invite. Must be a valid email format.
​
role
string
required
Role to assign when the invitation is accepted. One of "admin", "member", or "viewer".

​
Response

​
invitation
object
The created invitation object with id, organizationId, email, role, invitedBy, expiresAt, createdAt, and status.
​
inviteUrl
string
URL for the invitee to accept the invitation.
{
  "invitation": {
    "id": "inv_abc123",
    "organizationId": "org_cld2abc123def456",
    "email": "[email protected]",
    "role": "member",
    "invitedBy": {
      "id": "usr_cld2abc123def456",
      "email": "[email protected]",
      "fullName": "John Doe"
    },
    "expiresAt": "2024-01-22T10:00:00Z",
    "createdAt": "2024-01-15T10:00:00Z",
    "status": "pending"
  },
  "inviteUrl": "https://app.bunship.com/invite/tok_abc123def456..."
}

​
Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid email address
401AUTHENTICATION_ERRORMissing or invalid Bearer token
403AUTHORIZATION_ERRORInsufficient permissions (invitations:create required)
404NOT_FOUNDOrganization not found
409CONFLICTUser is already a member, or a pending invitation already exists for this email

​
Example

curl -X POST https://api.bunship.com/api/v1/organizations/org_cld2abc123def456/invitations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "member"
  }'