ThirdSectorBee organises all information around data entities — distinct record types, each representing a real-world concept in charity work. This page lists every entity across all modules, with a description of what it is and the fields it holds.

Relationships

The Relationships module is ThirdSectorBee’s CRM. See also: The Relationships data model and Touchpoints, payments and fundraising activities.

Contact

Usually an individual person, or a representation of an anonymous group.

Field Type Description
contactId string (UUID) Unique identifier for the contact
firstName string Given name(s)
lastName string Family name / surname
email string Primary email address
phone string Primary phone number
address object Postal address (line1, line2, town, county, postcode, country)
dateOfBirth date Date of birth — used for Gift Aid eligibility and personalisation
isAnonymous boolean True if this contact represents an anonymous individual or group rather than a named person
organisationId string (UUID) Associated organisation, if the contact is primarily known through one
notes string Free-text notes about the contact
consent object Communications consent for this contact. See Consent storage below.
tags string[] User-defined labels for filtering and segmentation
createdAt timestamp When the record was created
updatedAt timestamp When the record was last modified

See Contact fields for the full field reference including access groups.

The consent field is a nested object that records the contact’s opt-in or opt-out state for every combination of purpose and channel configured by the organisation. Its shape is:

consent[purposeName][channelKey] = ConsentChannelRecord
  • purposeName — the name of a communications purpose as configured in Settings → Communications Consent (e.g. "Marketing", "Service Updates"). Keys match the names defined there.
  • channelKey — lowercase, no spaces: email, mail, phone, sms, whatsapp.

Each ConsentChannelRecord contains:

Field Type Description
state enum Current consent state: ok (opted in), no (opted out), unknown (not yet captured)
history object[] Ordered log of every change to this channel’s state — see below

Each entry in history contains:

Field Type Description
timestamp string (ISO 8601) When the change was recorded
changedBy string Display name or email of the user who made the change
channel string Channel this entry relates to (e.g. "Email")
from enum State before the change (ok, no, or unknown)
to enum State after the change (ok, no, or unknown)
note string Optional free-text reason for the change

Example — a contact who has opted in to Marketing emails but opted out of Marketing SMS, with no record yet for mail:

{
  "Marketing": {
    "email": {
      "state": "ok",
      "history": [
        {
          "timestamp": "2024-03-15T10:22:00Z",
          "changedBy": "Alice Smith",
          "channel": "Email",
          "from": "unknown",
          "to": "ok",
          "note": "Opted in via sign-up form"
        }
      ]
    },
    "sms": {
      "state": "no",
      "history": [
        {
          "timestamp": "2024-06-01T14:05:00Z",
          "changedBy": "Alice Smith",
          "channel": "SMS",
          "from": "unknown",
          "to": "no"
        }
      ]
    }
  }
}

Only purposes and channels that have been explicitly set appear in the object — a missing key is treated the same as unknown.

Organisation

A corporate body, such as a company, trust, foundation, charity or club.

Field Type Description
organisationId string (UUID) Unique identifier for the organisation
name string Legal or trading name of the organisation
type enum Category of organisation: Company, Trust, Foundation, Charity, Club, Government, Other
email string Primary contact email address
phone string Primary contact phone number
address object Registered or principal address (line1, line2, town, county, postcode, country)
website string Organisation website URL
registrationNumber string Charity Commission, Companies House, or equivalent registration number
notes string Free-text notes about the organisation
tags string[] User-defined labels for filtering and segmentation
createdAt timestamp When the record was created
updatedAt timestamp When the record was last modified

See Organisation fields for the full field reference.

Thing

A physical thing involved in the work of the charity, such as a collection tin or contactless payment terminal.

Field Type Description
thingId string (UUID) Unique identifier for the thing
name string Human-readable name or label for the thing
type enum Category of thing: CollectionTin, ContactlessTerminal, DirectDebitMandate, Other
description string Further detail about this specific thing
serialNumber string Manufacturer or internal serial/reference number
location string Where the thing is currently deployed or stored
assignedContactId string (UUID) Contact currently responsible for or associated with this thing
assignedOrganisationId string (UUID) Organisation currently responsible for or associated with this thing
notes string Free-text notes
tags string[] User-defined labels for filtering and segmentation
createdAt timestamp When the record was created
updatedAt timestamp When the record was last modified

