• Technology | Matchbox System Overview
  • Matchbox API
  • Security

This document describes the Matchbox API for developers to integrate their data with the Matchbox review process. By the end of it, you will be able to query the Matchbox API for all the application and reader review assignments in the Matchbox database, create new applications and assignments, and modify existing ones.

The API provides access to all your data and is the same one used by the management website and the iPad application. It's split into two primary resources: Applications and Assignments. Through the API, you can add, update and get instances of either of these. The API conforms to RESTful protocols using the Tastypie framework. If you are unfamiliar with REST you can read about it on Wikipedia.

Some important details to remember:

  • All data are passed through the API in JSON format. It is necessary to include the format=json paramter to all requests.
  • The Matchbox API requires authentication. You will provide you with a login and password. Note that only Admins for your Program may access the API.
  • Only https methods are supported. Non-secure requests will be redirected to the secure url.

Among our key principles is superior customer service. If you have any questions at all about this document or your API use - please contact our Customer Success Team directly, or contact our technical team.

We have provided a number of examples below; for those we use UNIX cURL, but you can query with the client of your choosing. If you're just starting out with the API, it might be easiest to log in to the web dashboard with the browser of your choice - then authentication will be handled by cookies and you can browse through most of our examples with ease. We recommend using Chrome with the JSONView plugin to prettify the returning JSON.

Authentication

Authentication is passed to the API via cookie (if you have logged in through the login page) or by the Auth header using Basic format auth.

Application

The applicant is the center of the review process. This object represents the applicant that has applied to your school or program.

Schema

Let's first take a look at the application schema. This should tell us everything we want to know about how Application data are structured and stored in the Matchbox database.

GET /api/v2/application/schema

curl --user name:password \
 https://app.admitpad.com/api/v2/application/schema/?format=json

You should see the following:

{
    allowed_detail_http_methods: [
        "get",
        "post",
        "patch"
    ],
    allowed_list_http_methods: [
        "get",
        "post",
        "patch"
    ],
    default_format: "application/json",
    default_limit: 100,
    fields: {
        details: {
            blank: false,
            default: "No default provided.",
            help_text: "A dictionary of data. Ex: {'name': 'Daniel'}",
            nullable: false,
            readonly: false,
            type: "dict",
            unique: false
        },
        documents: {
            blank: false,
            default: "No default provided.",
            help_text: "A list of data. Ex: ['abc', 26.73, 8]",
            nullable: false,
            readonly: false,
            type: "list",
            unique: false
        },
        email: {
            blank: false,
            default: "",
            help_text: "The user's email",
            nullable: false,
            readonly: false,
            type: "string",
            unique: false
        },
        ...
    }
    filtering: {
        email: [
            "exact",
            "in"
        ],
        external_id: [
            "exact",
            "in"
        ]
    }
}

This gives the full list of parameters that the Application resource represents. Note in particular that it supports the GET, POST, and PATCH methods. As noted above, only https methods in JSON format are supported.

