Activity Types API

Learn how to manage custom activity types in AchieveApex using the REST API.

Overview

The Activity Types API allows you to define custom types of activities within your organization. These can be used to categorize and customize how activities appear in the system. You can list, retrieve, create, update, and delete activity types.

Base Endpoint

/activity-types

Activity Type Object

The activity type object contains information about a custom activity type in your organization.

Activity Type Object
{
  "id": 5,
  "name": "Customer Training",
  "color": "#4F46E5",
  "icon_key": "graduation-cap",
  "organization_id": 27,
  "created_at": "2025-03-10T14:22:17.562Z",
  "updated_at": "2025-03-10T14:22:17.562Z",
  "deleted_at": null
}

List Activity Types

Retrieve a list of activity types in your organization with optional filtering and pagination.

Request
GET /activity-types

curl -X GET https://api.achieveapex.com/activity-types \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 27,
      "$limit": 10,
      "$skip": 0,
      "$sort": { "name": 1 }
    }
  }'
Response
{
  "total": 5,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 1,
      "name": "Call",
      "color": "#10B981",
      "icon_key": "phone",
      "organization_id": 27,
      "created_at": "2025-03-01T10:00:00.000Z",
      "updated_at": "2025-03-01T10:00:00.000Z",
      "deleted_at": null
    },
    {
      "id": 2,
      "name": "Email",
      "color": "#3B82F6",
      "icon_key": "mail",
      "organization_id": 27,
      "created_at": "2025-03-01T10:00:00.000Z",
      "updated_at": "2025-03-01T10:00:00.000Z",
      "deleted_at": null
    },
    {
      "id": 3,
      "name": "Meeting",
      "color": "#F59E0B",
      "icon_key": "users",
      "organization_id": 27,
      "created_at": "2025-03-01T10:00:00.000Z",
      "updated_at": "2025-03-01T10:00:00.000Z",
      "deleted_at": null
    },
    {
      "id": 4,
      "name": "Task",
      "color": "#EC4899",
      "icon_key": "check-square",
      "organization_id": 27,
      "created_at": "2025-03-01T10:00:00.000Z",
      "updated_at": "2025-03-01T10:00:00.000Z",
      "deleted_at": null
    },
    {
      "id": 5,
      "name": "Customer Training",
      "color": "#4F46E5",
      "icon_key": "graduation-cap",
      "organization_id": 27,
      "created_at": "2025-03-10T14:22:17.562Z",
      "updated_at": "2025-03-10T14:22:17.562Z",
      "deleted_at": null
    }
  ]
}

Query Parameters

ParameterTypeDescription
organization_idNumberID of the organization (required)
nameStringFilter by name (supports partial matching)
$limitNumberNumber of activity types to return (default: 10)
$skipNumberNumber of activity types to skip (for pagination)
$sortObjectSort criteria (e.g., { "name": 1 } for name ascending)

Get an Activity Type

Retrieve a single activity type by ID.

Request
GET /activity-types/:id

curl -X GET https://api.achieveapex.com/activity-types/5 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
Response
{
  "id": 5,
  "name": "Customer Training",
  "color": "#4F46E5",
  "icon_key": "graduation-cap",
  "organization_id": 27,
  "created_at": "2025-03-10T14:22:17.562Z",
  "updated_at": "2025-03-10T14:22:17.562Z",
  "deleted_at": null,
  "activities_count": 12
}

Create an Activity Type

Create a new activity type in your organization.

Request
POST /activity-types

curl -X POST https://api.achieveapex.com/activity-types \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "Site Visit",
    "color": "#8B5CF6",
    "icon_key": "map-pin"
  }'
Response
{
  "id": 6,
  "name": "Site Visit",
  "color": "#8B5CF6",
  "icon_key": "map-pin",
  "organization_id": 27,
  "created_at": "2025-04-05T09:30:22.451Z",
  "updated_at": "2025-04-05T09:30:22.451Z",
  "deleted_at": null
}

Update an Activity Type

Update an existing activity type in your organization.

Request
PATCH /activity-types/:id

curl -X PATCH https://api.achieveapex.com/activity-types/6 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Site Visit",
    "color": "#7C3AED"
  }'
Response
{
  "id": 6,
  "name": "Client Site Visit",
  "color": "#7C3AED",
  "icon_key": "map-pin",
  "organization_id": 27,
  "created_at": "2025-04-05T09:30:22.451Z",
  "updated_at": "2025-04-05T09:40:15.876Z",
  "deleted_at": null
}

Delete an Activity Type

Delete an activity type from your organization.

Request
DELETE /activity-types/:id

curl -X DELETE https://api.achieveapex.com/activity-types/6 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response
{
  "id": 6,
  "name": "Client Site Visit",
  "color": "#7C3AED",
  "icon_key": "map-pin",
  "organization_id": 27,
  "created_at": "2025-04-05T09:30:22.451Z",
  "updated_at": "2025-04-05T09:50:33.219Z",
  "deleted_at": "2025-04-05T09:50:33.219Z"
}

Note on Activity Type Deletion

When an activity type is deleted, the system performs a soft delete by setting the deleted_at timestamp. Any existing activities using this type will continue to reference it, but the type will no longer be available for new activities. Consider updating existing activities to use a different type before deletion.

Available Icons

The following icon keys are available for use with activity types. These correspond to the Feather icon set.

phone

mail

calendar

users

check-square

map-pin

clipboard

coffee

message-circle

video

file-text

award

Error Handling

The Activity Types 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 CodeDescription
400 Bad RequestInvalid parameters or request
401 UnauthorizedMissing or invalid authentication
403 ForbiddenNot authorized to access this organization's activity types
404 Not FoundActivity type not found
500 Internal Server ErrorServer error

Related Documentation

For information on using activity types with activities, see the Activities API documentation.

Report an issue with this documentation

Please log in to report issues with our documentation.