Surveys
GET /v1/surveys
Model interface schema in TypeScript:
interface Survey {
// Unique Id - ObjectId (24 character hex string)
_id: string,
// User set name of the survey - Max: 500 characters
name?: string;
// Survey complete date - ISO 8601 format
completedDate?: Date,
// Only set when type is "aggregated" - ISO 8601 format
aggregatedDate?: Date,
// Aggregate survey used multiple other surveys to combine values into new survey
type: 'default' | 'aggregated',
// Reporting level (node) Id - ObjectId
initiativeId: string,
// Reporting period
period: 'monthly' | 'quarterly' | 'yearly',
// Period end date - ISO 8601 format
effectiveDate: Date,
// Only allow to create "actual" type of surveys at the moment
utrvType: 'actual',
// Determine if evidence is required for underlying Universal Tracker Values
evidenceRequired: boolean,
// Determine if verification step is required for underlying Universal Tracker Values
verificationRequired: boolean,
// Survey Universal Tracker Values default private value
isPrivate?: boolean,
// Most recent update timestamp for Survey metadata changes or underlying
// Universal Tracker Values. See details below for tracked metadata fields.
lastUpdated?: Date
}Tracked Survey Metadata Fields
View tracked fields
Changes to the following Survey fields will update the lastUpdated timestamp:
name- Survey namescope- Survey scope configurationevidenceRequired- Evidence requirement settingnoteRequired- Note requirement settingverificationRequired- Verification requirement settingisPrivate- Privacy settingtype- Survey type (default/aggregated)
List surveys
Allow to list all surveys associated with connection initiativeId
Request
curl --location 'https://api.sg.g17.eco/v1/surveys' \
--header 'Authorization: Bearer TOKEN_HERE'Response
{
"success": true,
"data": [
{
"_id": "62d9530ce3e05eca98c84663",
"period": "yearly",
"evidenceRequired": false,
"verificationRequired": false,
"type": "default",
"effectiveDate": "2022-07-21T13:22:20.575Z",
"utrvType": "actual",
"initiativeId": "62d9530ce3e05eca98c8465d",
"completedDate": "2022-07-21T14:42:55.087Z"
},
{
"_id": "6361eb2c1a6ad86071ce3304",
"name": "Q4 Reporting",
"period": "yearly",
"effectiveDate": "2022-12-31T23:59:59.999Z",
"utrvType": "actual",
"initiativeId": "62d9530ce3e05eca98c8465d",
"evidenceRequired": true,
"verificationRequired": false,
"type": "default",
"completedDate": "2023-05-09T07:29:05.643Z"
},
{
"_id": "63637694c60ea840343394b8",
"name": "Special report for last month",
"period": "yearly",
"effectiveDate": "2022-11-30T23:59:59.999Z",
"utrvType": "actual",
"initiativeId": "62d9530ce3e05eca98c8465d",
"evidenceRequired": true,
"verificationRequired": false,
"type": "default"
}
]
}changedSince filter
Filter results to return only surveys where Survey metadata or at least one Universal Tracker Value has been updated after the specified date.
curl --location 'https://api.sg.g17.eco/v1/surveys?changedSince=2025-02-01' \
--header 'Authorization: Bearer TOKEN_HERE'{
"success": true,
"data": [
{
"_id": "6362124d1a6ad86071ce52a9",
"period": "yearly",
"effectiveDate": "2022-12-31T23:59:59.999Z",
"utrvType": "actual",
"initiativeId": "5bb4ab10e90adc12160dddae",
"evidenceRequired": true,
"verificationRequired": true,
"type": "default",
"lastUpdated": "2025-02-14T04:59:11.273Z"
},
]
}Get Survey
GET /v1/surveys/:surveyId
Retrieve a single survey model by id together with associated Universal Tracker Values (utrv). Use this response to individually fetch information about universal tracker values or update answer information.
The universalTrackerValues array contains the same fields as the UniversalTrackerValue interface described in the Universal Tracker Values documentation, including the notes and assuranceStatus fields.
Request
curl --location 'https://api.sg.g17.eco/v1/surveys/5eab31413874c723a249d81c' \
--header 'Authorization: Bearer TOKEN_HERE'Response
{
"success": true,
"data": {
"_id": "62d9530ce3e05eca98c84663",
"period": "yearly",
"evidenceRequired": false,
"verificationRequired": false,
"type": "default",
"effectiveDate": "2022-07-21T13:22:20.575Z",
"utrvType": "actual",
"initiativeId": "62d9530ce3e05eca98c8465d",
"completedDate": "2022-07-21T14:42:55.087Z",
"universalTrackerValues": [
{
"_id": "62d9530de3e05eca98c84b49",
"period": "yearly",
"evidenceRequired": false,
"verificationRequired": false,
"status": "verified",
"effectiveDate": "2022-07-21T13:22:20.575Z",
"universalTrackerId": "607818272c2c251ef832bec9",
"initiativeId": "62d9530ce3e05eca98c8465d",
"valueData": {
"table": []
},
"value": 500,
"valueType": "number",
"universalTracker": {
"name": "Volunteering Hours - Total",
"valueLabel": "Total number of volunteering hours?",
"instructions": "Please include all volunteering activities by employees during business hours.",
"type": "kpi",
"typeCode": "",
"valueType": "number",
"unit": "h",
"unitType": "time"
}
},
{
"_id": "62d9530de3e05eca98c84b64",
"period": "yearly",
"evidenceRequired": false,
"verificationRequired": false,
"status": "verified",
"effectiveDate": "2022-07-21T13:22:20.575Z",
"universalTrackerId": "5e735d7a1f2c7d3484ed6d3b",
"initiativeId": "62d9530ce3e05eca98c8465d",
"valueData": {
"table": [
[
{
"code": "male",
"value": "10"
},
{
"code": "female",
"value": "20"
},
{
"code": "senior",
"value": "30"
},
{
"code": "middle",
"value": "50"
},
{
"code": "non_management",
"value": "5040"
},
{
"code": "technical",
"value": "1344"
},
{
"code": "administrative",
"value": "216"
},
{
"code": "production",
"value": "111"
}
]
]
},
"valueType": "table",
"universalTracker": {
"name": "Average Hours of Training",
"valueLabel": "Average hours of training that the organization's employees have undertaken during the reporting period, by:",
"instructions": "Report the average number of training hours per employee for each category. Include both internal and external training programs.",
"type": "gri",
"typeCode": "404-1/a",
"valueType": "table",
"valueValidation": {
"table": {
"columns": [
{
"code": "male",
"name": "Male",
"type": "number",
"unit": "h",
"unitType": "time",
},
{
"code": "female",
"name": "Female",
"type": "number",
"unit": "h",
"unitType": "time",
},
{
"code": "senior",
"name": "Senior Management",
"type": "number",
"unit": "h",
"unitType": "time",
},
{
"code": "middle",
"name": "Middle Management",
"type": "number",
"unit": "h",
"unitType": "time",
},
{
"code": "non_management",
"name": "Non-management",
"type": "number",
"unit": "h",
"unitType": "time",
},
{
"code": "technical",
"name": "Technical",
"type": "number",
"unit": "h",
"unitType": "time",
},
{
"code": "administrative",
"name": "Administrative",
"type": "number",
"unit": "h",
"unitType": "time",
},
{
"code": "production",
"name": "Production",
"type": "number",
"unit": "h",
"unitType": "time",
}
],
"validation": {
"maxRows": 1
}
}
}
}
}
// ... and more
]
}
}