PowerSchool Enrollment API v1 Documentation

Overview

API Key

In order to perform operations using the API, an API key will be needed for authentication. Keys will be provided by PowerSchool Enrollment solution specialists.

API Service Endpoint

All API requests should be made using the following base URL:

https://secure.infosnap.com/api/v1

All requests must use HTTPS.

Authentication

The API supports basic authentication.

When using basic authentication, provide the API key as the username with an empty value for the password.

Input & Output

For certain POST and PUT requests, the request body must sent in the JSON format. Many requests do not require input beyond the URL / route.

All responses will be formatted as JSON.

Dates and Times

All dates and times are provided in Coordinated Universal Time (UTC).

Response Status Codes

For successful requests, you will receive 200 OK.

For errors, you may receive one of the following...

404 Not Found - if the resource you are looking for does not exist.
401 Unauthorized - if you provide an invalid API key as a part of the authentication or if you attempt to access a resource to which you do not have authorization.
500 Internal Server Error - if an unexpected application exception occurs.

Error responses will also include details about the error in the following format.

{
  "message": "DESCRIPTION OF ERROR HERE"
}

Resources

Get API Health Status (WITHOUT Authentication)

Note: this call is at the root level and does not need the version number prepended to it ex. "{server}/api/healthz"

GET /healthz

On success will return an HttpStatusCode.OK (200) and a payload with Status, Software Version and the server DateTime.Now

{
 "Status": "Healthy",
 "SoftwareVersion": "19.5.1.0",
 "DateTimeNow": "7/15/2019 2:40:48 PM (Eastern Standard Time)"
}

Verify Credentials (WITH Authentication)

GET /connection/test

On success will return an HttpStatusCode.OK(200) and a payload with Status, Software Version and the server DateTime.Now

{
 "Status": "Healthy",
 "SoftwareVersion": "19.5.1.0",
 "DateTimeNow": "7/15/2019 2:40:48 PM (Eastern Standard Time)"
}

Invalid Credentials will return an HttpStatusCode.Unauthorized(500) and a payload with an appropriate error message

{
 "message": "You are not authorized to access this resource."
}

Get Published Actions

GET /publishedactions

Returns a list of published actions for your solution.

[
    {
        "id": 123,
        "title": "Enrollment",
        "academicYear": "2008-2009"
    },
    {
        "id": 456,
        "title": "Registration",
        "academicYear": "2009-2010"
    }
]

Get Import Schemas

GET publishedactions/{id}/importschemas

Returns a list of import schemas for a specific published available for the published action.

[
    {
        "id": 1,
        "title": "Sample Schema",
        "fields": [
            "FirstName",
            "MiddleName",
            "LastName",
            "DOB",
            "EmailAddress",
            "ETC..."
        ]
    },
    {
        "id": 2,
        "title": "Another Schema",
        "fields": [
            "stu_FirstName",
            "stu_LastName",
            "stu_ExternalID",
            "stu_Email",
            "stu_Phone",
            "ETC..."
        ]
    }
]

Import Roster Record

POST publishedactions/{publishedactionid}/importschemas/{schemaid}

Creates or updates a roster record based on the data provided. The keys for the data sent in the POST body must match the fields for the specified import schema.


{
    "FirstName": "Susan",
    "LastName": "Smith",
    "ExternalID": "190292",
    "DateOfBirth: "04/20/2007",
    etc...
}

SUCCESS

If the record is imported successfully, the following response is sent.

{
    "status": "Success",
    "errors": []
}

ERROR

If there were problems importing the data, the following response is sent.

{
    "status": "Error",
    "errors": [
        "Description of problem.",
        "Another problem here.",
        "etc..."
    ]
}

Get Delivery Targets

GET /deliverytargets

Returns a list of available delivery targets for your solution. Delivery targets define the specific details for the formatting of records delivered through the API. Delivery targets are set up by PowerSchool Enrollment solution specialists.

[
  {
    "id": 123,
    "title": "Title here"
  },
  {
    "id": 456,
    "title": "Title here"
  }
]

Create Batch

POST /deliverytargets/{targetid}/createbatch

Creates and returns the next batch of available submission records. Once form submission records are completed by families, they must go through some level of administrative review within the Admin Portal. Once these records have been approved for delivery, they become available for delivery. In order to retrieve the current set of records which are available for delivery, use this API call.

Note: Any call that makes changes to data in the system uses POST. In this case, each record's delivery history is updated as a result of this request.

{
  "id": "11fdbe9d-801a-4b8e-bc12-a2d8f7ac8cdc",
  "date": "2012-10-08T02:10:53Z",
  "records": [
    {
      "id": 123,
      "submitted": "2011-10-13T16:50:53Z",
      "data": {
        "student": {
          "studentID": "33765833",
          "firstName": "Alice",
          "lastName": "Smith",
          "grade": "4",
          "gender": "F"
        },
        "parent1": {
          "studentID": "33765833",
          "relationship": "Father",
          "firstName": "John",
          "lastName": "Smith",
          "homePhone": "444-444-4444",
          "email": "john@smith.com"
        },
        "parent2": {
          "studentID": "33765833",
          "relationship": "Mother",
          "firstName": "Jane",
          "lastName": "Smith",
          "homePhone": "444-444-4444",
          "email": "jane@smith.com"
        }
      }
    }
  ]
}

