Activities API

The Activities API allows you to read and create activities. Activities are immutable audit logs and cannot be updated or deleted.

Activity Types

call - Phone calls
email - Email messages
meeting - Meetings and appointments
note - Notes and comments
rating - Customer ratings or reviews

Endpoints

List Activities

Retrieve a list of activities with optional filtering.

GET /api-v1-activities

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of records per page (default: 100, max: 1000)
`page`	integer	Page number for offset pagination (default: 1)
`cursor`	string	Cursor for cursor-based pagination
`sort`	string	Sort field and direction (e.g., `created_at:desc`)
`filter[type]`	string	Filter by activity type
`filter[organization_id]`	string	Filter by organization ID
`filter[contact_id]`	string	Filter by contact ID
`filter[deal_id]`	string	Filter by deal ID
`filter[created_at][gte]`	string	Filter by creation date (greater than or equal)
`include`	string	Comma-separated relations: `organization`, `contact`, `deal`, `user`

Example Request

curl "https://your-instance.supabase.co/functions/v1/api-v1-activities?limit=50&filter[type]=call&include=contact,organization" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "call",
      "subject": "Follow-up call",
      "description": "Discussed product demo and pricing",
      "organization_id": "456e7890-e89b-12d3-a456-426614174001",
      "contact_id": "789e0123-e89b-12d3-a456-426614174002",
      "deal_id": "012e3456-e89b-12d3-a456-426614174003",
      "user_id": null,
      "metadata": {
        "created_via": "api",
        "duration_seconds": 300
      },
      "created_at": "2025-12-09T10:30:00Z",
      "updated_at": "2025-12-09T10:30:00Z",
      "contact": {
        "id": "789e0123-e89b-12d3-a456-426614174002",
        "first_name": "John",
        "last_name": "Doe"
      },
      "organization": {
        "id": "456e7890-e89b-12d3-a456-426614174001",
        "name": "Acme Corp"
      }
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "page": 1,
    "per_page": 50,
    "total_pages": 3,
    "has_more": true
  }
}

Get Single Activity

Retrieve a specific activity by ID.

GET /api-v1-activities/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Activity ID

Example Request

curl "https://your-instance.supabase.co/functions/v1/api-v1-activities/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "call",
    "subject": "Follow-up call",
    "description": "Discussed product demo and pricing",
    "organization_id": "456e7890-e89b-12d3-a456-426614174001",
    "contact_id": "789e0123-e89b-12d3-a456-426614174002",
    "deal_id": "012e3456-e89b-12d3-a456-426614174003",
    "user_id": null,
    "metadata": {
      "created_via": "api",
      "duration_seconds": 300
    },
    "created_at": "2025-12-09T10:30:00Z",
    "updated_at": "2025-12-09T10:30:00Z",
    "contact": {
      "id": "789e0123-e89b-12d3-a456-426614174002",
      "first_name": "John",
      "last_name": "Doe"
    },
    "organization": {
      "id": "456e7890-e89b-12d3-a456-426614174001",
      "name": "Acme Corp"
    },
    "deal": {
      "id": "012e3456-e89b-12d3-a456-426614174003",
      "title": "Q4 Enterprise Deal"
    },
    "user": null
  }
}

Create Activity

Log a new activity. Activities are immutable once created.

POST /api-v1-activities

Request Body

Field	Type	Required	Description
`type`	string	Yes	Activity type: `call`, `email`, `meeting`, `note`, `rating`
`subject`	string	No	Activity subject or title
`description`	string	No	Detailed description or notes
`organization_id`	UUID	No	Related organization ID
`contact_id`	UUID	No	Related contact ID
`deal_id`	UUID	No	Related deal ID
`metadata`	object	No	Additional custom data

Example Request

curl -X POST "https://your-instance.supabase.co/functions/v1/api-v1-activities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "call",
    "subject": "Discovery call",
    "description": "Initial conversation about their needs",
    "contact_id": "789e0123-e89b-12d3-a456-426614174002",
    "organization_id": "456e7890-e89b-12d3-a456-426614174001",
    "metadata": {
      "duration_seconds": 1200,
      "outcome": "interested"
    }
  }'

Example Response

{
  "data": {
    "id": "234e5678-e89b-12d3-a456-426614174004",
    "type": "call",
    "subject": "Discovery call",
    "description": "Initial conversation about their needs",
    "organization_id": "456e7890-e89b-12d3-a456-426614174001",
    "contact_id": "789e0123-e89b-12d3-a456-426614174002",
    "deal_id": null,
    "user_id": null,
    "metadata": {
      "created_via": "api",
      "duration_seconds": 1200,
      "outcome": "interested"
    },
    "created_at": "2025-12-09T11:00:00Z",
    "updated_at": "2025-12-09T11:00:00Z",
    "contact": {
      "id": "789e0123-e89b-12d3-a456-426614174002",
      "first_name": "John",
      "last_name": "Doe"
    },
    "organization": {
      "id": "456e7890-e89b-12d3-a456-426614174001",
      "name": "Acme Corp"
    },
    "deal": null,
    "user": null
  }
}

Validation Rules

type must be one of: call, email, meeting, note, rating
If organization_id is provided, the organization must exist and belong to your company
If contact_id is provided, the contact must exist and belong to your company
If deal_id is provided, the deal must exist and belong to your company
subject and description are trimmed of whitespace

Important Notes

Activities are immutable: Once created, activities cannot be updated or deleted. This ensures a complete audit trail.
API-created activities: Activities created via the API have user_id set to null and metadata.created_via set to "api".
Automatic metadata: The API automatically adds created_via: "api" to the metadata field.
Soft deletes not supported: Unlike other resources, activities cannot be deleted (even soft delete) as they are audit logs.

Filter Operators

When filtering, you can use these operators:

eq - Equal to (default)
ne - Not equal to
gt - Greater than
gte - Greater than or equal to
lt - Less than
lte - Less than or equal to
in - In array (comma-separated values)

Example with operators:

# Activities created after 2025-12-01
curl "https://your-instance.supabase.co/functions/v1/api-v1-activities?filter[created_at][gte]=2025-12-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Multiple activity types
curl "https://your-instance.supabase.co/functions/v1/api-v1-activities?filter[type][in]=call,meeting" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

400 Bad Request - Invalid Type

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid type. Must be one of: call, email, meeting, note, rating",
    "details": [
      {
        "field": "type",
        "message": "Must be one of: call, email, meeting, note, rating"
      }
    ]
  }
}

400 Bad Request - Organization Not Found

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Organization not found",
    "details": [
      {
        "field": "organization_id",
        "message": "Organization not found"
      }
    ]
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Activity not found"
  }
}