Welcome!

Hey! Welcome to our API reference for givestar!

The givestar API is based on REST, will return JSON encoded responses and uses standard HTTP status codes.

We'll use CURL script in here for examples, any problems or questions please contact us.

Authentication

We use two header keys for authentication

GS2SAPI-API-KEY - Your unique API key
GS2SAPI-API-OID - Your unique Owner Id

Header Example

curl --location 'https://api.givestar.io/api/v1/s2s/events/SignUp' \
--header 'X-GS2SAPI-Key: <API KEY HERE>' \
--header 'X-GS2SAPI-OID: <OID HERE>' \
...[rest of payload ommitted]

Both of these will be supplied by your contact at givestar so make sure you have those to hand.

Remember, your API credentials are essentially a username and password and must be treated as such. If you suspect your API key has been revealed anywhere it shouldn't, contact us and we will disable it and generate a new one for you.

Base URL

The base URL for the givestar API is at

https://api.givestar.io

Most integration endpoints will be under

https://api.givestar.io/api/v1/s2s

Errors

We use standard HTTP response codes to indicate success or failure of an API request.

Generally codes in the 2xx range indicate a success.

Codes in the 4xx range indicate an error with the request (missing field / information etc)

5xx range (hopefully none) indicate an error with the givestar API.

Base responses

All responses are returned as JSON formatted data and we use a few different objects to return data depending on the data.

Task Response

List Response

Signing up for an event

[POST] https://api.givestar.io/api/v1/s2s/events/signup

[RETURNS] Task Response

The event signup process will generate a new fundraising page, handle user onboarding and connect the new page to your event.

Events in givestar all have a template fundraising page connected to them. The new fundraising page will use the information from this as default (images / description / currency / target etc) and use any parameters specified in campaignSetup to override these.

Example Payload - Basic Information

{
    "eventId":"[your event id]",     
    "participants": [
        {
            "firstName":"Sam",
            "lastName":"Starling",
            "email":"sam.starling@givestar.io"            
        }
    ]
}

cURL example

curl --location 'https://api.givestar.io/api/v1/s2s/events/SignUp' \
--header 'X-GS2SAPI-Key: [your api key]' \
--header 'X-GS2SAPI-OID: [your owner id]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "eventId":"[your event id]",  
    "participants": [
        {
            "firstName":"Sam",
            "lastName":"Starling",
            "email":"sam.starling@givestar.io"            
        }
    ]
}'

The above example will create a new fundraising page for your event using all the template defaults. In addition we have specified the user information as Sam Starling, the system will check for an existing user or start the onboarding process for a new user.

Specifying campaign options (optional)

A number of campaign options can be set at signup which will override the template defaults. All following are optional.

Property Name	Data Type	Description	Example Value
`targetAmount`	Decimal	Specify target amount for fundraising page	123.45
`currencyId`	String	Specify currency id for page (see Currencies)	3fa85f64-5717-4562-b3fc-2c963f66afa6
`campaignName`	String	Title for fundraising page	My cool page title
`campaignDescription`	String	Description for fundraising page. (basic HTML allowed)	Hey! Thanks for visiting my page.

Here is an example where the target amount, campaign name and description have been set.

Example Payload

{
    "eventId":"[your event id]", 
    "campaignSetup":
        {
            "targetAmount": 350,
            "campaignName":"This is my page!",
            "campaignDescription":"Hey, thanks for checking out my page."
        }, 
    "participants": [
        {
            "firstName":"Sam",
            "lastName":"Starling",
            "email":"sam.starling@givestar.io"            
        }
    ]
}

Participants (required)

The participants property specifies information about the supporter. This data is used to either assign the new fund raising page to an existing user or to start the claim page routines within givestar. firstName, lastName and email are all required fields. Optionally, an address property can be specified which allows a phone number and country code to be specified for SMS alerts and marketing.

(for more information on the SMS functionality, please contact us)

 "participants": [
    {
      "firstName": "Frank",
      "lastName": "Smith",         
      "email": "frank.smith@givestar.io",
      "address": {        
        "phoneNumber": "075899899887",
        "countryCode": "gb"
      }
    }
  ]

Property Name	Data Type	Description	Example	Required
`firstName`	`string`	First name of the participant	`Frank`	yes
`lastName`	`string`	Last name of the participant	`Smith`	yes
`email`	`string`	Email address of the particpant	`frank.smith@givestar.io`	yes
`address`	`address object`	Optional address component (see below)		no

Address Component

The address property can be specified if a mobile phone number (and country code) is required to be sent as part of the payload.
The most common scenario is when the supporter should be entered into SMS workflows from givestar.