An empty batch would look like this:

{
  "id": "11fdbe9d-801a-4b8e-bc12-a2d8f7ac8cdc",
  "date": "2012-10-08T02:10:53Z",
  "records": []
}

Get Batches

GET /deliverytargets/{targetid}/getbatches/{date}{getAutoOpen}

Gets a list of previously delivered batches for the specific delivery target with optional date and optional getAutoOpen flag. getAutoOpen will return only batches that have a status of AutoOpen. (Current running batches will have this status)

Note: The results do not include records that were delivered as a part of that batch, only the batch details. In order to deliver the records again, you must first reset the records by resetting the batch.

Note: The format for the date argument must be yyyy-mm-dd (e.g. 2012-10-03).

Note: The format for the getAutoOpen flag is true / false. (default is false)

[
  {
    "id": "a0ae7615-aa9a-4f39-b186-3014455dc794",
    "date": "2012-04-22T13:15:30Z",
    "records": []
  },
  {
    "id": "7a67ba88-2cae-42f9-af54-ece0193800cc",
    "date": "2012-04-24T11:20:12Z",
    "records": []
  },
  {
    "id": "5a6436e9-99aa-4003-a758-d069994eb97a",
    "date": "2012-04-28T05:44:14Z",
    "records": []
  }
]

An empty result set would simply be an empty JSON array.

[]

Reset Batch

POST /deliverytargets/{targetid}/resetbatch/{batchid}

Resets the records that were part of a previously delivered batch so thay they may be delivered once more. Also closes said batch in the event that it's open

A successful response will return a 204 HTTP status code.

If the delivery batch does not exist then a 404 HTTP status code is returned.

Get Checklists

GET /checklists

Returns a list of checklists for your solution.

[
    {
        "id": 435,
        "title": "Music",
        "academicYear": "2013-2014"
    },
    {
        "id": 477,
        "title": "Visual Arts",
        "academicYear": "2014-2015"
    }
]

Get Checklist Details

GET checklists/{id}

Returns the details of a specific checklist.

[
    {
        "id": 123,
        "title": "My Checklist",
        "academicYear": "2013-2014",
        "items": [
            {
                "id": "83838",
                "itemType": "Photo",
                "externalID": "232323",
                "name": "Photo",
                "description": "School photo."
            },
            {
                ...
            }
        ]
    }
]

Get Checklist Entries

GET checklists/{id}/checklistentries

Returns the checklist entries for a specific checklist.

[
    {
        "id": 12345,
        "externalStudentID": "34343",
        "familyMemberFirstName": "John",
        "familyMemberLastName": "Doe",
        "grade" : "8",
        "familyEmailAddress": "janedoe@acme.com",
        "checklistItems": [
            {
                "checklistItemID": "83838",
                "status": "Completed",
                "dateCompleted": "02/03/2015",
                "adminNote": "Hello",
                "publicNote": "World"
            },
            {
                ...
            }
        ]
    },
    {
        ...
    }
]

Get Roster Records

GET publishedactions/{id}/rosterrecords

Returns a list of roster records for a specific published action.

[
    {
        "metadata": {
            "page": 1,
            "pageSize": 25,
            "pageCount": 3,
            "recordCount": 62
        },
        "records": [
            {
                ...roster record data here...
            }
        ]
    }
]

The paging parameters are:

page - the page number to return
pagesize - the maximum records to return on a page

For example, to get to the second page and set the page size to 50:
GET /publishedactions/:id/rosterrecords?page=2&pagesize=50

If a request does not include paging parameters, the defaults are page=1 and pagesize=50.

The search parameters are:

status - filter by roster record status

ImportedAdded
NotifiedNotStarted
Started
Submitted
OnHold
Discarded

For example, to get records with a "status" of "Submitted":
GET /publishedactions/:id/rosterrecords?status=Submitted

tag - filter by tag (tag values are implementation dependent)

For example:
GET /publishedactions/:id/rosterrecords?tag=Some Tag Name

If a request does not include search parameters, the default is all records.

Get Roster Record

GET /rosterrecords/{id}

Returns the details for a specific roster record by id.

[
    {
        "id": 12345,
        "status": "Submitted",
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "2000-04-15T00:00:00",
        "externalStudentID": "123",
        "externalFamilyID": "456",
        "household": "Primary",
        "school": "Cedar Park",
        "grade": "3",
        "enrollStatus": "Enrolled",
        "imported": "2011-04-13T08:40:19",
        "started": 2011-06-08T16:53:05",
        "submitted": "2011-06-08T16:53:33",
        "tags": [
            "Tag A",
            "Tag B",
            ...
        ],
        "dataItems": {
            "stu_FirstName": "John",
            "stu_LastName":  "Doe",
            "AnotherFieldName": "Another Value Here",
            ...
        }
    }
]

Get Submission Records

GET publishedactions/{id}/submissionrecords

Returns a list of submission records for a specific published action.

