Higg FEM - Data Dictionary - Worldly Developer Docs

The Higg Facility Environmental Module (Higg FEM) is a sustainability assessment tool that standardizes
how factories measure and evaluate their environmental performance, year over year. The Higg FEM is designed to:

Measure and quantify the sustainability impacts of a facility
Reduce redundancy in measuring and reporting sustainability performance
Drive business value through reducing risk and uncovering efficiencies
Create a common means and language to communicate sustainability to stakeholders

The FEM contains thousands of questions and indicators. When interacting with FEM data, there are a few general guidelines to keep in mind. FEM assessments are versioned each year. Each assessment has a set of metadata available about the assessment and the factory who is completing it. Then there are all of the questions, factory self-responses, and verifier responses. Then there are calculated outputs, such as aggregated impacts (for example total energy usage) and scores for each section. To make accessing different types of data more efficient, these APIs allow you to construct queries for selected assessments or groups of assessments, and also to specify which data elements are returned to you. Below are the primary categories of data that are available.

Assessment Metadata

Field	Description	Type
id	The unique identifier for the assessment — e.g. `femsurvey:7e1afda7-46fd-49cc-90ad-c0aed4aa5401`	string
statusHistory	Array of dates for the most status transition for status	array
status	The current status for the assessment — NS, ASI, ASC, VRP, VRQ, VRE, VRC, VRF, VRD, VRI, ASD	string
version	The type and version of the assessment — e.g. fem2022, fem2023, fslm, brm2022	string
accountId	The UUID of the account that owns the assessment	string
accountName	The name of the account that owns the assessment	string
sacId	The short ID (Higg/Worldly ID) of the account that owns the assessment	string
country	The name of the country in which the account is located	string
selfPosted	Indicates if the self-assessment has been completed and posted	Boolean
verifiedPosted	Indicates if the verified-assessment has been completed and posted	Boolean
verified	Indicates if verification is enabled as an option for the assessment	Boolean
createdOn	The unix timestamp when the assessment was created in Worldly	timestamp
lastUpdated	The unix timestamp when the assessment was last updated	timestamp
location	An array of location attributes, such as address, placeid, and lat/long	array
oarId	Optional open supply hub identifier for the account that owns the assessment	string
ffcId	Optional FFC id for the account that owns the assessment	string
taxId	Optional tax identifier for the account that owns the assessment	string
socialCreditId	Optional Chinese social credit id for the account that owns the assessment	string
customId	Optional custom identifier for the account that owns the assessment, as provided by the account who the assessment has been shared with	string
parentCompanyId	The UUID of the account that is identified as the parent to the account that owns the assessment	string
parentCompanyName	The name of the parent company account	string
parentCompanySacId	The short ID of the parent company account	string
v1Verified		Boolean
tags	An array of custom text strings for the assessment, as provided by the account who the assessment has been shared with	array
statusNotes		string
verifierBodyName	The name of the verifier company	string
verifierType	The type of verification	string
verifierStartDate	The date on which verification started	date
verifierEndDate	The date on which verification ended	date
questions	An array of all the question responses for the entire assessment	array
performance	An array of just the selected performance fields	array
scores	An array of the scores and level achievements	array
usage	An array of calculated outputs, based on responses to questions. For example, total energy or water use.	array
focus_areas	An array of the indicators that were identified as areas of focus, based on the assessment responses	array
verification_details	An array of fields with details about the verification for the assessment	array

FEM Content

The specific questions, option lists, and calculated outputs vary between FEM versions. For the full data dictionary for FEM 4.0 / FEM 2023, for a list of what has changed between FEM 3.0 and FEM 4.0, or for other resources about FEM content please reference the documents from this page. For a list of what has changed between FEM 3.0 and FEM 4.0, please see this file.

Due to the significant changes with FEM 4.0, there are some refIDs from FEM 3.0 that are not longer direct questions within FEM 4.0. To support some level of backwards compatibility, some additional transformations have been added to be able to continue to map a subset of FEM content into the legacy CSV V2 data export.Currently, these calculated outputs are only used to populate values returned in the Bulk CSV.

Performance

This is a curated dataset with simplified and readable column names, normalized across FEM versions. It contains key metadata, facility classifiers, scores, and quantitative values. For a list of the fields included in this dataset, please see this file. This dataset can be retrieved as a CSV stream via the FEM Performance CSV API, and also by using the ‘performance’ key im the include array via the FEM Module Data API For legacy documentation about this dataset, see this pdf.

Scores and Levels

For the FEM Module Data API, you may include the ‘scores’ key in the include array. When this is requested, the ‘scores’ key will be populated in the results. The format of this result contains data for overall score, section level scores, and per question scores. If no verified data is available, the verified score will not be populated.

GHGs (Greenhouse Gases)

For the FEM Module Data API, you may include the ‘ghg’ key in the include array. When this is requested, the ‘ghg’ key will be populated in the results. The format of this result contains data for all emissions sources and is converted to standard units (liter, kg and MJ) (see How To Higg for more data on this). If no verified data is available, the verified data will not be populated.

Resource Usage

For the FEM Module Data API, you may include the ‘usage’ key in the include array. When this is requested, the ‘usage’ key will be populated in the results. The format of this result contains data for all resource usage metrics and is converted to standard units (liter, kg and MJ). For FEM 4.0, this also includes subtotal calculations. If no verified data is available, the verified data will not be populated.

Focus Areas