Property Name	Data Type	Description	Example	Required
`phoneNumber`	`string`	Phone number of the supporter	`075899899887 / 00447589989987`	yes
`countryCode`	`string`	If the number is not specified in international format, i.e. does not begin with `0044` then a country code is required. By default the system will assume `gb` if this is not specified.	`gb`	yes

Specifying charities (optional)

Most events will use the event template charities as the default. These can be changed by the user once they have claimed their page through the onboarding process which happens after an event signup.

However, if you want to specify the charity(s) to be used during the event signup, then the selectedCharities property can be set. When more than one charity is specified the splits between the charities will be set automatically.

For example

Charity Count	Split
1	100%
2	50%
3	33.33%
4	25%

Up to 4 charities can be specified.

In the case of an uneven split (i.e. 33.33% leaves 0.01% floating), a random shuffle is used on each donation to determine the charity which will receive the additional 0.01% of the donation.

"selectedCharities": [
    {
      "charityId": "fede3b44-d90d-4b2d-8851-fb0d372c1ec8"
    },
    {
      "charityId": "88f2bf4e-d7c9-4c38-89c2-34792567e49c"
    } 
  ]

The charity ids are the givestar unique id for the charity, to find a charity id we can either supply this to you (if it is a pre-determined list that you wish to provide to your users) or you can use the charity search API call.

{
    "eventId":"[your event id]", 
    "campaignSetup":
        {
            "targetAmount": 1000,
            "campaignName":"Running the hills for charity",
            "campaignDescription":"Hey, I am splitting my donations between these two great charities!"
        }, 
    "participants": [
        {
            "firstName":"Sam",
            "lastName":"Starling",
            "email":"sam.starling@givestar.io"            
        }
    ],
    "selectedCharities": [
        {
          "charityId": "fede3b44-d90d-4b2d-8851-fb0d372c1ec8"
        },
        {
          "charityId": "88f2bf4e-d7c9-4c38-89c2-34792567e49c"
        }
  ]
}

The following is an example successful response following an event signup.

{
    "success": true,
    "message": "",
    "data": {
        "eventName": "Event Test",
        "supporterName": "Frank",
        "campaignQuickCode": "event-test-91623",
        "campaignLink": "https://api.givestar.io/gs/event-test-91623",
        "campaignName": "Event Test Page",
        "campaignCreated": true,
        "campaignId": "2045f1......6b56f7c",
        "supporterId": "c2af094......2d7855",
        "newUserCreated": true,
        "teamName": "",
        "newTeam": false,
        "teamInviteCode": "",
        "teamId": "",
        "teamQuickCode": "",
        "paymentReference": "",
        "teamSuccess": false,
        "teamResponseMessage": "No team options were specified.",
        "campaignResponseMessage": "",
        "pageActivationUrl": "https://givestar.io/ppa/gs/event-test-91623?userId=e9b416......c7b03e69f9a&activationCode=2193f52......c2f4e89ccb"
    },
    "responseCode": ""
}

Property Name	Data Type	Description
`success`	`boolean`	If the request was successful or not
`message`	`string`	Any message related to the response
`data`	`object`	The signup response data
`data.[eventName]`	`string`	Name of the event being signed up to
`data.[supporterName]`	`string`	First name of the supporter as specified in request
`data.[campaignQuickCode]`	`string`	Short code for the supporters fundraising page
`data.[campaignLink]`	`string`	Shareable Url for the supporters fundraising page
`data.[campaignName]`	`string`	Title of the created fundraising page
`data.[campaignCreated]`	`datetime`	Creation date of the fundraising page
`data.[campaignId]`	`uuid`	Internal id of the fundraising page
`data.[supporterId]`	`uuid`	Internal id of the supporter account
`data.[newUserCreated]`	`boolean`	True if a new user was created during signup, false if an existing user was found
`data.[teamName]`	`string`	Team name if request includes team join options
`data.[newTeam]`	`boolean`	True if a new team was created as part of the request
`data.[teamInviteCode]`	`string`	Shareable team invite code, populated when a new team is created
`data.[teamId]`	`uuid`	Internal team id
`data.[teamQuickCode]`	`string`	Short code for the team
`data.[paymentReference]`	`string`	Any payment reference relating to the signup and/or purchases
`data.[teamSuccess]`	`boolean`	If a team request was sent, true if the team join was successful
`data.[teamResponseMessage]`	`string`	Any messages relating to the team creation/join request
`data.[campaignResponseMessage]`	`string`	Any messages relating to the fundraising page creation
`data.[pageActivationUrl]`	`string`	Url to allow the user to "claim" their page on the givestar platform and activate their account

Creating Events

[POST] https://api.givestar.io/api/v1/s2s/events

