Changing the Notified Users for an Organization

To change subscribed users at the Org-Level, we'll need to have the appropriate permissions and send a PUT request to https://app.fossa.com/api/organizations/{{orgID}} with RAW JSON in the following shape:

{
    "notification_default_enabled": true,
    "notification_default_email_scan_users":
    [
        userID,
        userID,
        userID
    ]
}

If unsure about your or a colleague's userID, please jump to Pulling the List of UserIDs.

An example cURL request would look like the following:

curl --location --request PUT 'https://app.fossa.com/api/organizations/{orgID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{"notification_default_enabled":true,"notification_default_email_scan_users":[1111,2222,3333]}'

Changing the Notified Users for a Project

Changing the subscribed users at the project level is similar, but utilizes a different endpoint. To do this, we'll need to send a PUT request to https://app.fossa.com/api/projects/{{URL_ENCODED_LOCATOR}}- Please note this project locator should not include the revision.

The PUT request should include RAW JSON with the following shape:

{
    "notifications": [
        {
            "locator": "{{project_locator}}",
            "channel": "SCAN",
            "service": "EMAIL",
            "subscribed_users": [
                userID,
                userID
            ]
        }
    ]
}

📣 Tips + Notes:

• {{project_locator}} - Project's locator, without revision
• "channel": - This can be "SCAN" or "BUILD" depending on the notification type. If using both, please duplicate your response and add a separate entry for each.

An Example Request might look like the following:

curl --location --request PUT 'https://app.fossa.com/api/projects/{{URL_ENCODED_LOCATOR}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "notifications":
    [
        {
            "locator": "{{project_locator}}",
            "channel": "SCAN",
            "service": "EMAIL",
            "subscribed_users":
            [
                1111,
                2222
            ]
        },
        {
            "locator": "{{project_locator}}",
            "channel": "BUILD",
            "service": "EMAIL",
            "subscribed_users":
            [
                1111
            ]
        }
    ]
}'

📘

If using both BUILD and SCAN types, there will need to be two, separate entries. One for each channel.

Pulling the list of UserIDs

A user must be part of your Organization to be added to the notification list, and the API response is scoped to your permissions. For the most results, this data should be retrieved by an Org Admin.

A list of users and their IDs can be pulled from https://app.fossa.com/api/users, and will have the following shape:

[
    {
        "id": userID,
        "username": "{{userEmail}}",
        "email": "{{userEmail}}",
        "email_verified": true,
        "demo": false,
        "super": false,
        "joined": "YYYY-MM-DDTHH:MM:SS.000Z",
        "last_visit": "YYYY-MM-DDTHH:MM:SS.000Z",
        "terms_agreed": null,
        "full_name": "Full Name",
        "phone": null,
        "role": null,
        "organizationId": orgID,
        "sso_only": false,
        "enabled": true,
        "has_set_password": false,
        "has_seen_help_panel": true,
        "install_admin": false,
        "createdAt": "YYYY-MM-DDTHH:MM:SS.000Z",
        "updatedAt": "YYYY-MM-DDTHH:MM:SS.000Z",
        "github": null,
        "bitbucketCloud": null,
        "userRole": null,
        "teamUsers":
        [],
        "tokens":[],
        "organization":
        {
            "id": orgID,
            "title": "docs.fossa.com",
            "access_level": "free"
        }
    },

Since the /users endpoint has a ton of extra information, you can use JQ to trim the response. Here's an example:

curl --location 'https://app.fossa.com/api/users' \
--header 'Authorization: Bearer TOKEN' |  jq '.[] | "ID: \(.id) Email: \(.email)"'
## Which would produce the following result:
"ID: {{userID}} Email: {{userEmail}}"

We'll only need the userID, but seeing the email and ID side-by-side can be helpful.