OpenApply API openapply

You should implement the OpenApply (OA) Public API in a RESTful manner, using JSON over HTTP. Based on REST principles, the API uses three HTTP verbs: GET, POST and PUT.

The purpose of this API is to allow you to integrate 3rd party databases to automate the creation or update of users, including assignment into their classes.

Authentication & authorization

You can make API requests via HTTPS between the 3rd party database and OA. You authenticate all requests between the API the sub-domain with a unique product API token using HTTP Basic Access Authentication.

You can generate an API token manually via the Settings > Integrations menu item of the OpenApply web app.

Finding the public API key

Enable the Public API function and then add the API token for the integrated applications.

Requests

All requests must access resources from this API entry point with the authentication token.

For example, when accessing student resources:

GET https://<school_subdomain>.openapply.com/api/v1/students? auth_token=2a8b196ee0af6cfa3509961fb573a8a3

Responses

If a request fails, it returns the error as an HTTP status code with the range 400 - 599. Successful requests return a status code of 200 or 201.

Response Reason
HTTP/1.1 200 OK A successful request.
HTTP/1.1 201 Created The request created a new record (i.e. a new user logged to ManageBac and an account has been provisioned).
HTTP/1.1 401 Not authorized An authentication token was not provided or was incorrect.
HTTP/1.1 404 Not Found The requested record doesn’t exist, or the authenticated user doesn’t have access to the record.
HTTP/1.1 400 Bad Request If you PUT or POST a resource with invalid JSON.
HTTP/1.1 500 Internal Server Error An error occurred while processing a request.

Resources reference

Students

Retrieve all students

GET students/

Return up to 1000 (default is 100) student records sorted by id. The response also includes the list of parents associated with the students.

Optional parameters

Parameter Description
count Specifies the number of students to retrieve, up to a maximum of 1000.
since_id Return results with an ID greater than the specified ID.
since_date Return results updated since the specified date or time, e.g. 2013-09-23 or 2013-09-25 02:10:39.

Example request

GET https://<school_subdomain>.openapply.com/api/v1/students

Example response:

HTTP/1.1 200 OK
{
  "students": [
    {
      "id": 1,
      "name": "Chloe Epelbaum",
      "first_name": "Chloe",
      "last_name": "Epelbaum",
      "other_name": "",
      "preferred_name": "",
      "birth_date": "1999-01-29",
      "gender": "female",
      "enrollment_year": 2013,
      "sibling_ids": [ 112, 113 ],
      "full_address": "208 California Street #880, San Francisco, 94111, United States",
      "address": "208 California Street #880",
      "address_ii": null,
      "city": "San Francisco",
      "state": null,
      "postal_code": "94111",
      "country": "United States",
      "nationality": "",
      "student_id": "",
      "passport_id": "",
      "grade": "Grade 2",
      "applicant_id": "00000004",
      "campus": "Presidio Campus",
      "tags": [ ],
      "status": "wait_listed",
      "status_changed_at": "2012-06-11T02:11:15-07:00",
      "managebac_student_id": null,
      "applied_at": "2012-05-24T02:13:33-07:00",
      "enrolled_at": "2012-06-11T02:11:15-07:00",
      "inquired_at": "2012-05-21T02:08:43-07:00"
    },
    {
      "id": 2,
      "name": "Henry Epelbaum",
      "first_name": "Henry",
      "last_name": "Epelbaum",
      "other_name": "",
      "preferred_name": "",
      "birth_date": "1999-03-27",
      "gender": "female",
      "enrollment_year": 2013,
      "sibling_ids": [ ],
      "full_address": "208 California Street #880, San Francisco, 94111, United States",
      "address": "208 California Street #880",
      "address_ii": null,
      "city": "San Francisco",
      "state": null,
      "postal_code": "94111",
      "country": "United States",
      "nationality": "",
      "student_id": "",
      "passport_id": "",
      "grade": "Grade 2",
      "applicant_id": "00000005",
      "campus": "Presidio Campus",
      "tags": [ ],
      "status": "wait_listed",
      "status_changed_at": "2012-05-27T07:24:27-07:00",
      "managebac_student_id": null,
      "applied_at": "2012-05-27T07:24:27-07:00",
      "enrolled_at": null,
      "inquired_at": null
    },
    {
      ....
    },
    {
      ....
    }
  ]
}

Retrieve student by id

Retrieve student by id

