Developer Reference

API Documentation

🌱

Causes Module

Manage charitable causes — create, update, search, and delete cause records.

Prod: https://byve.io

Retrieve the full list of causes (including inactive and soft-deleted records).

Parameters

None

Response

[
  {
    "id": int,
    "name": string,
    "description": string,
    "imageUrl": string,
    "isActive": bool?,
    "isDeleted": bool?,
    "createdOn": DateTime,
    "modifiedOn": DateTime
  }
]

Retrieve a single cause by its numeric ID.

Query Parameters

Name	Type	Required	Description
id	int	✱ required	The unique identifier of the cause.

Example

GET /api/cause/getbyid?id=5

Filter causes by ID, name, or deletion status. All fields are optional.

Request Body — CauseSearch

{
  "id": int?,            // optional — filter by ID
  "name": string,         // optional — partial match
  "isDeleted": bool?     // optional — true/false/null
}

Insert a new charitable cause record.

Request Body — Cause

{
  "name": string,             ✱ required
  "description": string,
  "imageUrl": string,
  "isActive": bool?,
  "isDeleted": bool?,
  "createdOn": DateTime,
  "modifiedOn": DateTime
}

Update a cause record. The id field must be set to identify the record.

Request Body — Cause

{
  "id": int,               ✱ required
  "name": string,
  "description": string,
  "imageUrl": string,
  "isActive": bool?,
  "isDeleted": bool?,
  "modifiedOn": DateTime
}

Marks a cause as deleted (soft delete). Pass the cause ID in the request body.

Request Body

{
"id": int ✱ required
}

💜

Donation Module

Record and query charitable donations linked to causes.

Prod: https://byve.io

Retrieve every donation record across all causes.

Parameters

None

Response

[
  {
    "id": int,
    "causeId": int,
    "amount": decimal,
    "currency": string?,
    "country": string?,
    "ipaddress": string?,
    "website": string?,
    "donorEmail": string?,
    "createdOn": DateTime
  }
]

Search donations by cause, donor email, country, currency, or date. All fields are optional.

Request Body — DonationSearch

{
  "id": int?,
  "causeId": int?,
  "donorEmail": string?,
  "currency": string?,
  "country": string?,
  "createdOn": DateTime
}

Insert one or more donation records in a single call. Accepts an array of Donation.

Request Body — List<Donation>

[
  {
    "causeId": int,          ✱ required
    "amount": decimal,      ✱ required
    "currency": string?,     // e.g. "AUD"
    "country": string?,
    "ipaddress": string?,
    "website": string?,
    "donorEmail": string?,
    "createdOn": DateTime
  }
]

⭐

User GQ (Goodness Quotient) Module

Retrieve a user's computed Goodness Quotient score based on their donation history.

Prod:https://byve.io/

Returns the computed Goodness Quotient percentage for a given user email. GQ is the average of all donation GQ contributions: (payment_score / 5) × (cause_importance_pct / 100) × 100

Query Parameters

Name	Type	Required	Description
email	string	✱ required	Email address of the user whose GQ score is requested.

Example

GET /api/gq/getgq?email=user@example.com

Response — UserGqScore

{
  "id": long,
  "email": string,
  "gqPct": decimal?,    // 0–100 score
  "lastCalculated": DateTime?
}

GQ scores are recalculated daily by the stored procedure usp_RefreshUserGQScore. The lastCalculated field shows when the score was last refreshed.

🔐

Authentication

How to authenticate requests through the API Gateway.

All requests routed through the Ocelot API Gateway must include an API key header:

Request Header

X-Api-Key: your-api-key-here

The gateway validates this key via the API Key middleware before forwarding the request to the downstream service. Direct service calls (bypassing the gateway) use an internal key delegation mechanism.

OpenAPI specs are available at /openapi/v1.json on each service in Development mode.

⚠️

Common HTTP Status Codes

Standard response codes returned across all Byve APIs.