Property Name	Data Type	Description	Example	Required
`eventType`	`integer`	Specifies the type of event to create, this is normally set to 0 for regular signup events.	`0`	yes
`alternativeId`	`string`	Optional owner event id which can be used in place of the internal givestar id for event signups.	`ABC1234`	no
`eventCode1`	`string`	Optional event code field for your reporting purposes.	`code_1`	no
`eventCode2`	`string`	Secondary optional event code field for your reporting purposes.	`code_2`	no
`name`	`string`	The name of your event.	`My Event`	yes
`description`	`string`	The description of your event as shown on the event page. This section allows basic HTML commands.	`This is our event`	yes
`targetAmount`	`decimal`	Optional target amount for your event.	`100000`	no
`currencyId`	`uuid`	The currency id to be used for the event.	`9d6494c0-e364-43f0-b76c-52251df71133`	yes
`eventStart`	`datetime`	Optional event start field for the event in yyyy-MM-dd format.	`2027-01-01`	no
`eventEnd`	`datetime`	Optional event end field for the event in yyyy-MM-dd format.	`2027-06-01`	no
`category`	`integer`	The category id for the event (see event categories)	`3`	yes
`campaignTemplate`	`campaignTemplateObject`	The campaign or fundraising page template to be used. (See below for example)		yes
`locationAddress`	`addressObject`	Optional event location address. (See below for example)		no
`eventOptions`	`eventOptionsObject`	Optional settings for the event. (See below for example)		no

Fundraising Page Template Object

The fundraising page template (also known as the campaign template) defines the default setup for the fundraising pages created when signing up for an event.

This settings in this template will be used if no overrides are received during the event signup process to build the users page.

Property Name	Data Type	Description	Example	Required	Default
`name`	`string`	Fundraising page title	`My Page`	yes
`description`	`string`	Description of the fundraising page. This section allows basic HTML to be used.	`Thanks for visting my page!`	yes
`currencyId`	`uuid`	The currency id for the fundraising page. This should be set to the same as the main event.	`9d6494c0-e364-43f0-b76c-52251df71133`	yes
`defaultTarget`	`decimal`	The default target for the fundraising page.	`10000`	no	`0`
`noCharity`	`boolean`	If set to `true` the page will prompt for charities to be specified when the user claims the page.	`true`	no	`false`
`charities`	`campaignCharities[]`	An optional list of campaign charities to be set as default for the fundraising page. (See below for example). If the `noCharity` option is set to `true` this property will be ignored.		no

Campaign Charities

Property Name	Data Type	Description	Example	Required	Default
`charityId`	`uuid`	The id of the charity to be added.		yes
`autoSplit`	`boolean`	If set to `true` the platform will auto split the donations equally between the charities.	`true`	no	`true`
`split`	`decimal`	If `autoSplit` is set to `false` this value will be used to denote the percentage of the donation received against the charity. If the total of splits does not equal 100, the split will be made automatically.	`50`	no

Event Location Address

This object can be used to specify a location for your event.

Property Name	Data Type	Description	Example	Required
`addressLine1`	`string`	Address Line 1	`Fair Oak Manor`	no
`addressLine2`	`string`	Address Line 2		no
`addressLine3`	`string`	Address Line 3		no
`addressLine4`	`string`	Address Line 4		no
`locality`	`string`	Locality	`Hampshire`	no
`region`	`string`	Region	`South`	no
`postZipCode`	`string`	Post/Zip Code	`SO99 ABC`	no
`country`	`string`	Country	`UK` `Scotland`	no
`phoneNumber`	`string`	Phone Number	`+44 011 1234566`	no
`countryCode`	`string`	2 Digit country code	`UK`	no

Event Options

This object allows you to set specific options for your event.

Property Name	Data Type	Description	Example	Required	Default
`lockFundRaiserPage`	`boolean`	Whether the user can change the banner / title or description of the fundraising page.	`false`	no	`false`
`frpAllowCharitySelect`	`boolean`	Whether the user can select their own charities. If set to true, default charities must be specified on the main event template.	`true`	no	`true`
`hideFundRaiserCount`	`boolean`	Show or hide the number of fundraisers signed up to the event on the main event page.	`false`	no	`false`
`hideTotaliser`	`boolean`	Show or hide the totaliser on the main event page.	`false`	no	`false`
`hideDonationCount`	`boolean`	Show or hide the donation count on the main event page.	`false`	no	`false`
`hideLeaderBoard`	`boolean`	Show or hide the leader board on the main event page.	`false`	no	`false`
`maxChildCampaigns`	`integer`	The maximum number of pages that can be created under the event. A value of `0` means no limit.	`400`	no	`0`
`enableTeams`	`boolean`	Whether teams are enabled for the event.	`true`	no	`true`
`hideSignupButton`	`boolean`	Show or hide the signup button on the main event page.	`false`	no	`false`
`frpSupporterLimit`	`integer`	Sets how many pages can be created by an individual user/supporter account. A value of `0` means no limit.	`0`	no	`0`
`charityInclude`	`uuid[]`	A list of charities to be included for charity selection on the fundraising pages.	`[]`	no	`[]`
`charityExclude`	`uuid[]`	A list of charities to be excluded for charity selection on the fundraising pages.	`[]`	no	`[]`