See Thing fields for the full field reference.

Touchpoint

An interaction with a contact, organisation or thing. Touchpoints can be inbound (contact-initiated) or outbound (charity-initiated), and can be linked to multiple contacts, organisations or things. Files can be attached to a touchpoint via the FileAttachments service.

Field Type Description
touchpointId string (UUID) Unique identifier for the touchpoint
direction enum Whether the interaction was Inbound (contact-initiated) or Outbound (charity-initiated)
channel enum Medium of interaction: Email, Phone, InPerson, Post, SocialMedia, Online, Other
date timestamp When the interaction took place
subject string Brief subject or title of the interaction
summary string Description of what was discussed or happened
contactId string (UUID) Primary contact this touchpoint is recorded against
organisationId string (UUID) Organisation this touchpoint is associated with, if applicable
thingId string (UUID) Thing this touchpoint is associated with, if applicable
relatedContactIds string[] Additional contacts involved in this interaction
relatedOrganisationIds string[] Additional organisations involved in this interaction
relatedThingIds string[] Additional things involved in this interaction
notes string Free-text notes
tags string[] User-defined labels for filtering and segmentation
createdAt timestamp When the record was created
updatedAt timestamp When the record was last modified

See Touchpoint fields for the full field reference.

Payment

A record of the movement of funds, inbound or outbound. Files such as receipts, invoices, and signed agreements can be attached via the FileAttachments service.

The status field indicates whether money has actually changed hands:

  • Paid — the funds have been transferred
  • Pledged — the payer has indicated that payment will be made in future
  • Invoiced — an invoice for the payment has been raised (by default, these funds are accounted for from the date of invoice)
Field Type Description
paymentId string (UUID) Unique identifier for the payment
status enum Current state of the payment: Paid, Pledged, Invoiced
direction enum Whether the payment is Inbound (receipt) or Outbound (disbursement)
amount number (decimal) Face value of the payment in the nominated currency
currency string (ISO 4217) Currency code of the payment (e.g. GBP, USD, EUR)
reportingAmount number (decimal) Equivalent amount converted to the organisation’s reporting currency at the time of payment — necessarily approximate
contactId string (UUID) Contact associated with this payment (payer or payee)
organisationId string (UUID) Organisation associated with this payment, if applicable
relatedThingId string (UUID) Thing associated with this payment (e.g. the collection tin it came from)
personalOrOrganisationalDonation enum Whether the donation is Personal (from an individual) or Organisational (from a corporate body) — relevant to Gift Aid eligibility
datePaid date Date the funds were transferred; null if not yet paid
expectedDate date Expected date of payment for Pledged or Invoiced records
ineligibleForTaxRelief boolean True if this payment cannot benefit from Gift Aid or equivalent tax relief
acknowledgementPersonalisation string Custom text or reference used when generating a thank-you or receipt communication
paymentMethod enum How the payment was or will be made: Cash, Cheque, BankTransfer, DirectDebit, Card, Online, Other
bankAccount string Reference to the bank account involved, if applicable
team string Internal team or department the payment is attributed to
breakdown object[] Itemised split of the payment total. Each item contains: Purpose (Donation, ShopPurchase, Ticket, Grant, Other), TermsOfRestriction, Amount, and Percentage
notes string Free-text notes
createdAt timestamp When the record was created
updatedAt timestamp When the record was last modified

See Payment fields for the full field reference.

Recurring payment

A standing arrangement for income to be received on a predictable schedule — for example a Direct Debit mandate, a CAF/Stewardship regular giving setup, or a bank standing order. When an actual payment arrives, a Payment record is created and coded using the fields from the recurring payment.

The schedule is expressed as a frequency (every N weeks/months/years) combined with a rule that specifies which day within that period the payment falls on. A plain-English scheduleDescription (e.g. “every month on the 4th (or the following working day)”) is generated automatically.

