Notifications API — Fetch, Read & Delete Alerts

The Notifications API lets you retrieve, mark as read, and delete the in-app notifications generated by the EarthCoop platform. Notifications are produced automatically when key events occur — such as a project’s approval status changing, an admin requesting project revisions, or a new investment being received. All notification endpoints require a valid Bearer token.

Notification Types

The platform currently generates four types of notifications.

`project_status_changed`

Sent to a project owner when the status of their project changes (approved, rejected, under review, archived). Notification data fields:

string

Always project_status_changed.

integer

ID of the affected project.

string

Title of the affected project.

string

New project status: approved, rejected, under_review, or archived.

string

Human-readable status change message.

string

Optional reviewer comment, or null.

string

Deep link to the project page.

`project_revision_requested`

Sent to a project owner when an administrator requests changes to their project before it can be approved. Notification data fields:

string

Always project_revision_requested.

integer

ID of the project requiring revision.

string

Title of the project.

string

Standard notification message.

string

Specific revision instructions from the administrator.

string

Deep link to the project edit page.

`new_investment_received`

Sent to a project owner when an investor completes a payment for one of their projects. Notification data fields:

string

Always new_investment_received.

integer

ID of the new investment record.

integer

ID of the project receiving investment.

string

Title of the project.

integer

Investment amount in the platform’s currency unit (گل).

string

Display name of the investor.

string

Notification message text.

string

Deep link to the project’s investment overview.

`investment_status_changed`

Sent to an investor when the status of their investment changes (paid, active, completed, cancelled, refunded). Notification data fields:

string

Always investment_status_changed.

integer

ID of the investment.

string

Title of the associated project.

integer

Investment amount in the platform’s currency unit (گل).

string

New investment status: paid, active, completed, cancelled, or refunded.

string

Human-readable status change message.

string

Optional additional notes (e.g. refund amount), or null.

string

Deep link to the investment detail page.

Notification Object Structure

Every notification returned by the API shares the following top-level shape:

string

UUID of the notification record.

string

A string identifying the notification category, such as project_status_changed or new_investment_received.

object

The notification payload. The structure varies by notification type — see the type-specific fields above.

string|null

ISO 8601 timestamp of when the notification was marked as read, or null if unread.

string

ISO 8601 timestamp of when the notification was created.

GET /api/notifications

Returns the authenticated user’s unread notifications, ordered newest first. Authentication: Required — Authorization: Bearer {token} Request: No parameters.

Example Request

curl -X GET https://your-domain.com/api/notifications \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "project_status_changed",
    "data": {
      "type": "project_status_changed",
      "project_id": 123,
      "project_title": "Community Solar Farm Initiative",
      "status": "approved",
      "message": "Your project has been approved and is ready to receive investments.",
      "comment": null,
      "url": "https://your-domain.com/projects/123"
    },
    "read_at": null,
    "created_at": "2024-11-15T10:30:00Z"
  },
  {
    "id": "660f9511-f30c-52e5-b827-557766551111",
    "type": "new_investment_received",
    "data": {
      "type": "new_investment_received",
      "investment_id": 456,
      "project_id": 123,
      "project_title": "Community Solar Farm Initiative",
      "amount": 10000000,
      "investor_name": "Reza Karimi",
      "message": "A new investment has been recorded for your project.",
      "url": "https://your-domain.com/projects/123"
    },
    "read_at": null,
    "created_at": "2024-11-15T11:00:00Z"
  }
]

Error Responses

Unauthenticated — 401:

{
  "message": "Unauthenticated."
}

POST /api/notifications/

Marks a specific notification as read by setting its read_at timestamp to the current time. Authentication: Required — Authorization: Bearer {token}

Path Parameters

string

required

The UUID of the notification to mark as read.

Request body: None required.

Example Request

curl -X POST https://your-domain.com/api/notifications/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "message": "Notification marked as read."
}

Error Responses

Notification not found — 404:

{
  "message": "Not found."
}

DELETE /api/notifications/

Permanently deletes a notification from the authenticated user’s notification list. Authentication: Required — Authorization: Bearer {token}

Path Parameters

string

required

The UUID of the notification to delete.

Request body: None required.

Example Request

curl -X DELETE https://your-domain.com/api/notifications/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "message": "Notification deleted."
}

Deleting a notification is permanent and cannot be undone. If you want to keep a record of the notification, mark it as read instead.

Error Responses

Notification not found — 404:

{
  "message": "Not found."
}

Unauthenticated — 401:

{
  "message": "Unauthenticated."
}

Overview

Endpoints

Notifications API — Fetch, Read & Delete Alerts

Notification Types

`project_status_changed`

`project_revision_requested`

`new_investment_received`

`investment_status_changed`

Notification Object Structure

GET /api/notifications

Example Request

Example Response

Error Responses

POST /api/notifications/

Path Parameters

Example Request

Example Response

Error Responses

DELETE /api/notifications/

Path Parameters

Example Request

Example Response

Error Responses

​Notification Types

​project_status_changed

​project_revision_requested

​new_investment_received

​investment_status_changed

​Notification Object Structure

​GET /api/notifications

​Example Request

​Example Response

​Error Responses

​POST /api/notifications/

​Path Parameters

​Example Request

​Example Response

​Error Responses

​DELETE /api/notifications/

​Path Parameters

​Example Request

​Example Response

​Error Responses

Notification Types

`project_status_changed`

`project_revision_requested`

`new_investment_received`

`investment_status_changed`

Notification Object Structure

GET /api/notifications

Example Request

Example Response

Error Responses

POST /api/notifications/

Path Parameters

Example Request

Example Response

Error Responses

DELETE /api/notifications/

Path Parameters

Example Request

Example Response

Error Responses