Sustainability

Endpoints to manage Sustainability Programs

Dimension

Data model for a dimension, which allows for the collection of multiple values per metric. Dimensions could represent various categories or groupings, such as:

• Entity locations

• Market regions

• Business units

• Demographics, such as gender or race

Properties

Name	Type	Description	Restrictions
active	boolean	Indicates whether the dimension is available for use in new metrics
id	string(uuid)	The unique UUID identifier of the dimension	read-only
name	string¦null	The name of the dimension, representing a specific category or grouping.
values	[DimensionValue]¦null	A list of values associated with this dimension, requiring at least one and limited to a maximum of 1500. This list is populated when retrieving an individual dimension and is null when listing dimensions.	Minimum items: 1, Maximum items: 1500

Example

{
  "active": true,
  "name": "Facility",
  "values": [
    {
      "id": "Ames, IA",
      "name": "Ames, Iowa"
    },
    {
      "id": "Portland, OR",
      "name": "Portland, Oregon"
    }
  ]
}

DimensionsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of Dimension objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[Dimension]	Data model for a dimension, which allows for the collection of multiple values per metric. Dimensions could represent various categories or groupings, such as: - Entity locations - Market regions - Business units - Demographics, such as gender or race	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "active": true,
      "name": "Facility",
      "values": [
        {
          "id": "Ames, IA",
          "name": "Ames, Iowa"
        },
        {
          "id": "Portland, OR",
          "name": "Portland, Oregon"
        }
      ]
    }
  ]
}

DimensionValue

Data model for a dimension value

Properties

Name	Type	Description	Restrictions
active	boolean	Indicates whether the dimension value is available for use in new metrics.
id	string	A user-entered, unique identifier for the dimension value, up to 20 characters.	Maximum length: 20
name	string¦null	The name of the dimension value, up to 300 characters. If not provided, defaults to the value of ‘id’.	Maximum length: 300

Example

{
  "active": true,
  "id": "Ames, IA",
  "name": "Ames, Iowa"
}

FrameworkReference

An association with a framework or standard.

Properties

Name	Type	Description	Restrictions
framework	string	The framework or standard to which the reference belongs (e.g., GRI, SASB, TCFD).	required
publishedVersion	string	The published version of the framework or standard. If not specified during write operations, it will default to the latest published version.
referenceName	string	The identifier or label for the specific framework reference.	required

Example

{
  "framework": "GRI",
  "publishedVersion": "2016.2",
  "referenceName": "2-6-b-iii"
}

Metric

Represents a metric, which are used to track and collect material data to your company.

Properties

Name	Type	Description	Restrictions
allowedDimensions	[string]	A list of dimension ids that may be used when creating values for this metric.	Maximum items: 7
code	integer	An optional user-specified metric code as an integer greater than 0, unique to each metric. If not provided, the system assigns the next available integer.	Minimum: 1
dataType	string	Used to specify the type of data for a metric.
description	string	An optional description of the metric, explaining its purpose and main aspects, up to 32767 characters.	Maximum length: 32767
frameworkReferences	[FrameworkReference]	A list of framework/standard references or other related content, up to 20 references.	Maximum items: 20
id	string(uuid)	The unique UUID identifier of the metric.
index	integer	The index in the outline. If unset, the metric will be ordered last.
name	string	The name of the metric, up to 300 characters.	Maximum length: 300
requireNotes	boolean	Indicates whether notes are required for this metric.
requireSupportingAttachments	boolean	Indicates whether supporting attachments are required for this metric.
strCode	string	The system-generated string representation of the metric code, read-only.	read-only
tags	[Tag]	A collection of tags associated with the metric. A metric can have up to 20 tags.	Maximum items: 20
topic	string(uuid)	The unique UUID identifier of the parent topic.
unit	string	The unit of measurement for the metric, up to 300 characters.	Maximum length: 300

Enumerated Values

Property	Value
dataType	text
dataType	number
dataType	date
dataType	currency
dataType	percent