[
    {
        "metadata": {
            "page": 1,
            "pageSize": 25,
            "pageCount": 3,
            "recordCount": 62
        },
        "records": [
            {
                ...submission record data here...
            }
        ]
    }
]

The paging parameters are:

page - the page number to return
pagesize - the maximum records to return on a page

For example, to get to the second page and set the page size to 50:
GET /publishedactions/:id/submissionrecords?page=2&pagesize=50

If a request does not include paging parameters, the defaults are page=1 and pagesize=50.

The search parameters are:

status - filter by submission record status

PendingImport
PendingApproval
Approved
Discarded

For example, to get records with a "status" of "Approved":
GET /publishedactions/:id/submissionrecords?status=Approved

tag - filter by tag (tag values are implementation dependent)

For example:
GET /publishedactions/:id/submissionrecords?tag=Some Tag Name

If a request does not include search parameters, the default is all records.

Get Submission Record

GET /submissionrecords/{id}

Returns the details for a specific submission record by id.

[
    {
        "id": 12345,
        "status": "PendingApproval",
        "firstName": "Jane",
        "lastName": "Doe",
        "dateOfBirth": "2000-04-15T00:00:00",
        "externalStudentID": "123",
        "externalFamilyID": "456",
        "household": "Primary",
        "school": "Cedar Park",
        "grade": "3",
        "enrollStatus": "Enrolled",
        "imported": "2011-04-13T08:40:19",
        "started": 2011-06-08T16:53:05",
        "submitted": "2011-06-08T16:53:33",
        "tags": [
            "2nd Grader",
            "Polished",
            ...
        ],
        "dataItems": {
            "stu_FirstName": "Jane",
            "stu_LastName":  "Doe",
            "AnotherFieldName": "Another Value Here",
            ...
        }
    }
]

Create Single Submission

POST /submission

This endpoint accepts a JSON object in the request body that represents a single submission with the following properties:

publishedActionId: The ID number of the published action. (required)
submission: An array of data items containing form field names and their corresponding values. (required)


    {
        "publishedActionId": 12345,
        "submission": {
            "dataItems": [
                { 
                    "fieldName": "stu_FirstName",
                    "value": "Jane"
                },
                { 
                    "fieldName": "stu_LastName",
                    "value": "Doe"
                },
                    { 
                    "fieldName": "stu_DateOfBirth",
                    "value": "01/01/2010"
                }
            ]
        }
    }

Responses

Success

201 Created No content is returned.

Errors

400 Bad Request The request payload is empty or contains invalid data.

{
    "message": "The following validation errors are present in your request.",
    "errors": [
        {
            "message": "The data item is required.",
            "field": "stu_FirstName"
        }
    ]
}

401 Unauthorized Invalid basic authentication token (API key) or insufficient access to requested resource.

403 Forbidden The published action is private or is in a closed state.

{
    "message": "The following validation errors are present in your request.",
    "errors": [
        {
            "message": "The form associated with publishedActionId 12345 is closed.",
            "field": null
        }
    ]
}

405 Method Not Allowed The published action has special features enabled.
429 Too Many Requests Indicates too many requests have been received in a given amount of time. The Retry-After header is included to the response informing how many seconds to wait before making a new request.

500 Internal Server Error An application error occurred while processing the request.

{
    "message": "An error occurred processing the request. Please contact support and reference the following message ID: [df7e299e-624e-4b89-b004-2461737a15ac].",
    "errors": []
}

Get Document URL

GET documents/{objectId}

Returns the azure blob storage URL of the document if it exists and belong to the customer requesting it.

https://regsigdevstorage.blob.core.windows.net/secure-uploadeddocuments-832/832775f6-6d82-4ead-9f13-b7c2fb406b48?sv=2019-02-02&st=2020-06-19T07%3A17%3A00Z&se=2020-06-19T07%3A19%3A00Z&sr=b&sp=r&sig=4%2B5CZ4wZ8ivPoJQf%2F8Pt0XsbBYJIirItCxQINFVOFKc%3D

Get Document URL with ContentDisposition & ContentType

GET documents/document/url?file={base64_encoded_file_name}&providerDocUID={base64_encoded_file_guid}

Returns the azure blob storage URL of the document if it exists and belong to the customer requesting it with ContentDisposition & ContentType as per the provided querystring parameters.

Example: https://dev1.registration.powerschool.com/api10/v1/documents/document/url?file=eHl6LmpwZw==&providerDocUID=ODMyNzc1ZjYtNmQ4Mi00ZWFkLTlmMTMtYjdjMmZiNDA2YjQ4 will return something like:

https://regsigdevstorage.blob.core.windows.net/secure-uploadeddocuments-832/832775f6-6d82-4ead-9f13-b7c2fb406b48?sv=2017-07-29&sr=b&sig=4XgSXEAXWyFMSss7Rc0%2FEjLAV3Hc%2FHKo4Bv0m6nf2g8%3D&se=2020-08-10T18%3A10%3A54Z&sp=r&rsct=image%2Fjpeg&rscd=attachment%3B%20filename%3D%22xyz.jpg%22