Getting Started with EDU API

Handshake’s EDU API is a scalable, secure, and developer-friendly solution for data management and automation. With features like read-only data retrieval, institution-scoped access, versioning, and delta fetching, the API ensures efficiency and reliability.

Topics:

• How to setup your account
• Supported Entities and Endpoints
• Query Parameters
• Requests
• Responses
  • Successful Response
  • Error Response

How to setup your account

1. Open the Developer Portal: https://edu-api.joinhandshake.com:444.
2. Select Sign in. The sign in form will appear:

3. Use the Username and Password provided by the Handshake Support team via 1Password. Select Sign in. You will be directed to the following API Catalog page:

   

4. Go to Applications in the tabs section. Select Register an Application. 

5. Fill out the Register an Application form. Only the Application Name field is required. Please keep the Application Status radio button Enabled.

6. Select Register. You will be redirected to the Applications screen:

   

7. Now go back to the API Catalog tab. Select EDU API v1.

8. On the EDU API v1 page select Subscribe.

9. The following pop-up will appear, and your application will be selected in the dropdown. Add a message for the request, which will be sent to the Handshake Support team.

10. Click on Subscribe. The following message will appear:

    

11. Your request has been sent to the Handshake Support team. The team will review your request in 48 hours or less. 
12. You have access to the status of your request in the Subscriptions tab. After your request is approved, your API status will be set to Enabled. 

13. Select EDU API v1. Your API key is generated on the following screen. Anytime there’s an API request, you will need to use this key. If you regenerate the API key, please reach out to the Handshake Technical Support Team to have the new key enabled. The key must be enabled by Support before it can be used.

You're all set! You can now start using the API. Read below for details on supported endpoints, example requests, and responses.

Supported Entities and Endpoints

*Initial graduate outcomes reporting prioritizes MBA outcomes for V1. Our team is working on broadening outcome pulls to be able to include all first destination survey outcomes.

For detailed descriptions of each entity and their fields, please refer to this resource.

Query Parameters

API calls support the following query parameters, that will help you paginate and sort responses based on your specific data needs:

Requests

The base URL of the API service follows the format: 

<host>/edu/<version>/<entity>

All requests should have x-api-key as a Header entry with the value of the API key. You can get the API key in the Developer Portal, from the Subscriptions section.

Example: To fetch two records per page for the applications entity, using a given cursor, filtering for records updated after January 1, 2024, and sorting by job_id in descending order, the API request would be:

curl --location 'https://edu-api.joinhandshake.com/v1/applications?page_size=2&updated_since=2024-01-01T00%3A00%3A00Z&sorting_column=job_id&sorting_order=desc' \

--header 'x-api-key: <REDACTED_API_KEY>'

Responses

The API follows standard HTTP status codes as per RFC 9110, and all responses are returned in JSON format.

Successful Response

Upon a successful request, the API returns a JSON object containing the queried entities and metadata for pagination with the following format:

• data - an array containing the queried entities, where each record adheres to the structure described in the corresponding entity section from this resource.
• meta - contains metadata related to the results:
  • next_cursor - cursor that can be used to navigate forwards in the dataset.
  • prev_cursor - cursor that can be used to navigate backward in the dataset.

Example: For the request above, an example response would be:

{

    "data": [

        {

            "id": 18797,

            "job_id": 11933,

            "student_id": 92579,

            "employer_id": 2423,

            "status": "pending",

            "applicable_type": "Job",

            "withdrawn": true,

            "created_at": "2025-03-19T10:14:44.90493-05:00",

            "updated_at": "2025-03-19T10:14:51.908777-05:00"

        },

        {

            "id": 18793,

            "job_id": 11933,

            "student_id": 92579,

            "employer_id": 2423,

            "status": "pending",

            "applicable_type": "Job",

            "withdrawn": true,

            "created_at": "2025-03-17T14:29:29.617135-05:00",

            "updated_at": "2025-03-17T14:29:34.236529-05:00"

        }

    ],

    "meta": {

      "next_cursor": "eyJpZCIgOiAxODc5MywgInNvcnRpbmdfY29sdW1uX3ZhbHVlIiA6ICIyMDI1LTAzLTE3VDE5OjI5OjM0LjIzNjUyOSIsICJwYWdpbmF0aW9uX29yZGVyIiA6ICJmb3J3YXJkIn0=",

        "prev_cursor": null

    }

}

Error Response

In case of a failure, the API response has the following key-value format:

• errors - an array of error objects. It supports handling multiple errors in a single response. Each error will adhere to the following structure:
  • status - The HTTP status code related to the error, represented as a string (e.g., "400", "404"). It matches the HTTP response status code but is included in the body for clarity.
  • code - A custom, application-specific error code that provides a unique identifier for the type of error
  • detail - A detailed explanation of the error, providing specific context

Example:

{

    "errors": [

        {

            "status": 400,

            "code": "INVALID_PARAMETER_PAGE_CURSOR",

            "detail": "The 'page_cursor' parameter is not valid."

        }

    ]

}