Onboardings are used to connect districts or universities to your application. This data type allows you to invite specific districts by ID or to create instances of your onboarding link for initiating the onboarding flow from your application, such as from an admin dashboard. Onboardings also enable programmatically correlating which integration belongs to which school once the school completes the connection process.

Please note, we do not currently notify you of the completion of an onboarding. You will need to poll the API to check the status of the onboarding. We may support push notifications via our upcoming Data Feeds feature (Q3 2024).

Please note, using the automatic_approval property will skip the requested state and set the integration to active once the onboarding is completed. This may have an impact on your usage of Edlink, and therefore, your bill. The requested state is intended to allow you to review the integration and set sharing rules before activating it.

In our example workflow, we will assume that the district IT admin starts on a settings page within your application.

1. The IT administrator clicks a button to start the onboarding process (e.g. a button like Connect your SIS).
2. Your application sends a POST request to the Edlink API to create a new onboarding.
3. The Edlink API responds with the details of the new onboarding, including a unique onboarding_id.
4. Your application opens a new tab for the IT admin that points to the onboarding ID (i.e. https://ed.link/onboard/{onboarding_id}).
5. Your application begins polling the Edlink API to check the status of the onboarding.
6. The IT admin completes the onboarding process.
7. The Edlink API updates the onboarding state to completed and sets the newly created integration ID.
8. Your application (via polling) receives the updated onboarding state and can now associate the Edlink integration ID with the district.
9. You may then choose to load additional data about the district from the Edlink API using the integration ID or access token.

List All Onboardings For Your Team

GET https://ed.link/api/v1/teams/:team\_id/onboardings

Retrieve a list of all onboardings for a specific team. You can filter onboardings by the following properties: application_id, integration_id, state, provider_id, and user_id.

Sample Request

axios.get('https://ed.link/api/v1/teams/{team_id}/onboardings', {
    headers: {
        authorization: `Bearer ${user_access_token}`
    }
});

Sample Response

{
    "$data": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "state": "completed",
            "redirect_uri": "https://example.com/redirect",
            "expiration_date": "2024-12-31T23:59:59.999Z",
            "application_id": "00000000-0000-0000-0000-000000000000",
            "provider_id": "00000000-0000-0000-0000-000000000000",
            "user_id": "00000000-0000-0000-0000-000000000000",
            "team_id": "00000000-0000-0000-0000-000000000000",
            "integration_id": "00000000-0000-0000-0000-000000000000"
        },
        { ... }
    ]
}

Retrieve a Specific Onboarding

GET https://ed.link/api/v1/teams/:team\_id/onboardings/:onboarding\_id

Retrieve the details of a specific onboarding.

Sample Request

axios.get('https://ed.link/api/v1/teams/{team_id}/onboardings/{onboarding_id}', {
    headers: {
        authorization: `Bearer ${user_access_token}`
    }
});

Sample Response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "state": "completed",
    "redirect_uri": "https://example.com/redirect",
    "expiration_date": "2024-12-31T23:59:59.999Z",
    "application_id": "00000000-0000-0000-0000-000000000000",
    "provider_id": "00000000-0000-0000-0000-000000000000",
    "user_id": "00000000-0000-0000-0000-000000000000",
    "team_id": "00000000-0000-0000-0000-000000000000",
    "integration_id": "00000000-0000-0000-0000-000000000000"
}

Create a New Onboarding

POST https://ed.link/api/v1/teams/:team\_id/onboardings

Create a new onboarding for a specific team.

Sample Request

axios.post(
    'https://ed.link/api/v1/teams/{team_id}/onboardings',
    {
        application_id: '00000000-0000-0000-0000-000000000000',
        provider_id: '00000000-0000-0000-0000-000000000000',
        team_id: '00000000-0000-0000-0000-000000000000',
        expiration_date: '2024-12-31T23:59:59.999Z',
        redirect_uri: 'https://example.com/redirect'
    },
    {
        headers: {
            authorization: `Bearer ${user_access_token}`
        }
    }
);

Sample Response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "state": "created",
    "redirect_uri": "https://example.com/redirect",
    "expiration_date": "2024-12-31T23:59:59.999Z",
    "application_id": "00000000-0000-0000-0000-000000000000",
    "provider_id": "00000000-0000-0000-0000-000000000000",
    "user_id": "00000000-0000-0000-0000-000000000000",
    "team_id": "00000000-0000-0000-0000-000000000000",
    "integration_id": "00000000-0000-0000-0000-000000000000"
}

Delete an Onboarding

DELETE https://ed.link/api/v1/teams/:team\_id/onboardings/:onboarding\_id

Delete a specific onboarding. Note that you cannot delete a completed onboarding.

Sample Request

axios.delete('https://ed.link/api/v1/teams/{team_id}/onboardings/{onboarding_id}', {
    headers: {
        authorization: `Bearer ${user_access_token}`
    }
});