The default_limit is the number of Applications you will get when querying or filtering them in bulk. (We'll get into more details about filtering in the next section.) Several of the fields have been elided above, but you can see check for yourself to see what information falls into these fields.

Get a List of Applications

You can get a list of all the Applications in your program with a GET request on the Application resource URI:

GET /api/v2/application/

curl --user name:password \
 https://app.admitpad.com/api/v2/application/?format=json

Note again that when doing a GET, it's necessary to append ?format=json to the query. This will return a paginated set of Applications with a default limit of 100 per page. To change that limit to 200, add &limit=200 to the end of the query. To get the next page of queries, add &offset=1.

curl --user name:password \
 https://app.admitpad.com/api/v2/application/?format=json&limit=200&offset=1

Available Headers:

  • Accept: application/json

Available Querystring Parameters:

  • format=json : Override the accept header
  • limit={n} : Limit the number of records per page
  • offset={n} : Record offset for pagination
  • details={ALL|NONE|fieldname} : Tunable level of details returned
  • order_by={fieldname} : Sorting principle

Filtering and Sorting Applications

Applications may be filtered and sorted, if looking for an individual application or group. For example, we can sort the applications according to their Quantitative GMAT score:

curl --user name:password \
 https://app.admitpad.com/api/v2/application/?format=json\
&order_by=GmatQuantitativeScorePercent

But that gives us the increasing list, and we'd rather start with the best students and work down, so we can reverse the sort order by including a "-" in front of the parameter value:

curl --user name:password \
 https://app.admitpad.com/api/v2/application/?format=json\
&order_by=-GmatQuantitativeScorePercent

With Applications, you can filter by any program field in the details list. Take a few more examples: to get a list of all Applications for the 2012 year, you can filter by the ApplicationYear field:

curl --user name:password \
 https://app.admitpad.com/api/v2/application/?format=json\
&ApplicationYear=2012

By default, these tend to return a lot of information. Suppose we're more interested in just the list of names than in the full breadth of details for each application. In such cases, it's helpful to append "&details=NONE" to limit what's returned to top-level program fields.

Get Individual Application Details

You can also query for an applicant directly with their ID. The Matchbox data infrastructure automatically gives new Applications an ID, which you can find in the list view.

To get an Applicant by ID, simply append it to the standard Application URI:

GET /api/v2/application/{id}/

curl --user name:password \
 https://app.admitpad.com/api/v2/application/{id}/?format=json

Available Headers:

  • Accept: application/json

Available Querystring Parameters:

  • format=json : Override the accept header
  • details={ALL|NONE|fieldname} : Tunable level of details returned

Create a new Application

Use a POST method to add a new application to the database.

First get the applicant's information into serialized into JSON format that matches the field parameters listed in the Schema. For example:

POST /api/v2/application/

curl -H "Content-Type: application/json" \
 -X POST \
 --user name:password \
 --data {serialized_json_string} \
 https://app.admitpad.com/api/v2/application/

Here you would replace {serialized_json_string} with a post body similar to the example given below. It is necessary to include the program_id in the serialized json string so that the API knows where to put the new application.

Example Post body:

{
    "program_id": "abcdefg" ,
    "first_name": "Andy",
    "last_name": "Exampleson",
    "details": {
        "my_custom_school_field": "1 year",
        "my_custom_work_field": "Vice President"
    }
}

Your details will be different from the example above. Contact us if you have any questions.

Available Headers:

  • Accept: application/json
  • Content-Type: application/json

Available Querystring Parameters:

  • format=json : Override the accept header

Update Application Details

It's quite common to need to revise application details after it's been created. An applicant may fill in missing details, or provide new documents that need to be linked to their application. To do this, use POST to send the changes:

POST /api/v2/application/{id}/

curl -H "Content-Type: application/json" \
 -H "X-HTTP-Method-Override: PATCH" \
 -X POST \
 --user name:password \
 --data '{"program_id": "11235813", "last_name": "Exampleson"}' \
 https://app.admitpad.com/api/v2/application/{id}/

But note especially the addition X-HTTP-Method-Override header to PATCH! This is a required header when updating application details.

It is not necessary to resend unchanged data - since we're effectively using a PATCH request, you only need to send program field assignments that have changed.

Example Post body:

{
    "last_name": "smith",
    "details": {
        "my_custom_school_field": "1 year"
    }
}

Available Headers:

  • X-HTTP-Method-Override: PATCH (required)
  • Accept: application/json
  • Content-Type: application/json

Assignment

The Assignment record represents an instance of a step in the review process, and contains information about the scores selected, evidence collected, and other information.

Schema

As with Applications, we can take a look at the schema of the Assignment resource to see how they are structured:

GET /api/v2/assignment/

curl --user name:password \
 https://app.admitpad.com/api/v2/assignment/schema/?format=json

Get a List of Assignments

For bulk querying Assignments, we can do a GET request to the resource URI:

GET /api/v2/assignment/

curl --user name:password \
 https://app.admitpad.com/api/v2/assignment/?format=json

This will return a paginated list of all the Assignments in the program, sorted by due date.

Available Headers:

  • Accept: application/json

Available Querystring Parameters:

  • format=json : Override the accept header
  • limit={n} : Limit the number of
  • offset={n} : Record offset for pagination
  • details={ALL|NONE} : Tunable level of details returned
  • my_active=1 : Only return the active personal assignments for the logged in user
  • order_by={date_due|start_date|date_completed} : Sorting principle

Filtering Assignments

A full list of all the assignments might very well be more information than we really need. So to narrow down the list, we can filter what's returned by the API.

Two potentially useful examples in one query: let's only get the completed assignments for a particular user:

curl --user name:password \
 https://app.admitpad.com/api/v2/assignment/?format=json\
&completed=1&assignee={id}

Get Individual Assignment Details

To get an assignment in isolation, append the Matchbox-generated Assignment ID to the general query.

GET /api/v2/assignment/{id}/

curl --user name:password \
 https://app.admitpad.com/api/v2/assignment/{id}?format=json&details=ALL

Available Headers:

  • Accept: application/json

Available Querystring Parameters:

  • format=json : Override the accept header
  • details={ALL|NONE|fieldname} : Tunable level of details returned

Create a new Assignment

Similar to creating new Applications, we use POST to create new Assignments. Send the details of your assignment in encoded JSON in the Post body.

POST /api/v2/assignment/

curl -H "Content-Type: application/json" \
 -X POST \
 --user name:password \
 --data {serialized_json_string} \
 https://app.admitpad.com/api/v2/assignment/

After making it, you can double-check the assignment list to make sure it appears:

curl --user name:password /
 https://app.admitpad.com/api/v2/assignment/?format=json&order_by=date_due

Example Post body:

{
    "application_id": "abcdefg",
    "owner_id": "abcdefg",
    "activity_id": "abcdefg",
    "due_date": "2012-01-01T00:00:00Z"
}

It might be helpful to break a few of these down a little together:

  • application_id : The ID given by Matchbox to the application this assignment is intended to review.
  • owner_id : The ID of the program member responsible for this application.
  • activity_id : The ID of the reader's role (what kind of assignment is it).

You can check with our Customer Success team for the list of Activity IDs and the eligible program member IDs to be owners.

Available Headers:

  • Accept: application/json
  • Content-Type: application/json