For the FEM Module Data API, you may include the ‘focus_areas’ key in the include array. When this is requested, the ‘focus_areas’ key will be populated in the results. Being able to quickly pin point critical hotspots in your supply chain empowers you to take action sooner. For example, facilities who have indicated they were not in compliance with local permits may need a corrective action plan. For the FEM, there are two main levels for Focus Areas:

Critical Risks: Those questions that cover basic legal compliance statuses for facilities, including: facility operating licenses, environmental permits, governmental violations, and other general compliance questions.
Areas of Opportunity: While many FEM questions can be defined as key areas of opportunity, those flagged in this level adhere closely to SAC’s current scoring methodology and the general organization of questions in FEM, and they typically refer to the main question within a given section (or page title) scoring rules.

Example FEM Data

Here is an example request and response from the module-data endpoint for an FEM2023, with ALL available data.

Request

curl --request POST \
     --url https://api-v2.production.higg.org/api/v1/moduledata/fem \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: <<apiKey>>'
     --header 'x-developer-request-token: <<apiKey>>'
     -d '{
    "include": [
        "questions",
        "performance",
        "scores",
        "ghgs",
        "usage",
        "focus_areas"
    ],
    "assessmentIds": ["femsurvey:fa96c26b-85bb-4caa-82c1-3d1a3850d0cf"],
    "from": 0,
    "size":1
}'

Response

{
    "total": 1,
    "assessments": [
        {
            "id": "femsurvey:fa96c26b-85bb-4caa-82c1-3d1a3850d0cf",
            "statusHistory": {
                "NS": "2024/02/02",
                "ASI": "2024/05/09",
                "ASC": "2024/05/09",
                "VRP": "2024/05/09",
                "VRQ": "2024/05/10",
                "VRE": "",
                "VRC": "2024/05/10",
                "VRF": "2024/05/10",
                "VRD": "",
                "VRI": "",
                "ASD": ""
            },
            "status": "VRF",
            "version": "fem2023",
            "accountId": "5eda93a60905d9000a322def",
            "accountName": "French Facility",
            "sacId": 134476,
            "country": "France",
            "selfPosted": true,
            "verifiedPosted": true,
            "verified": true,
            "createdOn": 1706908832732,
            "lastUpdated": 1715364430855,
            "location": {
                "address": "Paris, France",
                "vicinity": "Paris",
                "country": "France",
                "placeid": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
                "lat": 48.85661400000001,
                "long": 2.3522219
            },
            "oarId": "FR2020297DKTNDA",
            "ffcId": "",
            "taxId": "",
            "socialCreditId": "",
            "parentCompanyId": "",
            "parentCompanyName": "",
            "parentCompanySacId": "",
            "v1VerifiedId": "",
            "tags": [],
            "statusNotes": "",
            "cadence": [],
            "verifierBodyName": "Example VB",
            "verifierType": "Onsite",
            "verifierStartDate": "2024-05-06",
            "verifierEndDate": "2024-05-08",
            "questions": {
                "sitecountry": {
                    "value": "Afghanistan",
                    "corrected": "Albania",
                    "selection": "inaccurate",
                    "flag": false,
                    "data": "must have been a typo. changed to Albania."
                },
                "sipfacilitytype": {
                    "value": "Finished Product Assembler,Finished Product Processing (Product Printing, Product Painting, Product Dyeing, Product Laundering and Product Finishing, Embroidery & Embellishments),Component / Sub-Assembly Manufacturing (incl Packaging) (e.g. Label, Zipper, Snap, Button, Elastic Bungee, cardboard, etc),Material Production (Raw and intermediate materials are transformed into their final state before assembly) (e.g. Fabric dye-house, Fabric manufacturer, Yarn Dyeing, PCB manufacturer, etc),Raw Material Processing (Raw Materials are processed into intermediate material products) (e.g. Yarn Spinning).,Raw Material Collection & Bulk Refining (Materials are collected/extracted/farmed and refined to bulk commodity state) (eg. Cotton Farming and Ginning, processing of bottles, fabric scrap, etc.. into new recycled material)",
                    "corrected": "Finished Product Assembler,Finished Product Processing (Product Printing, Product Painting, Product Dyeing, Product Laundering and Product Finishing, Embroidery & Embellishments),Component / Sub-Assembly Manufacturing (incl Packaging) (e.g. Label, Zipper, Snap, Button, Elastic Bungee, cardboard, etc),Material Production (Raw and intermediate materials are transformed into their final state before assembly) (e.g. Fabric dye-house, Fabric manufacturer, Yarn Dyeing, PCB manufacturer, etc),Raw Material Processing (Raw Materials are processed into intermediate material products) (e.g. Yarn Spinning).,Raw Material Collection & Bulk Refining (Materials are collected/extracted/farmed and refined to bulk commodity state) (eg. Cotton Farming and Ginning, processing of bottles, fabric scrap, etc.. into new recycled material)",
                    "selection": "accurate",
                    "flag": false,
                    "data": ""
                },
                // ... rest of the object remains unchanged for brevity ...
            }
        }
    ]
}

Getting Started

Data Dictionaries

Higg FEM - Data Dictionary

Assessment Metadata

FEM Content

Performance

Scores and Levels

GHGs (Greenhouse Gases)

Resource Usage

Focus Areas

Example FEM Data

Request

Response

​Assessment Metadata

​FEM Content

​Performance

​Scores and Levels

​GHGs (Greenhouse Gases)

​Resource Usage

​Focus Areas

​Example FEM Data

​Request

​Response

Assessment Metadata

FEM Content

Performance

Scores and Levels

GHGs (Greenhouse Gases)

Resource Usage

Focus Areas

Example FEM Data

Request

Response