The finalsite API is a REST-based web service which provides access to the following data in the finalsite CMS
In addition, the API provides functionality to login to the API itself and to authenticate users
The API supports Create, Read, Update and Delete functionality if the API user's permissions allow it and if the web service endpoint itself support that behavior.
The finalsite API relies on a number of conventions and assumptions to make the software, documentation, examples, and response information as consistent and accurate as possible. These API conventions are outlined here. Please read this section carefully as this will greatly help you in implementing the finalsite API.
To best use the finalsite API you should be familiar with the back-end modules and tools of the finalsite CMS, such Constituent Manager and Group Manager.
The finalsite API supports the following three HTTP Methods. These methods are sometimes referred to as verbs or CGI Methods.
PUT is not supported.
As you will see throughout the documentation, the HTTP Method drives the 'action' and there is a logical correspondence between the action you are trying to carry out and the Method you will use to do so. For example, GET is used to fetch data from the finalsite API, whereas a POST can be used to send data into the API. The only exceptions to this rule are login endpoints: for reasons of security, sensitive data is POSTed and thus the Method required is POST.
NOTE: All requests to the API must include a User-Agent header set (enforced as of 8/1/2018)
The finalsite API, like other REST-based web services, uses HTTP Basic Authentication. All web service endpoints require a username and password and these must be sent as an HTTP Authorization header, formatted according to the specification. For added security, we have extended the HTTP Basic Authentication model as follows:
By default, the API returns all data as XML. Adding ReturnFormat=json to any of your requests will return the data as JSON instead.
NOTE: Specifying ReturnFormat=json means XML data validation is not applied to the data returned by the API. See also Data Validation, below
A number of parameters that can be passed into our API are lists (lists of Constituent ImportIDs, for example), and have the format <paramname>_List. All lists are to be comma-separated and we recommend that they be URL encoded for maximum compatibility.
By default, all data passed into the API and returned from the API is XML-validated. However, since data currently in a finalsite CMS may not be fully Schema-compliant at all times (for example, a Degree Year may be stored as '90 instead of 1990), you have the option of disabling validation for data that is returned from the API, by using the ValidateResult=0 parameter. Data that is POSTed to the API must always be valid according to the finalsite XML Schema. Please note that the ValidateResult parameter is available everywhere and is not documented on each of the endpoint documentation pages.
NOTE: XML data validation is NOT applied to data returned by the API if ReturnFormat=json is used.
At object level (e.g. Constituent, Group, Household, and so on):
Within object XML data all elements except the ImportID are optional although element order is enforced (see the data structure for each object for more information).
The finalsite API provides the ability to run in 'debug mode'. Using this option instructs the API to return more detailed information about what is happening (or, more likely, what is going wrong!). You can enable this option by using the by using the DebugMode=1 parameter. Please note that the DebugMode parameter is available everywhere and is not documented on each of the endpoint documentation pages.
All examples use cURL, a command-line utility for getting or sending data using URL syntax and methods. We use the following cURL command-line options in our examples:
Other usefule cURL command line option are:
For more information consult the cURL man pages on your system or use Google.
Please also note the following conventions used throughout our examples:
Target Namespace | http://www.finalsite.com/apidata/v1.0 |
---|---|
Element and Attribute Namespaces |
|
Prefix | Namespace |
---|---|
xs | http://www.w3.org/2001/XMLSchema |
tns | http://www.finalsite.com/apidata/v1.0 |
xml | http://www.w3.org/XML/1998/namespace |
Name | AthleticCombined |
---|---|
Type | tns:AthleticCombined |
Nillable | no |
Abstract | no |
Name | AthleticEvents |
---|---|
Type | tns:AthleticEvents |
Nillable | no |
Abstract | no |
Name | AthleticLocations |
---|---|
Type | tns:AthleticLocations |
Nillable | no |
Abstract | no |
Name | AthleticOpponents |
---|---|
Type | tns:AthleticOpponents |
Nillable | no |
Abstract | no |
Name | AthleticSports |
---|---|
Type | tns:AthleticSports |
Nillable | no |
Abstract | no |
Name | AthleticTeams |
---|---|
Type | tns:AthleticTeams |
Nillable | no |
Abstract | no |
Name | CalendarEvents |
---|---|
Type | tns:CalendarEvents |
Nillable | no |
Abstract | no |
Name | Calendars |
---|---|
Type | tns:Calendars |
Nillable | no |
Abstract | no |
Name | ConstituentMemberships |
---|---|
Type | tns:ConstituentMemberships |
Nillable | no |
Abstract | no |
Name | Constituent_With_Memberships |
---|---|
Type | tns:Constituent_With_Memberships |
Nillable | no |
Abstract | no |
Name | Constituents |
---|---|
Type | tns:Constituents |
Nillable | no |
Abstract | no |
Name | Constituents_With_Memberships_And_Relationships |
---|---|
Type | tns:Constituents_With_Memberships_And_Relationships |
Nillable | no |
Abstract | no |
Name | Duplicate_id_Collection |
---|---|
Type | tns:Duplicate_id_Collection |
Nillable | no |
Abstract | no |
Name | Events |
---|---|
Type | tns:Events |
Nillable | no |
Abstract | no |
Name | GroupMemberships |
---|---|
Type | tns:GroupMemberships |
Nillable | no |
Abstract | no |
Name | Groups |
---|---|
Type | tns:Groups |
Nillable | no |
Abstract | no |
Name | Households |
---|---|
Type | tns:Households |
Nillable | no |
Abstract | no |
Name | Memberships |
---|---|
Type | tns:Memberships |
Nillable | no |
Abstract | no |
Name | NewsCategories |
---|---|
Type | tns:NewsCategories |
Nillable | no |
Abstract | no |
Name | NewsPosts |
---|---|
Type | tns:NewsPosts |
Nillable | no |
Abstract | no |
Name | Relationships |
---|---|
Type | tns:Relationships |
Nillable | no |
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: |
|
Name | Address |
---|---|
Abstract | no |
Documentation | Core Address complexType. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticCombined |
---|---|
Abstract | no |
Parent type: | tns:Event (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | AthleticEvent |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticEventMeta |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticEvents |
---|---|
Abstract | no |
Parent type: | tns:Address (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | AthleticLocation |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticLocations |
---|---|
Abstract | no |
Parent type: | tns:Address (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | AthleticOpponent |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticOpponents |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticSport |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticSports |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticTeam |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticTeamIDs |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | AthleticTeams |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Calendar |
---|---|
Abstract | no |
Parent type: | tns:Event (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | CalendarEvent |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | CalendarEventMeta |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | CalendarEvents |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | CalendarIDs |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Calendars |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: |
|
Name | Constituent |
---|---|
Abstract | no |
Documentation | Container element for constituent data. Empty or NULL elements get ignored on upload. For "Get" methods, empty or NULL values are not returned. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | ConstituentGroup |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | ConstituentGroups |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | ConstituentMembership |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | ConstituentMemberships |
---|---|
Abstract | no |
Parent type: | tns:Constituent (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | Constituent_In |
---|---|
Abstract | no |
Documentation | Constituent Complex Type for input structure. Input structure supports only those elements defined the in core Constituent Complex Type. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Constituent_With_Memberships |
---|---|
Abstract | no |
Documentation | Container element for constituents. Must contain one or more Constituent elements. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Constituents |
---|---|
Abstract | no |
Documentation | Container element for constituents. Must contain one or more Constituent elements. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Constituents_With_Memberships |
---|---|
Abstract | no |
Documentation | Container element for Constituent_With_Memberships. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Constituents_With_Memberships_And_Relationships |
---|---|
Abstract | no |
Documentation | Container element for constituents and relationships. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Duplicate_id_Collection |
---|---|
Abstract | no |
Documentation | Element which will hold a master importId, the service, the corresponding table, and the duplicate id's to be merged together. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Emails |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: |
|
Name | Event |
---|---|
Abstract | no |
Documentation | Core event compexType. Same structure is returned for all events. CalendarEventMetaData is returned for calendar events, AthleticEventMetaData for Athletic events. Only one or the other is returned. All times are UTC |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Events |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Feed |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Feeds_out |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: |
|
Name | Group |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | GroupConstituent |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | GroupConstituents |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | GroupMembership |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | GroupMemberships |
---|---|
Abstract | no |
Parent type: | tns:Group (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | Group_In |
---|---|
Abstract | no |
Documentation | Group Complex Type for input structure. Input structure supports only those elements defined the in core Group Complex Type. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Groups |
---|---|
Abstract | no |
Documentation | Container element for groups. Must contain one or more Group elements. |
Parent type: | tns:Address (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | HouseHoldAddress |
---|---|
Abstract | no |
Documentation | Extends core Address complexType and adds household-specific elements. On input (POST methods) a black Address1, Address2, Address3, City, and Zip will delete the address of this AddressType from the DB. |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | HouseHoldAddresses |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Household |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Households |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: |
|
Name | ImportID |
---|---|
Abstract | no |
Parent type: | tns:ImportID (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | ImportID_Out |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: |
|
Name | ImportIDs |
---|---|
Abstract | no |
Parent type: | tns:ImportIDs (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | ImportIDs_Person |
---|---|
Abstract | no |
Parent type: | tns:ImportIDs (derivation method: extension) |
---|---|
Direct sub-types: | None |
Name | ImportIDs_Related |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Info |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Membership |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Memberships |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | NewsCategories |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | NewsCategory |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | NewsPost |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | NewsPosts |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Phone |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Phones |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Relationship |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Relationships |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Roster |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | RosterMembership |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | School |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Schools |
---|---|
Abstract | no |
Parent type: | None |
---|---|
Direct sub-types: | None |
Name | Service |
---|---|
Abstract | no |
Parent type: | xs:string (derivation method: restriction) |
---|---|
Direct sub-types: | None |
Name | fsEmailAddress |
---|---|
Content |
|
Parent type: | xs:string (derivation method: restriction) |
---|---|
Direct sub-types: | None |
Name | fsEventType |
---|---|
Content |
|
Parent type: | xs:string (derivation method: restriction) |
---|---|
Direct sub-types: | None |
Name | fsGender |
---|---|
Content |
|
Parent type: | xs:string (derivation method: restriction) |
---|---|
Direct sub-types: | None |
Name | fsRights |
---|---|
Content |
|
Parent type: | xs:string (derivation method: restriction) |
---|---|
Direct sub-types: | None |
Name | fsStatus |
---|---|
Content |
|
Parent type: | xs:string (derivation method: restriction) |
---|---|
Direct sub-types: | None |
Name | fsYear |
---|---|
Content |
|
Abstract (Applies to complex type definitions and element declarations). An abstract element or complex type cannot used to validate an element instance. If there is a reference to an abstract element, only element declarations that can substitute the abstract element can be used to validate the instance. For references to abstract type definitions, only derived types can be used.
All Model Group Child elements can be provided in any order in instances. See: http://www.w3.org/TR/xmlschema-1/#element-all.
Choice Model Group Only one from the list of child elements and model groups can be provided in instances. See: http://www.w3.org/TR/xmlschema-1/#element-choice.
Collapse Whitespace Policy Replace tab, line feed, and carriage return characters with space character (Unicode character 32). Then, collapse contiguous sequences of space characters into single space character, and remove leading and trailing space characters.
Disallowed Substitutions
(Applies to element declarations). If substitution is specified, then substitution group members cannot be used in place of the given element declaration to validate element
instances. If derivation methods, e.g. extension, restriction, are specified, then the given element declaration will
not validate element instances that have types derived from the element declaration's
type using the specified derivation methods. Normally, element instances can override
their declaration's type by specifying an xsi:type
attribute.
Key Constraint Like Uniqueness Constraint, but additionally requires that the specified value(s) must be provided. See: http://www.w3.org/TR/xmlschema-1/#cIdentity-constraint_Definitions.
Key Reference Constraint Ensures that the specified value(s) must match value(s) from a Key Constraint or Uniqueness Constraint. See: http://www.w3.org/TR/xmlschema-1/#cIdentity-constraint_Definitions.
Model Group Groups together element content, specifying the order in which the element content can occur and the number of times the group of element content may be repeated. See: http://www.w3.org/TR/xmlschema-1/#Model_Groups.
Nillable
(Applies to element declarations). If an element declaration is nillable, instances
can use the xsi:nil
attribute. The xsi:nil
attribute is the boolean attribute, nil, from the http://www.w3.org/2001/XMLSchema-instance namespace. If an element instance has an xsi:nil
attribute set to true, it can be left empty, even though its element declaration
may have required content.
Notation A notation is used to identify the format of a piece of data. Values of elements and attributes that are of type, NOTATION, must come from the names of declared notations. See: http://www.w3.org/TR/xmlschema-1/#cNotation_Declarations.
Preserve Whitespace Policy Preserve whitespaces exactly as they appear in instances.
Prohibited Derivations (Applies to type definitions). Derivation methods that cannot be used to create sub-types from a given type definition.
Prohibited Substitutions (Applies to complex type definitions). Prevents sub-types that have been derived using the specified derivation methods from validating element instances in place of the given type definition.
Replace Whitespace Policy Replace tab, line feed, and carriage return characters with space character (Unicode character 32).
Sequence Model Group Child elements and model groups must be provided in the specified order in instances. See: http://www.w3.org/TR/xmlschema-1/#element-sequence.
Substitution Group Elements that are members of a substitution group can be used wherever the head element of the substitution group is referenced.
Substitution Group Exclusions (Applies to element declarations). Prohibits element declarations from nominating themselves as being able to substitute a given element declaration, if they have types that are derived from the original element's type using the specified derivation methods.
Target Namespace The target namespace identifies the namespace that components in this schema belongs to. If no target namespace is provided, then the schema components do not belong to any namespace.
Uniqueness Constraint Ensures uniqueness of an element/attribute value, or a combination of values, within a specified scope. See: http://www.w3.org/TR/xmlschema-1/#cIdentity-constraint_Definitions.