Event Categories

Events on the platform are assigned a category, below is the list of currently active categories that can be used in the category property.

Id	Name
`0`	Other
`1`	Run
`2`	Sport
`3`	Sailing
`4`	Cycle
`5`	Walk
`6`	Coffee Morning
`7`	Hike
`8`	Marathon
`9`	Sleep Out
`10`	Half Marathon
`11`	Obstacle Course
`12`	Swim
`13`	Triathlon
`14`	Rowing
`15`	Sky Dive

Example Payload

[POST] https://api.givestar.io/api/v1/s2s/events

{
    "eventType":0,
    "alternativeId":"596839",
    "eventCode1":"ev code 1",
    "eventCode2":"ev code 2",
    "name": "Sailing Event 7",
    "description":"This is my sailing event",
    "targetAmount":10000,
    "currencyId":"9d6494c0-e364-43f0-b76c-52251df71133",
    "eventStart":"2026-01-01",
    "eventEnd":"2026-01-02",
    "category":3,
    "campaignTemplate":{
        "name":"Sailing Event 7 TE",
        "description":"Thanks for looking at my page, I am part of the sailing event",
        "currencyId":"9d6494c0-e364-43f0-b76c-52251df71133",
        "defaultTarget":500        
    },
    "locationAddress": {
        "addressLine1":"Henley On Thames",
        "postZipCode":"HA1 5TR"
    }
}

Example Response

{
    "eventId": "e8ecaba7-7444-4901-99bd-521e5cd9d311",
    "eventName": "Sailing Event 7",
    "eventQuickCode": "sailing-event-7",
    "campaignCreated": true,
    "campaignId": "565d7665-dac2-4d3a-ae7a-f6e70b331729",
    "campaignName": "Sailing Event 7 TE",
    "campaignQuickCode": "sailing-event-7-te",
    "success": true
}

On a successful response, the eventId can be used to set the media for the event and for the template fundraising page. Please refer to the Media section in this document.

Updating Events

[PATCH] https://api.givestar.io/api/v1/s2s/events

The update endpoint allows you to change several different properties for both the event and the fundraising page template.

Property Name	Data Type	Description	Example	Required
`eventId`	`uuid`	The id of the event to update.		yes
`eventAlternativeId`	`string`	Optional owner event id which can be used in place of the internal givestar id for event signups.	`ABC1234`	no
`eventCode1`	`string`	Optional event code field for your reporting purposes.	`code_1`	no
`eventCode2`	`string`	Secondary optional event code field for your reporting purposes.	`code_2`	no
`eventTitle`	`string`	The name of your event.	`My Event`	no
`eventDescription`	`string`	The description of your event as shown on the event page. This section allows basic HTML commands.	`This is our event`	no
`eventStatus`	`integer`	Sets the status of the event. 0 = Draft, 1 = Active, 2 = Completed		no
`eventTargetAmount`	`decimal`	Optional target amount for your event.	`100000`	no
`eventStart`	`datetime`	Optional event start field for the event in yyyy-MM-dd format.	`2027-01-01`	no
`eventEnd`	`datetime`	Optional event end field for the event in yyyy-MM-dd format.	`2027-06-01`	no
`eventCategory`	`integer`	The category id for the event (see event categories)	`3`	no
`eventLocation`	`addressObject`	Optional event location address. (See above for example)		no
`eventOptions`	`eventOptionsObject`	Optional settings for the event. (See above for example)		no
`templateTitle`	`string`	The default title for fundraising pages created for this event.		no
`templateDescription`	`string`	The default description for fundraising pages created for this event.		no
`templateTargetAmount`	`decimal`	The default donation target for fundraising pages created for this event.		no
`eventQuickCode`	`string`	The quick code or URL slug for the event, see notes below.	`my-event-page`	no

If any property is omitted from the payload, its current value will not be changed.

In the case of the event start and end dates, if these values are omitted, then the system will assume a null value for these fields.

In the case of eventPrivate if this property is not specified, the system will assume a value of false.

Event Quick Code: The event quick code is used as a URL short code slug, i.e. https://givestar.io/ev/my-event where my-event is the quick code.

If this is specified on the event update payload then the requested value will be checked against other events to ensure uniqueness, if the specified quick code is already in use an error will be returned with a message to this effect. Quick codes will automatically be trimmed, converted to lower case and have any spaces replaced with -.

