Organization Invitations API

Learn how to invite users to join your organizations using the REST API.

Overview

The Organization Invitations API allows you to invite users to join an organization by email. The system sends an invitation with a unique token that recipients can use to accept the invitation and join the organization.

Base Endpoint

/organizations-users-invites

Invitation Object

The invitation object represents a pending or accepted invitation to join an organization.

Invitation Object

{
  "id": 456,
  "organization_id": 123,
  "email": "user@example.com",
  "created_by_user_id": 101,
  "role": "member",
  "status": "pending",
  "token": "abc123def456",
  "expires_at": "2023-01-02T00:00:00.000Z",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "organization": {
    "id": 123,
    "name": "Acme Inc"
  },
  "created_by_user": {
    "id": 101,
    "email": "admin@example.com",
    "first_name": "Admin",
    "last_name": "User"
  }
}

Create an Invitation

Send an invitation to a user by email to join your organization. The system will generate a unique token and send an email with a link that the recipient can use to accept the invitation.

Request

POST /organizations-users-invites

curl -X POST https://api.achieveapex.com/organizations-users-invites \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "organization_id": 123,
    "role": "member"
  }'

Response

{
  "id": 456,
  "organization_id": 123,
  "email": "user@example.com",
  "created_by_user_id": 101,
  "role": "member",
  "status": "pending",
  "token": "abc123def456",
  "expires_at": "2023-01-02T00:00:00.000Z",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z"
}

Request Parameters

Parameter	Type	Required	Description
email	String	Yes	Email address of the user to invite
organization_id	Number	Yes	ID of the organization to invite the user to
role	String	Yes	Role to assign to the user (e.g., "owner", "admin", "member")

List Invitations

Retrieve a list of invitations for a specific organization, optionally filtered by status.

Request

GET /organizations-users-invites

curl -X GET https://api.achieveapex.com/organizations-users-invites \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 123,
      "status": "pending",
      "$limit": 100,
      "$sort": { "created_at": -1 }
    }
  }'

Response

{
  "total": 2,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": 456,
      "organization_id": 123,
      "email": "user1@example.com",
      "created_by_user_id": 101,
      "role": "member",
      "status": "pending",
      "token": "abc123def456",
      "expires_at": "2023-01-02T00:00:00.000Z",
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z"
    },
    {
      "id": 457,
      "organization_id": 123,
      "email": "user2@example.com",
      "created_by_user_id": 101,
      "role": "admin",
      "status": "pending",
      "token": "ghi789jkl012",
      "expires_at": "2023-01-02T00:00:00.000Z",
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z"
    }
  ]
}

Query Parameters

Parameter	Type	Required	Description
organization_id	Number	Yes	ID of the organization to fetch invitations for
status	String	No	Filter invitations by status (e.g., "pending", "accepted")
email	String	No	Filter invitations by email address
token	String	No	Filter by specific invitation token
$limit	Number	No	Maximum number of invitations to return (default: 10)
$skip	Number	No	Number of invitations to skip (for pagination)
$sort	Object	No	Sort criteria (e.g., { "created_at": -1 } for newest first)

Get an Invitation

Retrieve a single invitation by its ID or token.

Request by ID

GET /organizations-users-invites/:id

curl -X GET https://api.achieveapex.com/organizations-users-invites/456 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Request by Token

GET /organizations-users-invites

curl -X GET https://api.achieveapex.com/organizations-users-invites \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "token": "abc123def456",
      "$limit": 1
    }
  }'

Accept an Invitation

When a user follows the invitation link, they'll be taken to a page where they can accept the invitation. The system handles this process automatically, creating a new user account if necessary.

For API access, you can use the following endpoint to accept an invitation:

Request

PATCH /organizations-users-invites/:id

curl -X PATCH https://api.achieveapex.com/organizations-users-invites/456 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "accepted"
  }'

Response

{
  "id": 456,
  "organization_id": 123,
  "email": "user@example.com",
  "created_by_user_id": 101,
  "role": "member",
  "status": "accepted",
  "token": "abc123def456",
  "expires_at": "2023-01-02T00:00:00.000Z",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T12:34:56.789Z"
}

Note: Invitations expire after 24 hours. Each invitation link can only be used once. When an invitation is accepted, the user is automatically added to the organization with the specified role.

Error Handling

The Organization Invitations API returns standard HTTP status codes and error messages.

Error Response

{
  "name": "BadRequest",
  "message": "Invalid token or invitation has expired",
  "code": 400,
  "className": "bad-request"
}

Status Code	Description
400 Bad Request	Invalid parameters, expired invitation, or already used token
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Not authorized to manage invitations for this organization
404 Not Found	Invitation not found
500 Internal Server Error	Server error

Report an issue with this documentation

Please log in to report issues with our documentation.