Table of Contents:
Overview
Certain objects in your NationBuilder database have associations, or relationships, with each other. For example, Signups can belong to a Recruiter, and Memberships can belong to a Signup. These associations should not be confused with relationship objects in NationBuilder. When two objects are accessible through an API endpoint and have an association, they are referred to as connected resources. The diagram below outlines the relationships between these connected resources, such as between a Signup and a Recruiter.
Types of relationships
Relationships may be to-one or to-many.
To-One
A to-one relationship in NationBuilder's API refers to a connection between two objects where one object is associated with one instance of another object.
One-to-One: When each instance of an object is tied to exactly one instance of another object, and vice versa. Both objects are uniquely related to one another.
Example: Signups and Signups Profiles. A Signup may only have one Signup Profile and a Signup Profile may only ever belong to one Signup.
โMany-to-One: When multiple instances of one object are associated with one instance of another object. In this relationship, one object may have many related instances, but each instance is linked to a single parent.
Example: Signups and Memberships. A Membership belongs to one Signup, but a Signup may have many Memberships.
To-Many
This relationship indicates a one-to-many relationship, where one instance of an object can be associated with many instances of another object.
To-Many: When one instance of an object can be associated with many instances of another object.
Example: Recruiters and Signups. A Recruiter may have many Signups, but a Signup can only belong to one Recruiter.
โMany-to-Many: When multiple instances of one object can be associated with multiple instances of another object.
Example: Signups and Signup Tags. A Signup may have many Tags, and a Tag can belong to many Signups.
Sideposting and Sideloading
When accessing certain resources via the API, it is possible to simultaneously view, create, or update that resource along with its connected resource via sideloading and sideposting. Resources that have relationships with each other can be created, updated, or retrieved in the same request as their connected resources. When sideposting or sideloading, any resource can be accessed as long as it has a relationship to the primary resource, it does not matter what the relationship is. For example, a membership can be updated via a post to the signup resource, and a signup can be updated via a post to the membership resource.
Examples of sideposting and sideloading can be found in our core concepts article here.
Resources and their Relationships to Connected Resources
Below are all the resources and their relationships with other resources. When a resource has a relationship with an object that does not have its own dedicated resource, the related resource is specified. For example, the Recruiter object does not have its own resource, but Recruiter objects can be accessed through the Signup resource. For instance, a donation's recruiter is accessed through the Signup resource, so it is documented as Recruiter (SignupResource)
under the Donation resource.
Resource | Connected Resource | Relationship |
Automation Enrollment | Automation | To-One |
Automation Enrollment | Signup | To-One |
Automation | Enrollments (AutomationEnrollmentResource) | To-Many |
Ballot | Election | To-One |
Ballot | Voter | To-One |
Broadcaster | Point Person (SignupResource) | To-One |
Broadcaster | Voicemail Point Person (SignupResource) | To-One |
Broadcaster | Text Point Person (SignupResource) | To-One |
Broadcaster | Mailings | To-Many |
Broadcaster | Signups | To-Many |
Contact | Signup | To-One |
Contact | Author (SignupResource) | To-One |
Donation | Author (SignupResource) | To-One |
Donation | Donation Tracking Code | To-One (as tracking_code) |
Donation | Import | To-One |
Donation | Membership | To-One |
Donation | Page | To-One |
Donation | Payment Type | To-One |
Donation | Pledge | To-One |
Donation | Mailing | To-One |
Donation | Recruiter (SignupResource) | To-One |
Donation | Signup | To-One |
Donation Tracking Code | Donations | To-Many |
Election | Ballots | To-Many |
Event | Auto Response Broadcaster (BroadcasterResource) | To-One |
Event | Page (PageResource) | To-One |
Event | Point Person (SignupResource) | To-One |
Event | Tracking Code (DonationTrackingCodeResource) | To-One |
Event | RSVPs (EventRsvpResource) | To-Many (as rsvps) |
Event | Ticket Levels (EventTicketLevelResource) | To-Many (as ticket_levels) |
Event RSVP | Author (SignupResource) | To-One |
Event RSVP | Event Page (EventResource) | To-One |
Event RSVP | Ticket Level (EventTicketLevelResource) | To-One |
Event RSVP | Recruiter (SignupResource) | To-One |
Event RSVP | Signup | To-One |
Event Ticket Level | Event Page (EventResource) | To-One |
Event Ticket Level | RSVPs (EventRsvpResource) | To-Many (as rsvps) |
Import | Point Person (SignupResource) | To-One |
Import | Author (SignupResource) | To-One |
Import | Terminator (SignupResource) | To-One |
Import | Signups (SignupResource) | To-Many |
Mailing | Author (SignupResource) | To-One |
Membership | Donations | To-Many |
Membership | Membership Type | To-One |
Membership | Signup | To-One |
Membership Type | Page | To-One |
Membership Type | Memberships | To-Many |
Page | Site | To-One |
Page | Membership Types | To-Many |
Path History | Current Step Point Person (SignupResource) | To-One |
Path History | Path Journey | To-One |
Path History | Path Journey Status Change | To-One |
Path History | Point Person (SignupResource) | To-One |
Path History | Recruiter (SignupResource) | To-One |
Path Journey | Signup | To-One |
Path Journey | Path (PathResource) | To-One |
Path Journey | Point Person (SignupResource) | To-One |
Path Journey | Current Step Point Person (SignupResource) | To-One |
Path Journey | Path Journey Status Change | To-One |
Path Journey | Current Step (PathStepResource) | To-One |
Path Journey | Path Histories (PathHistoryResource) | To-Many |
Path Journey Status Change | Path | To-One |
Path Journey Status Change | Path Journeys | To-Many |
Path Journey Status Change | Path Histories | To-Many |
Path | Path Journeys (PathJourneyResource) | To-Many |
Path | Path Steps | To-Many |
Path | Path Journey Status Changes | To-Many |
Path | Default Point Person (SignupResource) | To-One |
Path Step | Path | To-One |
Path Step | Default Point Person (SignupResource) | To-One |
Petition | Petition Signatures (PetitionSignatureResource) | To-Many (as signatures) |
Petition | Page | To-One |
Petition Signature | Page | To-One |
Petition Signature | Petition (as petition_page) | To-One |
Petition Signature | Recruiter (SignupResource) | To-One (as signup) |
Petition Signature | Signup | To-One |
Pledge | Author (SignupResource) | To-One |
Pledge | Donation Tracking Code | To-One (as tracking_code) |
Pledge | Page | To-One |
Pledge | Recruiter (SignupResource) | To-One |
Pledge | Signup | To-One |
Precinct | Point Person (SignupResource) | To-One |
Precinct | Signups | To-Many |
Relationship | First Signup (SignupResource) | To-One |
Relationship | Second Signup (SignupResource) | To-One |
Signup Nation | Signup | To-One |
Signup Profile | Signup | One-To-One |
Signups | Author (SignupResource) | To-One |
Signups | Last Contacted By (SignupResource) | To-One |
Signups | Page | To-One |
Signups | Parent (SignupResource) | To-One |
Signups | Precinct | To-One |
Signups | Recruiter (SignupResource) | To-One |
Signups | Signup Profile | One-To-One |
Signups | Voter | One-To-One |
Signups | Signup Tags (SignupTagResource) | Many-To-Many (as tags) |
Signups | Identity Mappings | To-Many |
Signups | Memberships | To-Many |
Signups | Path Journeys (PathJourneyResource) | To-Many |
Signups | Taggings (SignupTaggingResource) | To-Many |
Signups | Petition Signatures | To-Many |
Signups | Signup Nations | To-Many |
Signups | Signup Sources | To-Many |
Signup Source | Signup | To-One |
Signup Tag | Signups | Many-To-Many |
Signup Tagging | Tag (SignupTagResource) | To-One |
Signup Tagging | Signup | To-One |
Site | Pages | To-Many |
Survey Question Possible Response | Survey Question | To-One |
Survey Question Possible Response | Survey Question Responses (as responses) | To-Many |
Survey Question | Survey | To-One |
Survey Question | Author (SignupResource) | To-One |
Survey Question | Survey Question Responses (as responses) | To-Many |
Survey Question | Survey Question Possible Responses (as possible_responses) | To-Many |
Survey Question Response | Survey Question | To-One |
Survey Question Response | Survey Question Possible Response (as response) | To-One |
Survey Question Response | Signup | To-One |
Survey Question Response | Author (SignupResource) | To-One |
Survey Question Response | Page | To-One |
Survey | Survey Questions | To-Many |
Voter | Signup | One-To-One |
Voter | Ballots | To-Many |