Setting Sharing Rules via API

Typically, people want to configure sharing rules via the Edlink Dashboard. Occasionally, however, you might still have a use case that requires you to set sharing rules in bulk, or via some automated process. While we're still working on building out documentation around our "Meta API" (our API for interacting with Edlink as a platform, rather than data for an individual school), we're still happy to help you get something up and running.

If this is a use case that you're interested in, please contact your Edlink client success manager and they will point you in the right direction.

Here are some use cases where setting sharing rules programmatically may help you:

• You are looking for tighter integration with your own internal tools for managing school districts.
• You want to grant access to users / classes based on some action taking place within your platform (e.g., a user signing up with a particular email address or upgrading their plan).
• You want to automatically revoke access to your platform after a certain date.

Occasionally, developers will have use cases that require them to programmatically create, update, or delete rules and conditions in Edlink. In this guide, we'll break down a few of the situations in which this might be valuable, and some best practices for doing so.

Why you might want to programmatically modify rules

1. Your application may require frequent or granular modifications to sharing rules that are difficult or time consuming for a person to undertake.
2. You may want teachers to opt-in certain courses
3. Some applications have use cases that don't naturally fit Edlink's pricing model. As a result,

While we do not have any formally documented APIs for creating, modifying, and deleting rules, you are able to use the same API calls made by the Edlink Dashboard to modify your integrations as needed. Although these endpoints are written down in this guide, we consider them to be in "beta" and subject to change, not in accordance with our general deprecation policy.

In general, when possible it is advised to create empty rules & conditions on new integrations manually via the Edlink Dashboard. That way, you can simply call the PUT request below to update and existing condition, which may save you a good bit of engineering work.

Request authorization

Although it is possible to use your personal access token, we recommend that you authorize requests using a Service Account access token. It is critical that this access token is stored safely as it has all of the permissions that you do to modify data in Edlink.

Send this service account access token as an authorization header in each of the following API requests to properly authenticate yourself.

Authorization: 'Bearer SERVICE_ACCOUNT_ACCESS_TOKEN'

Create a new rule

POST https://ed.link/api/v1/teams/:team_id/integrations/:integration_id/rules

{
    "state": "draft",
    "target": "classes",
    "conditions": [],
    "end_date": null,
    "start_date": null,
    "soft_cap": null,
    "hard_cap": null,
    "name": null,
    "product_ids": []
}

• Your team ID can be found on your team settings page.
• The possible options for state are draft and active.
• The possible options for target are classes, people, and schools.
• The rule target cannot be updated after the rule is created.
• You may optionally send conditions in the conditions array while creating a rule. The conditions should conform to the schema in the below requests.
• The start_date, end_date, soft_cap, hard_cap, name, and product_ids columns are all optional.

Update a rule

PUT https://ed.link/api/v1/teams/:team_id/integrations/:integration_id/rules/:rule_id

{
    "state": "active",
    "conditions": [
        {
            "id": "<UUID>",
            "property": "class_id",
            "target": "class",
            "values": ["<UUID>"],
            "operator": "IN"
        }
    ]
    "end_date": null,
    "start_date": null,
    "soft_cap": null,
    "hard_cap": null,
    "name": null,
    "product_ids": []
}

• When using this endpoint to update conditions, you should include the condition id property in the payload (as seen above).
• When using this endpoint to create a new condition, this id can be ommitted.
• There are many valid targets, properties, and operators that you can use in your conditions. We suggest that you try creating conditions on the Edlink Dashboard to understand which one(s) will work best for your use case.

Delete a rule

DELETE https://ed.link/api/v1/teams/:team_id/integrations/:integration_id/rules/:rule_id

• There is no payload and no response to this API request.