AI-ready version:

Impact Summary Totals

Description

Retrieve the weighted totals for all Impact Type Categories associated with a specific company or application. The totals represent the total count multiplied by the impact multiplier. Optionally, the results can be filtered to display impact totals for a specific user.

Endpoint

GET https://impact.dots.eco/api/v1/impact/summary-totals?company={company_id}&app_token={app_token}&user={remote_user_id}

Refer to Headers and Authorization for details about token setup and required headers.

Parameters

Name	Required	Type	Description
`company`	Yes^*	`integer`	The ID of the company for which to retrieve weighted impact totals.
`app_token`	Yes^*	`string`	The app token, available in the app dashboard. Multiple app tokens can be separated by commas.
`user`	No	`string`	The remote user ID for filtering impact totals by a specific user.

^*Note: At least one of company or app_token parameters must be provided. If both are supplied, results are filtered by the app_token.

Example Requests

Minimal Request Example

curl --location --request GET 'https://impact.dots.eco/api/v1/impact/summary-totals?company=33&app_token=65-b156f001' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN'

Filtering by Multiple App Tokens and User

curl --location --request GET 'https://impact.dots.eco/api/v1/impact/summary-totals?company=33&app_token=65-b156f001,63-f1758578&user=testuser' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN'

Responses

Success Response Example (Single Category)

{
  "19": {
    "impact_type_category_name": "Carbon offset",
    "impact_unit": "Kg of carbon emissions",
    "total": "12",
    "unit_text": "kg",
    "single_unit_text": "kg",
    "unit_html": "<p>kg</p>",
    "action_in_past_tense": "offsetted",
    "action_title": "removing",
    "icon": "https://impact.dots.eco/sites/default/files/2023-10/jangomo%20love%20the%20oceans.png"
  }
}

Success Response Example (Multiple Categories)

{
  "19": {
    "impact_type_category_name": "Carbon offset",
    "impact_unit": "Kg of carbon emissions",
    "total": "12",
    "unit_text": "kg",
    "single_unit_text": "kg",
    "unit_html": "<p>kg</p>",
    "action_in_past_tense": "offsetted",
    "action_title": "removing",
    "icon": "https://impact.dots.eco/sites/default/files/2023-10/jangomo%20love%20the%20oceans.png"
  },
  "20": {
    "impact_type_category_name": "Save a Sea Turtle",
    "impact_unit": "sea turtle hatchling",
    "total": "1",
    "unit_text": "turtles",
    "unit_html": "<p>turtles</p>",
    "action_in_past_tense": "saved",
    "action_title": "saving",
    "icon": "https://impact.dots.eco/sites/default/files/2023-10/jangomo%20love%20the%20oceans.png"
  }
}

Response Fields

Field	Type	Description
`[integer]`	`integer`	The unique ID of the Impact Type Category.
`impact_type_category_name`	`string`	The name of the Impact Type Category (e.g., "Carbon offset").
`impact_unit`	`string`	The unit of measurement for the impact (e.g., "Kg of carbon emissions").
`total`	`string`	The total weighted impact for the category (total count multiplied by the impact multiplier).
`unit_text`	`string`	A plain-text representation of the impact unit (e.g., "kg").
`single_unit_text`	`string`	A plain-text representation of the impact unit (e.g., "kg").
`unit_html`	`string`	An HTML-formatted representation of the impact unit (e.g., "`<p>kg</p>`").
`action_in_past_tense`	`string`	The description of the impact action in past tense (e.g., "offsetted").
`action_title`	`string`	The description of the impact action (e.g., "removing").
`icon`	`string`	A URL pointing to the icon representing the Impact Type Category.

Errors

Possible Error Messages

Message	Cause
`"Access denied. You are not a manager of specified company..."`	You are not authorized to manage the company or application related to the request.
`"You must provide a value for 'app_token' and/or 'company'..."`	Missing `app_token` and `company` parameters in the request.
`"No results found for specified criteria."`	No data matches the query parameters (e.g., incorrect `app_token` or company ID).

HTTP Status Codes

Code	Description
200	Request succeeded, and impact totals are included in the response.
403	Forbidden. Occurs if the token or user lacks necessary permissions for the request.
422	Unprocessable Entity due to missing or incorrect input parameters.
404	No impact totals found that match the specified query parameters.

Notes

Required Parameters: Ensure at least one of company or app_token is included in the query string.
Multiple App Tokens: Use comma-separated app_token values to query across multiple applications simultaneously.
User-Specific Data: Include the user parameter to filter results to view impact totals for a specific user.
Refer to Headers and Authorization for more details on authentication token usage.