Field Type Description
recurringPaymentId string (UUID) Unique identifier for the recurring payment
amount number (decimal) Expected payment amount in the nominated currency
currency string (ISO 4217) Currency code (e.g. GBP, USD, EUR)
frequencyUnit enum Cadence unit: Weeks, Months, or Years
frequencyInterval number (integer) Number of units between payments (e.g. 2 + Weeks = fortnightly)
collectionDayRule object Discriminated union describing the day within the period — one of: DayOfWeek (weekly schedules), DayOfMonth (e.g. 15th), DayOfMonthExcludingWeekends (moves to next working day if weekend), NthWorkingDayOfMonth (e.g. 1st working day), AnnualDate (specific month + day for yearly)
scheduleDescription string System-generated plain-English summary, e.g. “every month on the 4th (or the following working day)”
status enum Payment status to apply when coding the incoming Payment: Paid, Pledged, Invoiced
reportingAmount number (decimal) Expected amount in the organisation’s reporting currency
contactId string (UUID) Contact associated with this recurring arrangement (payer)
organisationId string (UUID) Organisation associated with this arrangement, if applicable
relatedThingId string (UUID) Thing associated with this arrangement (e.g. a Direct Debit mandate record)
personalOrOrganisationalDonation enum Whether donations from this arrangement are Personal or Organisational — relevant to Gift Aid eligibility
startDate date When the arrangement began
expectedDate date Next expected payment date
ineligibleForTaxRelief boolean True if payments from this arrangement cannot benefit from Gift Aid or equivalent tax relief
acknowledgementPersonalisation string Custom text used when generating thank-you communications for payments from this arrangement
paymentMethod string Reference to the payment method used (e.g. Direct Debit)
bankAccount string Reference to the bank account involved
collectionSystem string Reference to the collection system used to handle the transfer (e.g. GoCardless, Stewardship, CAF) — configured in Payment Settings
team string Internal team or department this arrangement is attributed to
breakdown object[] Itemised split for coding payments. Each item: Purpose, TermsOfRestriction, Amount, Percentage
createdAt timestamp When the record was created
updatedAt timestamp When the record was last modified

Fundraising activity

An activity undertaken by the charity or its supporters to facilitate or encourage donations or engagement. Analogous to a Source Code or Campaign.

Field Type Description
fundraisingActivityId string (UUID) Unique identifier for the fundraising activity
name string Name of the activity or campaign
description string What the activity involves and its purpose
type enum Category of activity: Campaign, Appeal, Event, Challenge, Grant, RegularGiving, Other
status enum Current state: Draft, Active, Completed, Cancelled
startDate date Date the activity begins or began
endDate date Date the activity ends or ended; null if open-ended
target number (decimal) Fundraising income target in the reporting currency
currency string (ISO 4217) Currency of the target amount
leadContactId string (UUID) Contact responsible for running or championing this activity
organisationId string (UUID) Organisation hosting or sponsoring this activity, if applicable
notes string Free-text notes
tags string[] User-defined labels for filtering and segmentation
createdAt timestamp When the record was created
updatedAt timestamp When the record was last modified

See Fundraising activity fields for the full field reference.

File Attachments

File attachment

A file uploaded by a user and linked to one or more data entities. The FileAttachments service centralises upload and metadata storage so individual modules do not need their own file-handling logic.

Touchpoints and Payments currently accept file attachments from the UI. Cases are supported by the service but not yet surfaced in the Case Management UI.

Field Type Description
attachmentId string (UUID) Unique identifier for the attachment
tenantId string Tenant the attachment belongs to
fileName string Original file name as provided by the uploader
contentType string (MIME) MIME type of the file (e.g. application/pdf, image/png)
sizeBytes number File size in bytes
s3Key string S3 object key where the file is stored
s3Bucket string S3 bucket name
uploadedBy string (UUID) ID of the user who uploaded the file
status enum Lifecycle state: pending (uploaded but not yet confirmed), available (confirmed and accessible), deleted (soft-deleted)
linkedEntities object[] Entities this file is attached to. Each item contains: entityType (Case, Payment, or Touchpoint) and entityId (UUID)
createdAt timestamp When the attachment was confirmed
deletedAt timestamp When the attachment was deleted; absent if not deleted