Example

{
  "code": 12,
  "dataType": "text",
  "description": "Covers all direct greenhouse gas emissions from sources owned or controlled by the reporting entity.",
  "id": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac",
  "index": 0,
  "name": "Scope 1 Consolidated GHG Emissions",
  "requireNotes": false,
  "requireSupportingAttachments": false,
  "topic": "cc507098-c403-4b8b-98b4-31a6c5a639f4",
  "unit": "Metric Ton"
}

MetricAttachment

Represents an attachment associated with a metric or metric value

Properties

Name	Type	Description	Restrictions
name	string	Name of the attachment	required
type	string	The type of attachment	required

Enumerated Values

Property	Value
type	url
type	file
type	externalFile

Example

{
  "name": "download.pdf",
  "type": "file"
}

MetricsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of Metric objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[Metric]	Represents a metric, which are used to track and collect material data to your company.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "code": 12,
      "dataType": "text",
      "description": "Covers all direct greenhouse gas emissions from sources owned or controlled by the reporting entity.",
      "id": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac",
      "index": 0,
      "name": "Scope 1 Consolidated GHG Emissions",
      "requireNotes": false,
      "requireSupportingAttachments": false,
      "topic": "cc507098-c403-4b8b-98b4-31a6c5a639f4",
      "unit": "Metric Ton"
    }
  ]
}

MetricValue

Represents a metric value, which is a data record belonging to a specific metric.

Properties

Name	Type	Description	Restrictions
coordinates	object	A mapping of dimension ids to dimension value ids for the value. The maximum number of key-value dimension pairs is limited to 3.
coordinates.additionalProperties	string
dataSource	object	Represents the source of the value, which can be a Workiva spreadsheet or table cell or a Workiva document text region. Only one of the connection types can be specified.
dataSource.connectionType	string	The type of connection to the value.
dataSource.spreadsheetCellConnection	PlatformSpreadsheetCellConnection	Represents a connection to a value from a Workiva spreadsheet
dataSource.tableCellConnection	TableCellConnection	Represents a connection to a value from a Workiva table cell
dataSource.textRegionConnection	TextRegionConnection	Represents a connection to a value from a Workiva document text region
fieldsToClear	[string]	List of fields to clear.	write-only
id	string(uuid)	The unique UUID identifier of the metric value.
notes	string¦null	Optional notes for the value, with a maximum length of 32,767 characters.	Maximum length: 32767
reportingPeriod	object	Defines the reporting period for a value.
reportingPeriod.end	integer	The end month of the collection period, represented as an integer (e.g., Q1 = 3, Q2 = 6, Q3 = 9, Q4 = 12). Must be greater than or equal to start.	required, Maximum: 12, Minimum: 1
reportingPeriod.start	integer	The start month of the collection period, represented as an integer (e.g., Q1 = 1, Q2 = 4, Q3 = 7, Q4 = 10).	required, Maximum: 12, Minimum: 1
reportingPeriod.year	integer	The 4-digit year representing the report period for a value.	required, Maximum: 9999, Minimum: 1000
status	string	Represents the current status of a metric value. The status can only be set to complete if it’s currently notStarted, and it can be reset to notStarted if it’s complete.
supportingAttachments	[MetricAttachment]¦null	A list of attachments associated with the metric value.	read-only, Maximum items: 50
task	string	The id of the task that corresponds to the metric value, which can be used to fetch the task/modify details via the tasking api
value	string	The string representation of the metric value. The value can be up to 32,767 characters.	Maximum length: 32767

Enumerated Values

Property	Value
connectionType	spreadsheetCell
connectionType	tableCell
connectionType	textRegion
status	notStarted
status	notSent
status	inProgress
status	sentForApproval
status	returned
status	complete
status	error

Example

