Skip to main content

Custom Data Services: Finalsite Enrollment External API

Josh Fulton
  • Updated

Overview

This article provides a general overview of the concepts underlying the Finalsite Enrollment API and how to best use the API for success. 

The Finalsite Enrollment API is built on RESTful principles and is meant for retrieving information from a specific Finalsite Enrollment site. At this time, the Finalsite Enrollment API is read-only, meaning only GET requests are accepted and no data can be written to the system via the API.

The API is only accessible through HTTPS.

Important Notes and Considerations:

  • Our Support team is not able to assist with the development of this feature.

  • Access to the API is an add-on.
    • Please contact your client success manager if you would like to purchase access.

  • Most schools work with a programming engineer to help them build the API to map to their desired third party.

Once you have been approved and paid for the External API, a member of the Finalsite Enrollment team will enable the feature for you.

Once enabled, any System Admin with Data permissions will be able to access the External API Documentation and Credentials from within Settings > Fields & Data.

In this article

Authentication

The API uses JSON Web Tokens (JWTs) to authenticate requests.

An API credential ID and API secret are required to create a valid JWT. The ID identifies an API credential belonging to an API user and is used as part of generating the token. The secret is used to sign the token.

The JWT must be generated with the following claims and signed with the corresponding secret:

 {"sub": "api_credential_id",
  "name": "human readable name that identifies the calling program",
  "exp": "expiration time in seconds since epoch"}

Expiration Time

This field specifies when the token will expire.

  1. Value is a Unix Epoch Timestamp - The number of seconds that have elapsed since January 1st 1970, 12:00:00 AM UTC
  2. The expiration can be no more than sixty minutes in the future.

Authorization Header

The generated token must then be included in the Authorization header as Bearer token, for example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlJvZ2VyIFdpbGNvIiwiaWF0IjoxNTE2MjM5MDIyfQ.2fA2T6_92g3xomqL0IjrW_6XMBafS9uU1LRGRaAUmKE
 

Content-Type

The API returns all responses as JSON.

Expandable Attributes

Some endpoints support optional attributes, which might include deeper information about related objects.

Objects marked as x-expandable in endpoint documentation can be included or excluded using the includes and excludes request parameters.

For example, the contacts endpoint includes information minimal information about each contact's relatives by default. A full Contact object for each relative can be optionally included by specifying the ?includes=contacts.relationships.contactrequest parameter.

Pagination

Endpoints with pagination will return a maximum of 100 objects. When more than 100 objects are returned, the response will include a meta key containing a next_cursor, for example:

{meta: {next_cursor: 'MjVkMjE3NDctM2MwYS0xMWVjLThlMGEtMDI0MmFjMTIwMDA1'}}

This cursor must be included as a query param in the next request with the key cursor in order to retrieve the next set of results. When there are no more results, the next_cursor will be returned as nil.

Rate Limiting

Requests to the API are rate-limited to a rate of 15 requests per 10 seconds. Requests that exceed this limit will return a 429 response with a Retry-After header specifying how long to wait before the next request.

Response Statuses

The API uses the following standard HTTP response statuses.

Status Code                                 Description
200 OK The request succeeded. The body of the response should be a json object with the requested data.
401 Unauthorized The authorization data provided was not valid.
404 Not Found The requested resource could not be found. You may be trying to access a record that does not exist, or you may have supplied an invalid URL.
429 Too Many Requests You will see this response if you've exceeded the rate limit. This response should include a Retry-After (see Rate Limiting).
500 Internal Server Error An unexpected error has occurred. This response should include a JSON error object describing what went wrong.
 

Versioning

The API uses a single major version number. This version number is incremented whenever breaking changes are introduced. This version is an integer, specified with the header X-Api-Version. For example:

X-Api-Version: 1

It is always recommended to use the latest version of an endpoint available. The version will not be updated when the following occurs:

  1. Non-breaking, backwards-compatible change are introduced
  2. New attributes are added to a result
  3. Validations are added to prevent bad data from entering the system

 

Related Articles

Related articles

Comments

0 comments

Article is closed for comments.