Example Payload

{
    "eventId":"xxxx905f-2d3c-xxxx-xxxx-df66b25cc7a0",
    "eventTitle":"Our event!!",
    "eventDescription":"The very cool event",
    "eventTargetAmount":700,
    "eventCategory":1, 
    "eventStart":"2025-09-01",
    "eventEnd":"2025-09-02",
    "eventCode1":"a new event code",
    "eventCode2":"2nd event code",
    "eventQuickCode":"this event 2",
    "eventAlternativeId":"AN ALT ID",
   "templateDescription":"This is a new template description.",
   "templateTargetAmount":1010,
   "templateTitle":"The new event",
   "eventLocation": {
        "addressLine1":"Event Address 1",
        "addressLine2":"Event Address 2",
        "postZipCode":"SE11 1QR"
   }
}

Example Response

{
    "success": true,
    "message": "",
    "data": null,
    "responseCode": ""
}

Media

[POST] https://api.givestar.io/api/v1/s2s/media

The media endpoint can be used to set banner images for both the event and template campaign records.

After creating an event record, the event should have a banner set, optionally a banner can be set for the template campaign as well. If the template campaign does not have a default banner image, the main event banner image will be used instead.

Images are uploaded as form-data with two URL parameters to specify the media type and the related entity id (either the campaign or event id in this case.)

https://api.givestar.io/api/v1/s2s/media?mediaType=12&entityId=e8ecaba7-7444-4901-99bd-521e5cd9d311

Example cURL Request

This request uploads a new event banner image (media type 12) for the event id e8ecaba7-7444-4901-99bd-521e5cd9d311.

curl --location 'https://api.givestar.io/api/v1/s2s/media?mediaType=12&entityId=e8ecaba7-7444-4901-99bd-521e5cd9d311' \
--header 'X-GS2SAPI-Key: [your api key]' \
--header 'X-GS2SAPI-OID: [your owner id]' \
--form '=@"/C:/Users/givestar/Downloads/my-event-banner.jpg"'

This request uploads a new fundraising page banner image (media type 1) for the page id 565d7665-dac2-4d3a-ae7a-f6e70b331729.

curl --location 'https://api.givestar.io/api/v1/s2s/media?mediaType=1&entityId=565d7665-dac2-4d3a-ae7a-f6e70b331729' \
--header 'X-GS2SAPI-Key: [your api key]' \
--header 'X-GS2SAPI-OID: [your owner id]' \
--form '=@"/C:/Users/givestar/Downloads/my-page-banner.jpg"'

Reporting Services

Overview

We offer a number of standard reports which are accessible from the S2S endpoint /api/v1/s2s/reports

We have tried to make the reporting system at givestar as flexible as possible to allow it to cater for different integration requirements.

Reports here can be filtered, paged and sorted as required as well as supplying data in a structured JSON format.

If custom reports are developed for you, they are available by the same process as below.

Available reports

Report Id	Name	Context	Description
`fd1131be-0da5-4409-b2b7-a341c409a1fc`	Event List Report	`s2s`	Base report for events.
`91c62a22-38e8-4492-976e-e97e3f2b831e`	Event Fundraising Page Report	`s2s`	A report on all fundraising pages, including totals for events.
`60150d0a-f6fc-40c8-914a-833f70437ddb`	Event Charity List (GBP Totals)	`s2s`	A report on all beneficiary charities for events

Report Components

There are 3 main components to the reports:

Report Definition
Report Request
Report Response

Report Definition

/api/v1/sysops/reports/{reportId} [GET]

Returns the definition of a report, it will return all the available fields, types along with any required parameters for the report.

It is useful to call this if you need to determine what fields and parameters are available and what they mean as well as determining which fields can be sorted and filtered.

Example Response