{
  "coordinates": {
    "b38353ce-32bc-4ea7-852a-bf5e12b72d95": "Ames, IA"
  },
  "dataSource": {
    "connectionType": "spreadsheetCell",
    "spreadsheetCellConnection": {
      "cell": "A1",
      "sheet": "576696e0f7a143b4a0bc7c20a34480ab",
      "spreadsheet": "7a5e271acf1d49d480a6fbabc394a0fa"
    }
  },
  "fieldsToClear": [
    "notes"
  ],
  "id": "bf9aa2c3-f278-4c77-8acb-97584e843dcd",
  "notes": "metric value notes",
  "reportingPeriod": {
    "end": 12,
    "start": 1,
    "year": 2024
  },
  "status": "complete",
  "supportingAttachments": [
    {
      "name": "Workiva Document",
      "type": "file"
    }
  ],
  "task": "VGFMDU1MmJiOGEwZDVjZWYzNDlVhZDWU5Y2jYzY3zax5iMg",
  "value": "512.8768743"
}

MetricValueIdentifier

Represents a metric value identifier

Properties

Name	Type	Description	Restrictions
data	[object]
data.coordinates	object	A mapping of dimension ids to dimension value ids for the value. The maximum number of key-value dimension pairs is limited to 3.
data.coordinates.additionalProperties	string
data.reportingPeriod	object	Defines the reporting period for a value.
data.reportingPeriod.end	integer	The end month of the collection period, represented as an integer (e.g., Q1 = 3, Q2 = 6, Q3 = 9, Q4 = 12). Must be greater than or equal to start.	required, Maximum: 12, Minimum: 1
data.reportingPeriod.start	integer	The start month of the collection period, represented as an integer (e.g., Q1 = 1, Q2 = 4, Q3 = 7, Q4 = 10).	required, Maximum: 12, Minimum: 1
data.reportingPeriod.year	integer	The 4-digit year representing the report period for a value.	required, Maximum: 9999, Minimum: 1000

Example

{
  "data": [
    {
      "coordinates": {
        "b38353ce-32bc-4ea7-852a-bf5e12b72d95": "Ames, IA"
      },
      "reportingPeriod": {
        "end": 12,
        "start": 1,
        "year": 2024
      }
    }
  ]
}

MetricValuesListResult

Returns a JSON object with data and @nextLink properties. data contains a list of MetricValue objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[MetricValue]	Represents a metric value, which is a data record belonging to a specific metric.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "coordinates": {
        "b38353ce-32bc-4ea7-852a-bf5e12b72d95": "Ames, IA"
      },
      "dataSource": {
        "connectionType": "spreadsheetCell",
        "spreadsheetCellConnection": {
          "cell": "A1",
          "sheet": "576696e0f7a143b4a0bc7c20a34480ab",
          "spreadsheet": "7a5e271acf1d49d480a6fbabc394a0fa"
        }
      },
      "fieldsToClear": [
        "notes"
      ],
      "id": "bf9aa2c3-f278-4c77-8acb-97584e843dcd",
      "notes": "metric value notes",
      "reportingPeriod": {
        "end": 12,
        "start": 1,
        "year": 2024
      },
      "status": "complete",
      "supportingAttachments": [
        {
          "name": "Workiva Document",
          "type": "file"
        }
      ],
      "task": "VGFMDU1MmJiOGEwZDVjZWYzNDlVhZDWU5Y2jYzY3zax5iMg",
      "value": "512.8768743"
    }
  ]
}

MetricValueUpsertion

Properties

Name	Type	Description	Restrictions
data	[MetricValue]	An array of metric values, each representing a metric value data record belonging to a specific metric.

Example

