Organizations API

Learn how to manage your organizations in AchieveApex using the REST API.

Overview

The Organizations API allows you to list and retrieve organizations that you have access to. Each user can belong to multiple organizations with different roles.

Base Endpoint

/organizations

Organization Object

The organization object contains information about an organization in AchieveApex.

Organization Object

{
  "id": 123,
  "name": "Acme Inc",
  "subscription_status": "active",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z"
}

List Organizations

Retrieve a list of organizations that the authenticated user has access to. You can optionally filter organizations by name using the search parameter.

Request

GET /organizations

curl -X GET https://api.achieveapex.com/organizations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "$limit": 10,
      "$skip": 0,
      "searchTerm": "acme"
    }
  }'

Response

{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "name": "Acme Inc",
      "subscription_status": "active",
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z"
    },
    {
      "id": 456,
      "name": "Acme Solutions",
      "subscription_status": "active",
      "created_at": "2023-02-01T00:00:00.000Z",
      "updated_at": "2023-02-01T00:00:00.000Z"
    }
  ]
}

Query Parameters

Parameter	Type	Description
$limit	Number	Maximum number of organizations to return (default: 10)
$skip	Number	Number of organizations to skip (for pagination)
searchTerm	String	Optional term to filter organizations by name

Get an Organization

Retrieve a single organization by ID.

Request

GET /organizations/:id

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

Response

{
  "id": 123,
  "name": "Acme Inc",
  "subscription_status": "active",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z"
}

Organization Users

You can also retrieve the users belonging to an organization using the organizations-users endpoint. For detailed documentation on this endpoint, see the Organization Users API documentation.

Request

GET /organizations-users

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

Response

{
  "total": 2,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": 789,
      "user_id": 101,
      "organization_id": 123,
      "role": "admin",
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z",
      "user": {
        "id": 101,
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com"
      }
    },
    {
      "id": 790,
      "user_id": 102,
      "organization_id": 123,
      "role": "member",
      "created_at": "2023-01-02T00:00:00.000Z",
      "updated_at": "2023-01-02T00:00:00.000Z",
      "user": {
        "id": 102,
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@example.com"
      }
    }
  ]
}

Error Handling

The Organizations API returns standard HTTP status codes and error messages.

Error Response

{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}

Status Code	Description
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Not authorized to access this organization
404 Not Found	Organization not found
500 Internal Server Error	Server error

Report an issue with this documentation

Please log in to report issues with our documentation.