{
    "id": "da3e5ad0-629e-4c45-b88b-935cbb7da90b",
    "name": "Donation Report",
    "description": "Charity donation report",
    "groupName": "Donations",    
    "requiredParameters": [
        {
            "parameterName": "startDate",
            "fieldType": "datetime",
            "value1": "",
            "value2": "",
            "internalSet": false
        },
        {
            "parameterName": "endDate",
            "fieldType": "datetime",
            "value1": "",
            "value2": "",
            "internalSet": false
        }
    ],
    "fieldsAvailable": [
        {
            "fieldName": "statement_internal_id",
            "internalFieldName": "",
            "fieldType": "uuid",
            "headerName": "(INT) Statement Id",
            "description": "Internal statement id.",
            "displayIndex": 0,
            "allowSort": true,
            "allowFilter": true,
            "baseDisplay": false,
            "permanent": true,
            "validFilters": [
                "equals",
                "not_equal",
                "null",
                "not_null"
            ]
        }....
        [Rest of payload omitted]

Property	Description
`id`	Unique id of the report requested
`name`	Name of the report
`description`	A description of the report
`groupName`	Grouping name for the report, i.e. Donations or Events etc
`requiredParameters`	Array of parameters required for the report (see report parameters)
`fieldsAvailable`	Array of the fields available for the report (see report fields)

Report Field Object

The report field object defines a report field. Its basic job is to provide a human friendly representation of the underlying data field and to allow the UI to determine if it should show for filtering and ordering.

Property Name	Data Type	Description
`fieldName`	String	The unique internal field name, this should be used when referencing the field
`fieldType`	field_type	The type of field data (see field types)
`headerName`	String	The default "friendly" name for the field
`description`	String	A user friendly description of the field
`displayIndex`	Integer	The default display index (position) of the field
`allowSort`	Boolean	Whether the field allows sorting or not
`allowFilter`	Boolean	Whether the field allows filtering or not
`baseDisplay`	Boolean	If the field is included when no fields are defined by the report request
`permanent`	Boolean	If the field is always sent regardless of the report request
`validFilters`	String[]	If the field is filterable, then a list of the filters valid for the data-type

Field Types

Below is a list of all the current valid field types

Field Type Id	Description
`datetime`	Date / Time in yyyy-MM-dd HH:mm format
`uuid`	UUID / GUID
`boolean`	Boolean as `true` or `false`
`text`	Any text values (inc JSON data as string)
`number_decimal`	Decimal values
`number_int`	Integer values

Running a report

/api/v1/s2s/reports/run [POST]

To run a report a reportRequest payload must be sent.

The report request specifies the report required, paging information, parameters (if required), filtering, sorting and any specific fields required.

If a report request doesn't specify any fields, then the default set of fields will be returned.

Example Report Request

{
    "reportId": "ab45f-629e-4c45-aaaa-935cbb7da90b",
    "pageSize": 1,
    "pageNumber": 50,
    "exportReport": false,
    "fields": [            
        {
            "fieldName": "donation_date",
            "displayIndex": 0,
            "headerName": "Date of donation"
        },
        {
            "fieldName": "campaign_name",
            "displayIndex": 1,
            "headerName": "Campaign Name"
        },
        {
            "fieldName": "donation_amount",
            "displayIndex": 2,
            "headerName": "Donation Amount"
        },
        {
            "fieldName": "event_name",
            "displayIndex": 3,
            "headerName": "Event Name"
        },
        {
            "fieldName": "donator_email",
            "displayIndex": 4,
            "headerName": "Donator Email"
        }
    ],
    "order": [      
        {
            "fieldName": "donation_date",
            "direction": "desc"
        },       
        {
            "fieldName": "campaign_name",
            "direction": "asc"
        },
        {
            "fieldName": "donation_amount",
            "direction": "desc"
        }
    ],
    "filterType": "all",
    "filters": [
        {
            "fieldName": "donation_amount",
            "filterOperation": "greater_than_or_equal",
            "filterValue": "10"
        }
    ],
    "parameters": [       
        {
            "parameterName": "startDate",            
            "value1": "2024-01-01 00:00"
        },
        {
            "parameterName": "endDate",            
            "value1": "2025-03-20 00:00"
        }
    ]
}

Report Request Properties

Property Name	Data Type	Description
`reportId`	UUID	The id of the report requested
`pageSize`	int	Number of records per page to return
`pageNumber`	int	Page number required
`exportReport`	boolean	If true, then any paging information is overidden and a full set of data is returned as JSON data
`fields`	`reportRequestField[]`	A list of the fields requested, if no fields are specified then a base set of information is returned.
`order`	`reportRequestOrderField[]`	An array of fields on which to order the data
`filterType`	string	`all` or `any`. If "all" then all filters will try and match, if any, then the data can be matched to any of the filters.
`parameters`	`reportRequestParameter[]`	An array of the parameters required for the report.

Report Request Field

The report request field object is used to specify which fields (and override their header names if needed) and the order in which they should appear.

Property Name	Data Type	Description
`fieldName`	string	The field name id for the field required
`displayIndex`	int	The order in which the field should be rendered. If conflicts then the order is by the display index and then by the header name.
`headerName`	string	Allows the user to define their own header name if required. If omitted, then the default header name for the field is used.

Order Fields

The report order field can be used to define multiple ordering columns for the report output.

Property Name	Data Type	Description
`fieldName`	string	The field name id for the field required
`direction`	string	One of `asc` for ascending sort or `desc` for descending sort

Filter Fields

Reports can be filtered by specifying the reportFilterField property on the reportRequest object.

Depending on the field type, only certain filter operations are valid.

In addition to providing filter fields, you must also specify the filterType. By default this is set to all which means all fields must match.

If any is specified, then any fields may match.

Property Name	Data Type	Description
`fieldName`	string	The field name id for filtering. This does not have to be included in the display fields.
`filterOperation`	string	The operation to apply. (See filter operations table)
`filterValue`	string	The filter value to check for. All values are try-parsed against their respective data-types backend. If an invalid parse, the filter is ignored.

Filter Operations Table

Filter Operation	Description
`equals`	Value is equal to
`greater_than`	Value is greater than
`greater_than_or_equal`	Value is greater than or equal to
`not_equal`	Value is not equal to
`less_than`	Value is less than
`less_than_or_equal`	Value is less than or equal to
`null`	Value is null
`not_null`	Value is not null
`contains`	(text only - case insensitive) Text contains value
`not_contains`	(text only - case insensitive) Text does not contain value

Parameter Fields

Some reports may require parameters as specified when you get the base report definition.

These are supplied to using the following data type.

If an incorrect number pf parameters is received, or not all parameters could be converted to their respective data-types, then an error will be returned.

Property Name	Data Type	Description
`parameterName`	string	From the report definition
`value1`	string	String value to be parsed as parameter

Relative Date Parameters (new)

Many reports are based from a date range using two parameters startDate and endDate. For convenience a relativeDateParamValue can be passed as the value for the startDate which will instruct the report service to automatically determine a startDate and endDate value from the point the report is being run.

For example, if now-12h is specified as the startDate parameter value and the report is being run at 6pm on the 1st March 2026, the resulting startDate and endDate values will be:

startDate = 2026-03-01 06:00 endDate = 2026-03-01 18:00

Because these parameter values can be saved in a custom report, this allows you to create a report that, when run, automatically selects the correct date range rather than having to set it manually each time.

Value	Description	Notes
`now-5m`	Last 5 minutes
`now-15m`	Lat 15 minutes
`now-30m`	Last 30 minutes
`now-1h`	Last hour
`now-3h`	Last 3 hours
`now-6h`	Last 6 hours
`now-12h`	Last 12 hours
`now-24h`	Last 24 hours
`now-1d`	Last day
`now-2d`	Last 2 days
`now-7d`	Last 7 days
`now-30d`	Last 30 days
`now-90d`	Last 90 days
`now-6m`	Last 6 months
`now-1y`	Last year
`now-2y`	Last 2 years
`now-5y`	Last 5 years
`now-1d/d`	Yesterday	Sets start time to `00:00:00` and end time to `23:59:59`
`now-2d/d`	Day before yesterday	Sets start time to `00:00:00` and end time to `23:59:59`
`now-7d/d`	This day last week	Sets start time to `00:00:00` and end time to `23:59:59`
`now-1w/w`	In the last week	Sets start time to `00:00:00` and end time to `23:59:59`
`now-1M/M`	Last month	Sets start time to `00:00:00` and end time to `23:59:59`
`now-1y/y`	Previous year Jan-Dec	Sets start time to `00:00:00` and end time to `23:59:59`
`now/d`	Today	Sets start time to `00:00:00` and end time to `23:59:59`
`now/M`	This month	Sets start time to `00:00:00` and end time to `23:59:59`
`now/y`	This year Jan-Dec	Sets start time to `00:00:00` and end time to `23:59:59`

If an invalid relative date parameter value is sent, the response will be one of an error.

Example request

Report in last 3 hours

{
    "reportId": "da3e5ad0-629e-4c45-b88b-935cbb7da90b",
    "pageSize": 25,
    "pageNumber": 1,
    "exportReport": false,
    "parameters":[
        {
            "parameterName":"startDate",
            "value1":"now-3h",
            "fieldType":"date_time"
        },
        {
            "parameterName":"endDate",
            "value1":"now",
            "fieldType":"date_time"
        }
    ]  
}

Note: When specifying a relative date parameter value for startDate, endDate value is ignored but must be supplied with any value.

Report Request Response

The report request response is sent back either on a successful report run or as part of a 400 response.

Example response (success)

{
    "reportId": "da3e5ad0-629e-4c45-b88b-935cbb7da90b",
    "reportName": "Donation Report",
    "success": true,
    "errorMessage": "",
    "totalRecords": 1058,
    "fieldCount": 7,
    "headerCount": 7,
    "exportMode": false,
    "data": [
        {
            "donation_source_name": "Mobile App",
            "campaign_name": "Santa Barbara Big Surf hshs",
            "donation_date": "2025-03-30T07:36:33.820059",
            "donation_type_name": "Online",
            "donation_id": "79108610-9d68-4f9b-9a76-57f6ff6de534",
            "donation_amount": 10,
            "payout_net": 9.56
        }
        ....[data truncated]
    ],
    "headers": [
        {
            "fieldName": "donation_source_name",
            "headerName": "Donation Source"
        },
        {
            "fieldName": "campaign_name",
            "headerName": "Campaign Name"
        },
        {
            "fieldName": "donation_date",
            "headerName": "Date of donation"
        },
        {
            "fieldName": "donation_type_name",
            "headerName": "The wonderful type of donation"
        },
        {
            "fieldName": "donation_id",
            "headerName": "My donation id"
        },
        {
            "fieldName": "donation_amount",
            "headerName": "Donation Amount"
        },
        {
            "fieldName": "payout_net",
            "headerName": "Payout NET"
        }        
    ],
    "summaryData": [
        {
            "description": "Total record count",
            "fieldType": "number_decimal",
            "value": 1058
        }
    ]
}

Property Name	Data Type	Description
`reportId`	uuid	Id of base report requested
`reportName`	string	Name of base report requested
`success`	boolean	True or False depending on status
`errorMessage`	string	If success == false, a message explaining the error will be shown here
`totalRecords`	int	Total number of records in dataset irrespective of paging
`fieldCount`	int	Total number of fields rendered
`headerCount`	int	Total number of header fields rendered. This should match the field count.
`exportMode`	boolean	True if export mode was requested (full data set, no paging), false if basic paging method
`data`	object[]	Array of objects. The property names for each object will match a header entry below
`headers`	fieldHeader[]	Array of field headers with fieldNames matching the property names in the data array
`summaryData`	summaryData[]	Array of summary fields. See notes below

Summary Data

Some reports will return summary data as part of the payload. These are unique depending on the type of report being run.

Donation Ticker & Totaliser Feeds

We offer two endpoints to enable you to display a real-time donation ticker and totaliser feed on your own website / application.

These are updated every time a donation is "settled" on the givestar platform and can be used to display live totals to your audience. Both endpoints can be used with either a campaignId, eventId or teamId in place of the {entityId} below.

Donation Ticker

The ticker displays a list of all donations settled on the system. It maintains a list of 150 donations for a maximum of 48 hours (after no activity).

https://api.givestar.io/api/v1/FRP/{entityId}/DonationTicker

Example Response

[
  {
    "timeStamp": "2025-05-16T20:04:03.5485622Z",
    "campaignId": "e373627b-0000-4608-9742-948d37fc0627",
    "eventId": "2c9d8328-0000-4145-9206-66281d40f0cd",
    "teamId": "00000000-0000-0000-0000-000000000000",
    "donationAmount": 20,
    "giftAid": false,
    "giftAidValue": 0,
    "donationCurrencyCode": "GBP",
    "displayName": "Nick",
    "donatorFirstName": "Nicholas",
    "donatorLastName": "Smith",
    "donatorDisplayName": "Nick",
    "donatorMessage": "Good Luck!",
    "donationCurrencySymbol": "£",
    "formattedDonationAmount": "£20.00",
    "totalValueWithGiftAid": 20,   
    "campaignOwnerId": "3d6bea74-26e4-4a05-9a35-d9e291183bee",
    "campaignQuickCode": "helens-fundraising-page"    
   }]....[DATA TRUNCATED]

Donation Totaliser

The totaliser contains the total amount raised for the entityId specified.

https://api.givestar.io/api/v1/FRP/{entityId}/DonationTotal

Example Response

{
  "recordId": "e4faa8f0-0000-48d4-9761-da086a0d3960",
  "recordName": "My Run!",
  "currencyCode": "GBP",
  "currencySymbol": "£",
  "amount": 1200.47,
  "giftAidAmount": 294.25,
  "formattedAmount": "£1200.47"
}

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Welcome!

Authentication

Base URL

Errors

Base responses

Task Response

List Response

Event Signup

Signing up for an event

Specifying campaign options (optional)

Participants (required)

Address Component

Specifying charities (optional)

Event SignUp Response

Creating Events

Fundraising Page Template Object

Campaign Charities

Event Location Address

Event Options

Event Categories

Example Payload

Example Response

Updating Events

Example Payload

Example Response

Media

Example cURL Request

Reporting Services

Overview

Available reports

Report Components

Report Definition

Example Response

Report Field Object

Field Types

Running a report

Example Report Request

Report Request Properties

Report Request Field

Order Fields

Filter Fields

Filter Operations Table

Parameter Fields

Relative Date Parameters (new)

Example request

Report Request Response

Example response (success)

Summary Data

Donation Ticker & Totaliser Feeds

Donation Ticker

Example Response

Donation Totaliser

Example Response