GET students/:id

Return a single student specified by id with any custom fields defined.

Required parameters

Parameter Description
id The numerical id of the desired student.

Example request

GET https://<school_subdomain>.openapply.com/api/v1/students/1

Example response:

HTTP/1.1 200 OK
{
  "student": {
    "id": 1,
    "name": "Chloe Epelbaum",
    "first_name": "Chloe",
    "last_name": "Epelbaum",
    "other_name": "",
    "birth_date": "1999-01-29",
    "gender": "female",
    "enrollment_year": 2013,
    "sibling_ids": [ 112, 119 ],
    "full_address": "Jalean Sriry 1/16, Kabaru, United State",
    "address": "alean Sriry 1/16",
    "address_ii": null,
    "city": "Kabaru",
    "state": null,
    "postal_code": null,
    "country": "United States",
    "nationality": "",
    "student_id": "",
    "passport_id": "",
    "grade": "Grade 2",
    "applicant_id": "00000004",
    "campus": "Presidio Campus",
    "tags": [ ],
    "status": "wait_listed",
    "status_changed_at": "2012-05-24T02:13:33-07:00"  ,
    "managebac_student_id": null,
    "applied_at": "2012-05-24T02:13:33-07:00",
    "enrolled_at": null,
    "inquired_at": "2012-05-21T02:08:43-07:00",
    "custom_fields": {
      "preferred_name": "Big Henry",
      "place_of_birth": "Sacramento",
      "parent_guardian": [{
          "id": 4,
          "name": "Thomas Epelbaum",
          "first_name": "Thomas",
          "last_name": "Epelbaum",
          "gender": "male",
          "address": null,
          "address_ii": null,
          "city": null,
          "state": null,
          "postal_code": null,
          "email": "[email protected]",
          "parent_role": "Father",
          "managebac_parent_id": null,
          "parent_id": "3314",
          "custom_fields": {
            "title": "CTO",
            "birth_date": "1952-07-23"
          }
        },{
          "id": 5,
          "name": "Adrienne Epelbaum",
          "first_name": "Adrienne",
          "last_name": "Epelbaum",
          "gender": "female",
          "address": null,
          "address_ii": null,
          "city": null,
          "state": null,
          "postal_code": null,
          "email": "[email protected]",
          "parent_role": "Mother",
          "managebac_parent_id": null,
          "parent_id": "3315",
          "custom_fields": {
            "title": "Creative Director",
            "birth_date": "1962-07-17"
          }
        }
      ]
    }
  }
}

Update status of student

Update status of a student

PUT students/:id/status

Updates the status of an individual student​ specified by id.

Required parameters

Parameter Description
id The numerical id of the desired student.​
status The status value is pre-defined and can be matched to the statuses below
Status Code
Pending 10
Applied 20
Admitted 30
Wait-listed 40
Declined 50
Enrolled 60
Graduated 70
Withdrawn 80

Example Request

PUT https://<school_subdomain>.openapply.com/api/v1/students/1/status
PUT Data status=Applied

Response:

HTTP/1.1 200 OK
{
  "user": {
    "id": 29676,
    "name": "Chloe Epelbaum",
    "first_name": "Chloe",
    "last_name": "Epelbaum",
    "birth_date": "1997-04-01",
    "gender": "female",
    "enrollment_year": 2014,
    "status": "applied"
  }
}

If the update fails, the response will be​

HTTP/1.1 400 Bad Request
{ "errors": "Cannot update status." }

Retrieve student payment information

Retrieve student payment information

GET students/:id/payments

Returns the payment information of a student, specified by the id parameter.

Required parameters

Parameter Description
id The numerical id of the desired student.​

Example request

GET https://<school_subdomain>.openapply.com/api/v1/students/1/payments

Response:

HTTP/1.1 200 OK
{
  "payments": [{
      "invoice_status": "Paid",
      "type": "Application",
      "invoice_number": 500,
      "amount": "49.99",
      "issue_date": "2012-09-25",
      "due_date": "2012-10-25",
      "payment_method": "check",
      "payment_date": "2012-09-05"
    }, {
      "invoice_status": "Paid",
      "type": "Enrollment",
      "invoice_number": 521,
      "amount": "200.0",
      "issue_date": "2013-10-03",
      "due_date": "2013-11-02",
      "payment_method": "cash",
      "payment_date": "2013-10-01"
    }
  ]
}