{
  "data": [
    {
      "coordinates": {
        "b38353ce-32bc-4ea7-852a-bf5e12b72d95": "Ames, IA"
      },
      "dataSource": {
        "connectionType": "spreadsheetCell",
        "spreadsheetCellConnection": {
          "cell": "A1",
          "sheet": "576696e0f7a143b4a0bc7c20a34480ab",
          "spreadsheet": "7a5e271acf1d49d480a6fbabc394a0fa"
        }
      },
      "fieldsToClear": [
        "notes"
      ],
      "id": "bf9aa2c3-f278-4c77-8acb-97584e843dcd",
      "notes": "metric value notes",
      "reportingPeriod": {
        "end": 12,
        "start": 1,
        "year": 2024
      },
      "status": "complete",
      "supportingAttachments": [
        {
          "name": "Workiva Document",
          "type": "file"
        }
      ],
      "task": "VGFMDU1MmJiOGEwZDVjZWYzNDlVhZDWU5Y2jYzY3zax5iMg",
      "value": "512.8768743"
    }
  ]
}

PlatformSpreadsheetCellConnection

Represents a connection to a value from a Workiva spreadsheet

Properties

Name	Type	Description	Restrictions
cell	string	The column-row identifier of a specific cell within a sheet (i.e. A1)	required
sheet	string	The unique identifier of a specific sheet within a spreadsheet.	required
spreadsheet	string	The unique identifier of the connected spreadsheet.	required

Example

{
  "cell": "A1",
  "sheet": "576696e0f7a143b4a0bc7c20a34480ab",
  "spreadsheet": "7a5e271acf1d49d480a6fbabc394a0fa"
}

Program

A Sustainability Program

Properties

Name	Type	Description	Restrictions
id	string(uuid)	The unique UUID identifier of the program	read-only
name	string	The name of the program. Must be unique within the workspace.	Maximum length: 150

Example

{
  "name": "Sustainability Program"
}

ProgramsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of Program objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[Program]	A Sustainability Program	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "name": "Sustainability Program"
    }
  ]
}

TableCellConnection

Represents a connection to a value from a Workiva table cell

Properties

Name	Type	Description	Restrictions
cell	string	The column-row identifier of a specific cell within a table (i.e. A1)	required
document	string	The unique identifier of the connected document.	required
section	string	The unique identifier of a specific section within the document.	required
table	string	The unique identifier of a specific table within the document.	required

Example

{
  "cell": "A1",
  "document": "944204de31eb4f078f531a25d7cdde2f",
  "section": "944204de31eb4f078f531a25d7cdde2f_34",
  "table": "576696e0f7a143b4a0bc7c20a34480ab"
}

Tag

Represents a tag associated with a metric in the program

Properties

Name	Type	Description	Restrictions
name	string	The key or category of the tag, representing a specific attribute of the metric.	required
value	string	The corresponding value for the tag key, specifying its classification or category.	required

Example

{
  "name": "Industry",
  "value": "Agriculture"
}

TextRegionConnection

Represents a connection to a value from a Workiva document text region

Properties

Name	Type	Description	Restrictions
document	string	The unique identifier of the connected document.	required
section	string	The unique identifier of a specific section within the document.	required

Example

{
  "document": "944204de31eb4f078f531a25d7cdde2f",
  "section": "944204de31eb4f078f531a25d7cdde2f_34"
}

Topic

Represents a topic, an organizational and grouping mechanism for metrics. Each topic may have subtopics and metrics.

Properties

Name	Type	Description	Restrictions
id	string(uuid)	The unique UUID identifier of the topic.	read-only
index	integer	The index in the outline. If unset, the topic will be ordered last.
name	string	The name of the topic, up to 300 characters.	required
parent	string(uuid)¦null	The unique UUID identifier of the parent topic, if this topic is a subtopic. This field can be null for top-level topics.

Example

{
  "index": 0,
  "name": "Climate",
  "parent": "82bae647-8e43-44c3-a4e7-2aa3294c87ac"
}

TopicsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of Topic objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[Topic]	Represents a topic, an organizational and grouping mechanism for metrics. Each topic may have subtopics and metrics.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "index": 0,
      "name": "Climate",
      "parent": "82bae647-8e43-44c3-a4e7-2aa3294c87ac"
    }
  ]
}