Practices Survey Platform API Reference
This is the reference documentation for the Practices Survey Platform API. Most API calls require an authentication token. To authenticate, take a look at the Profile, Billing and Access Control API reference documentation.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
Browse the API endpoints by ...
By workflows
Assessments
- Clears answers
- Creates a campaign
- Creates a new sample
- Freezes a sample
- Freezes part of sample
- Lists an assessment
- Lists answers
- Lists campaigns
- Lists candidate answers
- Lists frozen samples
- Lists part of an assessment
- Lists quantitative measurements
- Lists units available
- Lists updatable samples
- Lists values in an account
- Records quantitative measurements
- Retrieve a aggregated metric over a time period
- Retrieves a campaign
- Retrieves a sample
- Retrieves a unit
- Updates an answer
- Uses candidate answers
This section contains APIs related to assessments
Reporting
- Creates a profiles fitler
- Creates a questions fitler
- Deletes a matrix of scores for cohorts against a metric
- Deletes a profile in an enumerated profiles filter
- Deletes a profiles fitler
- Deletes a questions fitler
- Lists assessments for reporting profiles
- Lists fitlers
- Lists profiles filters
- Lists questions filters
- Retrieves GHG emissions reported (in percentage)
- Retrieves GHG emissions reported (in tons)
- Retrieves a matrix of scores for cohorts against a metric
- Retrieves a profile in an enumerated profiles filter
- Retrieves a profiles fitler
- Retrieves a questions fitler
- Retrieves assessments completed by segments
- Retrieves planned improvements and targets
- Retrieves the completion rate
- Updates a fitler
- Updates a matrix of scores for cohorts against a metric
- Updates a profile in an enumerated profiles filter
- Updates a profiles fitler
- Updates a questions fitler
This section contains APIs related to reporting
Lists units available
GET /api/units
This API end-point lists all the units of measurement available to record datapoints.
Alongside the usual metric units (meters, kilogram, etc.) and imperial units (inch, pounds, etc.), there could be units with a rank system (natural integers), or an enumerated system (finite set of values with no order). A special unit is used to represent free form text.
Query parameters
A page number within the paginated result set.
units that can be used intercheably with this one
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier that can be used in a URL
Short description suitable for display
One of standard (metric system), imperial, rank, enum, or freetext
Examples
curl https://livedemo.djaoapp.com/api/units{ "count": 1, "previous": null, "next": null, "results": [ { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] } ] }
Retrieves a unit
GET /api/units/{unit}
Retrieves the details of a Unit.
Responses
Unique identifier that can be used in a URL
Short description suitable for display
One of standard (metric system), imperial, rank, enum, or freetext
Examples
curl https://livedemo.djaoapp.com/api/units/assessment{ "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }
Lists campaigns
GET /api/{profile}/campaigns
Lists campaigns that belongs to a profile.
Query parameters
A page number within the paginated result set.
date/time in ISO format after which records were created.
date/time in ISO format before which records were created.
value to search for in the fields specified by q_f
restrict searches to one or more fields in: title. searches all fields when unspecified.
sort by created_at, title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier that can be used in a URL
Account this sample belongs to.
Enter a campaign title.
This description will be displayed to interviewees.
Whether the campaign is available or not
Examples
curl https://livedemo.djaoapp.com/api/alliance/campaigns{ "count": 1, "results": [ { "slug": "construction", "account": "alliance", "title": "Assessment on sustainable construction practices", "active": true } ] }
Creates a campaign
POST /api/{profile}/campaigns
Creates a campaign against which profiles can be assessed.
Request body
Enter a campaign title.
This description will be displayed to interviewees.
If checked, correct answser are required
Default unit for measured field when none is specified
Extra meta data (can be stringify JSON)
Responses
Unique identifier that can be used in a URL
Enter a campaign title.
This description will be displayed to interviewees.
If checked, correct answser are required
Default unit for measured field when none is specified
Extra meta data (can be stringify JSON)
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Sustainable construction practices"}' https://livedemo.djaoapp.com/api/alliance/campaigns{ "slug": "sustainable-construction-practices", "title": "Sustainable construction practices" }
Retrieves a campaign
GET /api/{profile}/campaigns/{campaign}
Retrieves the details of a Campaign.
Responses
Unique identifier that can be used in a URL
Account this sample belongs to.
Enter a campaign title.
This description will be displayed to interviewees.
Whether the campaign is available or not
If checked, correct answser are required
Unique identifier that can be used in URL
Short description
Unique identifier that can be used in a URL
Short description suitable for display
One of standard (metric system), imperial, rank, enum, or freetext
Hint for the user interface on how to present the input field
Examples
curl https://livedemo.djaoapp.com/api/alliance/campaigns/sustainability{ "slug": "construction", "account": "alliance", "title": "Assessment on sustainable construction practices", "active": true, "quizz_mode": false, "questions": [ { "path": "/construction/product-design", "title": "Product Design", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, { "path": "/construction/packaging-design", "title": "Packaging Design", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" } ] }
Lists fitlers
GET /api/{profile}/filters
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/filters{ "count": 2, "next": null, "previous": null, "results": [ { "slug": "boxes-and-enclosures", "title": "Boxes & enclosures", "extra": "", "predicates": [ { "rank": 0, "operator": "startswith", "operand": "/metal/boxes-and-enclosures", "field": "extra", "selector": "keepmatching" } ], "likely_metric": null } ] }
Lists profiles filters
GET /api/{profile}/filters/accounts
Query parameters
A page number within the paginated result set.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/filters/accounts{ "count": 1, "previous": null, "next": null, "results": [ { "slug": "supplier-1", "full_name": "Supplier 1", "email": "supplier-1@localhost.localdomain" } ] }
Creates a profiles fitler
POST /api/{profile}/filters/accounts
Responses
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/energy-utility/filters/accounts{ "slug": "supplier-1", "printable_name": "Supplier 1", "extra": null }
Lists values in an account
GET /api/{profile}/filters/accounts/values
Query parameters
A page number within the paginated result set.
date/time in ISO format after which records were created.
date/time in ISO format before which records were created.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/filters/accounts/values{ "count": 0, "next": null, "previous": null, "results": [ { "created_at": "2020-01-01T00:00:00Z", "measured": 12, "unit": "tons" } ] }
Retrieves a profiles fitler
GET /api/{profile}/filters/accounts/{editable_filter}
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/filters/accounts/suppliers{ "slug": "suppliers", "title": "Energy utility suppliers", "extra": null, "predicates": [], "likely_metric": null, "results": [ { "facility": "Main factory", "fuel_type": "natural-gas", "allocation": "Energy utility", "created_at": null, "ends_at": null, "amount": 100, "unit": "mmbtu" } ] }
Updates a profiles fitler
POST /api/{profile}/filters/accounts/{editable_filter}
Request body
Extra meta data (can be stringify JSON)
Responses
Extra meta data (can be stringify JSON)
Examples
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"full_name": "Main"}' https://livedemo.djaoapp.com/api/energy-utility/filters/accounts/suppliers{ "slug": "main", "full_name": "Main" }
Updates a fitler
PUT /api/{profile}/filters/accounts/{editable_filter}
Request body
Title for the filter
Extra meta data (can be stringify JSON)
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Energy utility suppliers", "predicates": []}' https://livedemo.djaoapp.com/api/energy-utility/filters/accounts/suppliers{ "slug": "suppliers", "title": "Energy utility suppliers", "extra": null, "predicates": [], "likely_metric": null, "results": [ { "facility": "Main factory", "fuel_type": "natural-gas", "allocation": "Energy utility", "created_at": null, "ends_at": null, "amount": 100, "unit": "mmbtu" } ] }
Deletes a profiles fitler
DELETE /api/{profile}/filters/accounts/{editable_filter}
Responses
204 No Content
Examples
curl -X DELETE https://livedemo.djaoapp.com/api/energy-utility/filters/accounts/suppliersLists quantitative measurements
GET /api/{profile}/filters/accounts/{editable_filter}/values
Query parameters
A page number within the paginated result set.
date/time in ISO format after which records were created.
date/time in ISO format before which records were created.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/filters/accounts/ghg-emissions/values{ "count": 0, "next": null, "previous": null, "results": [ { "created_at": "2020-01-01T00:00:00Z", "measured": 12, "unit": "tons" } ] }
Records quantitative measurements
POST /api/{profile}/filters/accounts/{editable_filter}/values
Records numeric measurements towards a specific metric.
When baseline_at is specified, the measurement refers to a relative value since baseline_at. When baseline_at is not specified, the intent is to record an absolute measurement at time created_at.
Request body
Unit the measured field is in
measurement in unit
Account this sample belongs to.
Responses
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Account this sample belongs to.
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"created_at": "2020-01-01T00:00:00Z", "items": [{"slug": "main-factory", "measured": 12, "unit": "tons"}]}' https://livedemo.djaoapp.com/api/supplier-1/filters/accounts/ghg-emissions/values{ "created_at": "2020-01-01T00:00:00Z", "items": [ { "slug": "main-factory", "measured": 12, "unit": "tons" } ] }
Retrieves a profile in an enumerated profiles filter
GET /api/{profile}/filters/accounts/{editable_filter}/{rank}
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/filters/accounts/suppliers/1{ "title": "Main factory", "predicates": [] }
Updates a profile in an enumerated profiles filter
PUT /api/{profile}/filters/accounts/{editable_filter}/{rank}
Request body
Title for the filter
Extra meta data (can be stringify JSON)
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Main factory", "predicates": []}' https://livedemo.djaoapp.com/api/energy-utility/filters/accounts/suppliers/1{ "title": "Main factory", "predicates": [] }
Deletes a profile in an enumerated profiles filter
DELETE /api/{profile}/filters/accounts/{editable_filter}/{rank}
Responses
204 No Content
Examples
curl -X DELETE https://livedemo.djaoapp.com/api/energy-utility/filters/accounts/suppliers/1Lists questions filters
GET /api/{profile}/filters/questions
Query parameters
A page number within the paginated result set.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Default unit for measured field when none is specified
Extra meta data (can be stringify JSON)
Unique identifier that can be used in URL
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/filters/questions{ "count": 1, "previous": null, "next": null, "results": [ { "path": "/construction/product-design", "title": "Product Design", "default_unit": "assessment", "ui_hint": "radio" } ] }
Creates a questions fitler
POST /api/{profile}/filters/questions
Request body
Default unit for measured field when none is specified
Extra meta data (can be stringify JSON)
Unique identifier that can be used in URL
Responses
Default unit for measured field when none is specified
Extra meta data (can be stringify JSON)
Unique identifier that can be used in URL
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Construction", "default_unit": "assessment", "path": "/construction/product-design"}' https://livedemo.djaoapp.com/api/energy-utility/filters/questions{ "title": "Construction", "default_unit": "assessment", "path": "/construction/product-design" }
Retrieves a questions fitler
GET /api/{profile}/filters/questions/{editable_filter}
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/filters/questions/suppliers{ "slug": "suppliers", "title": "Energy utility suppliers", "predicates": [ { "rank": 1, "operator": "contains", "operand": "Energy", "field": "extra", "selector": "keepmatching" } ] }
Updates a questions fitler
PUT /api/{profile}/filters/questions/{editable_filter}
Request body
Title for the filter
Extra meta data (can be stringify JSON)
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"slug": "suppliers", "title": "Energy utility suppliers", "predicates": [{"rank": 1, "operator": "contains", "operand": "Energy", "field": "extra", "selector": "keepmatching"}]}' https://livedemo.djaoapp.com/api/energy-utility/filters/questions/suppliers{ "slug": "suppliers", "title": "Energy utility suppliers", "predicates": [ { "rank": 1, "operator": "contains", "operand": "Energy", "field": "extra", "selector": "keepmatching" } ] }
Deletes a questions fitler
DELETE /api/{profile}/filters/questions/{editable_filter}
Responses
204 No Content
Examples
curl -X DELETE https://livedemo.djaoapp.com/api/energy-utility/filters/questions/suppliersRetrieve a aggregated metric over a time period
GET /api/{profile}/metrics/aggregate/{path}
Query parameters
date/time in ISO format after which records were created.
date/time in ISO format before which records were created.
Responses
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/metrics/aggregate/ghg-emissions{ "created_at": "2020-01-01T00:00:00Z", "measured": 12, "unit": "tons" }
Lists grants and requests to be accepted/denied
GET /api/{profile}/portfolios
Lists all grants and requests that have to be accepted or denied by account.
If you want to get all requests that have been initiated by account, see /api/{account}/requests. If you want to get all grants that have been initiated account, see /api/{account}/grants.
Query parameters
A page number within the paginated result set.
filter by state
date/time in ISO format after which records were created.
date/time in ISO format before which records were created.
value to search for in the fields specified by q_f
restrict searches to one or more fields in: grantee__full_name, account__full_name. searches all fields when unspecified.
sort by grantee, account, state, ends_at. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/portfolios{ "count": 1, "next": null, "previous": null, "results": [ { "grantee": "energy-utility", "account": "supplier-1", "campaign": "sustainability", "ends_at": "2022-01-01T00:00:00Z", "state": "request-initiated", "api_accept": "/api/supplier-1/portfolios/requests/0000000000000000000000000000000000000002/" } ] }
Lists initiated grants
GET /api/{profile}/portfolios/grants
Lists all grants currently pending initiated by account.
Query parameters
A page number within the paginated result set.
filter by state
date/time in ISO format after which records were created.
date/time in ISO format before which records were created.
value to search for in the fields specified by q_f
restrict searches to one or more fields in: grantee__full_name, account__full_name. searches all fields when unspecified.
sort by grantee, account, state, ends_at. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/portfolios/grants{ "count": 1, "next": null, "previous": null, "results": [ { "grantee": "water-utility", "account": "supplier-1", "campaign": "sustainability", "ends_at": "2022-01-01T00:00:00Z", "state": "grant-initiated", "api_accept": "/api/water-utility/portfolios/grants/0000000000000000000000000000000000000003/" } ] }
Initiates a grant
POST /api/{profile}/portfolios/grants
Initiate a grant of data to a grantee
Request body
Responses
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"grantee": {"slug": "energy-utility", "full_name": "Energy Utility"}}' https://livedemo.djaoapp.com/api/supplier-1/portfolios/grants{ "grantee": { "slug": "energy-utility", "full_name": "Energy Utility" } }
Accepts a portfolio grant
POST /api/{profile}/portfolios/grants/{request_key}
An account has sent its portfolio to a grantee. The grantee accepts the request, making the account's answers up-to-date ends_at available to grantee.
Note that account parameter is the grantee we have send data to here, while the account parameter is the account owning that data when calling POST /api/{account}/grants.
Responses
200
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/energy-utility/portfolios/grants/0123456789abcef{}
Denies a portfolio grant
DELETE /api/{profile}/portfolios/grants/{request_key}
Responses
204 No Content
Examples
curl -X DELETE https://livedemo.djaoapp.com/api/energy-utility/portfolios/grants/0123456789abcefLists initiated requests
GET /api/{profile}/portfolios/requests
Lists all requests currently pending initiated by account.
Query parameters
A page number within the paginated result set.
filter by state
date/time in ISO format after which records were created.
date/time in ISO format before which records were created.
value to search for in the fields specified by q_f
restrict searches to one or more fields in: grantee__full_name, account__full_name. searches all fields when unspecified.
sort by grantee, account, state, ends_at. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/portfolios/requests{ "count": 3, "next": null, "previous": null, "results": [ { "grantee": "energy-utility", "account": "supplier-1", "campaign": "sustainability", "ends_at": "2022-01-01T00:00:00Z", "state": "request-denied", "api_accept": null }, { "grantee": "energy-utility", "account": "supplier-1", "campaign": "sustainability", "ends_at": "2022-01-01T00:00:00Z", "state": "request-initiated", "api_accept": "/api/supplier-1/portfolios/requests/0000000000000000000000000000000000000002/" }, { "grantee": "energy-utility", "account": "andy-shop", "campaign": "sustainability", "ends_at": "2022-01-01T00:00:00Z", "state": "request-initiated", "api_accept": "/api/andy-shop/portfolios/requests/0000000000000000000000000000000000000004/" } ] }
Initiates a request
POST /api/{profile}/portfolios/requests
Initiate a request of data for an account.
Request body
Responses
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"accounts": [{"slug": "supplier-1", "full_name": "Supplier 1"}]}' https://livedemo.djaoapp.com/api/energy-utility/portfolios/requests{ "accounts": [ { "slug": "supplier-1", "full_name": "Supplier 1" } ] }
Accepts a portfolio request
POST /api/{profile}/portfolios/requests/{request_key}
A grantee has made a request to account's portfolio. The account accepts the request, making the account's answers up-to-date ends_at available to grantee.
Note that account is the actual account we are looking to access data from here, while the account parameter is the grantee when calling POST /api/{account}/requests.
Responses
200
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/energy-utility/portfolios/requests/0123456789abcef{}
Denies a portfolio request
DELETE /api/{profile}/portfolios/requests/{request_key}
Responses
204 No Content
Examples
curl -X DELETE https://livedemo.djaoapp.com/api/energy-utility/portfolios/requests/0123456789abcefLists assessments for reporting profiles
GET /api/{profile}/reporting/{campaign}
List of suppliers accessible by the request user with normalized (total) score when the supplier completed an assessment.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier that can be used in a URL
Printable name
Primary contact e-mail
Most recent time an assessment was updated
Datetime at which the scorecard was requested
current reporting status
Most recent time an assessment was completed
segment that was answered
link to the scorecard
score
number of answers marked N/A
also reporting publicly
reporting environmental fines
energy measured and trended
ghg emissions measured and trended
water measured and trended
waste measured and trended
number of planned improvements
improvement targets
share was supplier initiated
extra information tags
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "andy-shop", "printable_name": "Andy's Shop", "email": "andy@localhost.localdomain", "last_activity_at": "2016-07-15T00:36:19.448000Z", "requested_at": null, "reporting_status": "Planning phase", "segment": "", "score_url": "", "normalized_score": null, "nb_na_answers": null, "reporting_publicly": null, "reporting_fines": null, "nb_planned_improvements": null, "tags": [ "high_impact" ] }, { "slug": "supplier-1", "printable_name": "S1 - Tamerin (Demo)", "email": "steve@localhost.localdomain", "last_activity_at": "2017-01-01T00:00:00Z", "requested_at": null, "reporting_status": "Completed", "segment": "Boxes & enclosures", "score_url": "/app/supplier-1/scorecard/f1e2e916eb494b90f9ff0a36982341/content/boxes-and-enclosures/", "normalized_score": 90, "nb_na_answers": 1, "reporting_publicly": true, "reporting_fines": null, "nb_planned_improvements": 1, "tags": [] } ] }
Retrieves assessments completed by segments
GET /api/{profile}/reporting/{campaign}/by-segments
Returns the number of reporting accounts aggregated by segments.
Responses
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Datapoints in the serie
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/by-segments{ "title": "Assessments completed by segments", "scale": 1, "unit": "profiles", "table": [ { "key": "Energy utility", "values": [] }, { "key": "Trade Association", "values": [] } ] }
Retrieves the completion rate
GET /api/{profile}/reporting/{campaign}/completion-rate
Returns the week-by-week percentage of requested accounts that have completed a scorecard.
Responses
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Datapoints in the serie
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/completion-rate{ "title": "Completion rate (%)", "scale": 1, "unit": "percentage", "table": [ { "key": "% completion", "values": [ [ "2020-09-13T00:00:00Z", 0 ], [ "2020-09-20T00:00:00Z", 0 ], [ "2020-09-27T00:00:00Z", 0 ], [ "2020-10-04T00:00:00Z", 0 ], [ "2020-10-11T00:00:00Z", 0 ], [ "2020-10-18T00:00:00Z", 0 ], [ "2020-10-25T00:00:00Z", 0 ], [ "2020-11-01T00:00:00Z", 0 ], [ "2020-11-08T00:00:00Z", 0 ], [ "2020-11-15T00:00:00Z", 0 ], [ "2020-11-22T00:00:00Z", 0 ], [ "2020-11-29T00:00:00Z", 0 ], [ "2020-12-06T00:00:00Z", 0 ], [ "2020-12-13T00:00:00Z", 0 ], [ "2020-12-20T00:00:00Z", 0 ], [ "2020-12-27T00:00:00Z", 0 ], [ "2021-01-03T00:00:00Z", 0 ] ] }, { "key": "vs. last year", "values": [ [ "2019-09-15T00:00:00Z", 0 ], [ "2019-09-22T00:00:00Z", 0 ], [ "2019-09-29T00:00:00Z", 0 ], [ "2019-10-06T00:00:00Z", 0 ], [ "2019-10-13T00:00:00Z", 0 ], [ "2019-10-20T00:00:00Z", 0 ], [ "2019-10-27T00:00:00Z", 0 ], [ "2019-11-03T00:00:00Z", 0 ], [ "2019-11-10T00:00:00Z", 0 ], [ "2019-11-17T00:00:00Z", 0 ], [ "2019-11-24T00:00:00Z", 0 ], [ "2019-12-01T00:00:00Z", 0 ], [ "2019-12-08T00:00:00Z", 0 ], [ "2019-12-15T00:00:00Z", 0 ], [ "2019-12-22T00:00:00Z", 0 ], [ "2019-12-29T00:00:00Z", 0 ], [ "2020-01-05T00:00:00Z", 0 ] ] }, { "key": "Trade Association", "values": [ [ "2020-09-13T00:00:00Z", 0 ], [ "2020-09-20T00:00:00Z", 0 ], [ "2020-09-27T00:00:00Z", 0 ], [ "2020-10-04T00:00:00Z", 0 ], [ "2020-10-11T00:00:00Z", 0 ], [ "2020-10-18T00:00:00Z", 0 ], [ "2020-10-25T00:00:00Z", 0 ], [ "2020-11-01T00:00:00Z", 0 ], [ "2020-11-08T00:00:00Z", 0 ], [ "2020-11-15T00:00:00Z", 0 ], [ "2020-11-22T00:00:00Z", 0 ], [ "2020-11-29T00:00:00Z", 0 ], [ "2020-12-06T00:00:00Z", 0 ], [ "2020-12-13T00:00:00Z", 0 ], [ "2020-12-20T00:00:00Z", 0 ], [ "2020-12-27T00:00:00Z", 0 ], [ "2021-01-03T00:00:00Z", 0 ] ] } ] }
Retrieves GHG emissions reported (in tons)
GET /api/{profile}/reporting/{campaign}/ghg-emissions-amount
Returns the total GHG emissions in tons of reporting accounts (for reporting accounts that actually report emissions).
Responses
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Datapoints in the serie
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/ghg-emissions-amount{ "title": "GHG emissions reported", "scale": 1, "unit": "tons", "table": [ { "key": "Energy utility", "values": [] }, { "key": "Trade Association", "values": [] } ] }
Retrieves GHG emissions reported (in percentage)
GET /api/{profile}/reporting/{campaign}/ghg-emissions-rate
Returns the percentage of reporting accounts which report GHG emissions.
Responses
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Datapoints in the serie
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/ghg-emissions-rate{ "title": "GHG emissions reported", "scale": 1, "unit": "percentage", "table": [ { "key": "Energy utility", "values": [ [ "Reported", 0 ], [ "Not reported", 0 ] ] }, { "key": "Trade Association", "values": [ [ "Reported", 0 ], [ "Not reported", 0 ] ] } ] }
Retrieves planned improvements and targets
GET /api/{profile}/reporting/{campaign}/goals
Returns the number of reporting accounts with planned improvements, targets or both.
Responses
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Datapoints in the serie
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/goals{ "title": "Goals", "scale": 1, "unit": "profiles", "table": [ { "key": "Energy utility", "values": [ [ "Assessment only", 0 ], [ "Targets or plan", 0 ], [ "Targets and plan", 0 ] ] }, { "key": "Trade Association", "values": [ [ "Assessment only", 0 ], [ "Targets or plan", 0 ], [ "Targets and plan", 0 ] ] } ] }
Retrieves a matrix of scores for cohorts against a metric
GET /api/{profile}/reporting/{campaign}/matrix/{path}
Uses the total score for each organization as recorded by the assessment surveys and present aggregates by industry sub-sectors (Boxes & enclosures, etc.)
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/matrix/totals{ "slug": "totals", "title": "Average scores by supplier industry sub-sector", "cohorts": [ { "slug": "/portfolio-a", "title": "Portfolio A", "tags": null, "predicates": [], "likely_metric": "/app/energy-utility/portfolios/portfolio-a/" } ] }
Updates a matrix of scores for cohorts against a metric
PUT /api/{profile}/reporting/{campaign}/matrix/{path}
Request body
Title for the filter
Extra meta data (can be stringify JSON)
Title for the filter
Extra meta data (can be stringify JSON)
Title for the filter
Extra meta data (can be stringify JSON)
Responses
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Title for the filter
Extra meta data (can be stringify JSON)
Name that can be safely used for display in HTML pages
URL location of the profile picture
Extra meta data (can be stringify JSON)
rank in filter
Examples
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Average scores by supplier industry sub-sector", "cohorts": []}' https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/matrix/languages{ "slug": "languages", "title": "All cohorts for all questions", "cohorts": [] }
Deletes a matrix of scores for cohorts against a metric
DELETE /api/{profile}/reporting/{campaign}/matrix/{path}
Responses
204 No Content
Examples
curl -X DELETE https://livedemo.djaoapp.com/api/energy-utility/reporting/sustainability/matrix/languagesLists updatable samples
GET /api/{profile}/sample
This API end-point returns all samples which have not been frozen for an account.
Query parameters
A page number within the paginated result set.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Campaign this sample is part of.
Unique identifier for the sample. It can be used in a URL.
Account this sample belongs to.
Date/time of creation (in ISO format)
Date/time of last update (in ISO format)
When True, answers to that sample cannot be updated.
URL at which the response is visible.
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/sample{ "count": 1, "previous": null, "next": null, "results": [ { "slug": "46f66f70f5ad41b29c4df08f683a9a7a", "created_at": "2018-01-24T17:03:34.926193Z", "campaign": "sustainability", "is_frozen": false, "extra": null } ] }
Creates a new sample
POST /api/{profile}/sample
Creates a new sample to record qualitative and/or quantitative data.
Request body
Campaign this sample is part of.
Responses
Campaign this sample is part of.
Unique identifier for the sample. It can be used in a URL.
Account this sample belongs to.
Date/time of creation (in ISO format)
Date/time of last update (in ISO format)
When True, answers to that sample cannot be updated.
URL at which the response is visible.
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/supplier-1/sample{ "slug": "46f66f70f5ad41b29c4df08f683a9a7a", "created_at": "2018-01-24T17:03:34.926193Z", "campaign": "sustainability" }
Retrieves a sample
GET /api/{profile}/sample/{sample}
Returns top level information about a sample.
Responses
Campaign this sample is part of.
Unique identifier for the sample. It can be used in a URL.
Account this sample belongs to.
Date/time of creation (in ISO format)
Date/time of last update (in ISO format)
When True, answers to that sample cannot be updated.
URL at which the response is visible.
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a{ "slug": "46f66f70f5ad41b29c4df08f683a9a7a", "created_at": "2018-01-24T17:03:34.926193Z", "updated_at": "2018-01-24T17:03:34.926193Z", "is_frozen": false, "account": "supplier-1", "campaign": "sustainability" }
Lists answers
GET /api/{profile}/sample/{sample}/answers/{path}
The list returned contains at least one measurement for each question in the campaign. If there are no measurement yet on a question, measured will be null.
There might be more than one measurement per question as long as there are no duplicated unit per question. For example, to the question adjust-air-fuel-ratio, there could be a measurement with unit assessment (Mostly Yes/ Yes / No / Mostly No) and a measurement with unit freetext (i.e. a comment).
The {sample} must belong to {organization}.
{path} can be used to filter the tree of questions by a prefix.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Question the answer refers to
Unique identifier that can be used in URL
Short description
Unique identifier that can be used in a URL
Short description suitable for display
One of standard (metric system), imperial, rank, enum, or freetext
Hint for the user interface on how to present the input field
Whether an answer is required or not.
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/answers/construction{ "count": 3, "previous": null, "next": null, "results": [ { "question": { "path": "/construction/governance/the-assessment-process-is-rigorous", "title": "The assessment process is rigorous", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "required": true, "measured": "yes", "unit": "assessment", "created_at": "2020-09-28T00:00:00.000000Z", "collected_by": "steve" }, { "question": { "path": "/construction/governance/the-assessment-process-is-rigorous", "title": "The assessment process is rigorous", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "measured": "Policy document on the public website", "unit": "freetext", "created_at": "2020-09-28T00:00:00.000000Z", "collected_by": "steve" }, { "question": { "path": "/construction/production/adjust-air-fuel-ratio", "title": "Adjust Air fuel ratio", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "required": true, "measured": null, "unit": null } ] }
Updates an answer
POST /api/{profile}/sample/{sample}/answers/{path}
This API end-point attaches a measurement (measured field) in unit (meters, kilograms, etc.) to a question (also called metric) named {path} as part of a {sample}.
If a measurement with that unit already exists for the couple ({path}, {sample}), the previous measurement is replaced, otherwise it is added.
If unit is not specified, the default unit for the question is used.
The {sample} must belong to {organization} and be updatable.
Request body
Unit the measured field is in
measurement in unit
Responses
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"measured": "mostly-no", "unit": "assessment"}' https://livedemo.djaoapp.com/api/supplier-1/sample/724bf9648af6420ba79c8a37f962e97e/answers/construction{ "created_at": "2020-09-28T00:00:00.000000Z", "collected_by": "steve", "measured": "mostly-no", "unit": "assessment" }
Retrieves benchmark graphs
GET /api/{profile}/sample/{sample}/benchmarks
XXX change resp to a {count:, results:} format.
Returns a list of graphs with anonymized performance of peers for paths marked as visible (see ::ref::api_score).
Responses
200
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/sample/ce6dc2c4cf6b40dbacef91fa3e934eed/benchmarks[ { "slug": "totals", "title": "Total Score", "nb_answers": 4, "nb_questions": 4, "nb_respondents": 2, "numerator": 12.0, "improvement_numerator": 8.0, "denominator": 26.0, "normalized_score": 46, "improvement_score": 30, "score_weight": 1.0, "highest_normalized_score": 88, "avg_normalized_score": 67, "created_at": "2017-08-02T20:18:19.089", "distribution": { "y": [ 0, 1, 0, 1 ], "x": [ "0-25%", "25-50%", "50-75%", "75-100%" ], "organization_rate": "25-50%" } }, { "slug": "energy-efficiency-management-basics", "title": "Management", "text": "/media/envconnect/management-basics.png", "tag": "management", "score_weight": 1.0 }, { "slug": "process-heating", "title": "Process heating", "text": "/media/envconnect/process-heating.png", "nb_questions": 4, "nb_answers": 4, "nb_respondents": 2, "numerator": 12.0, "improvement_numerator": 8.0, "denominator": 26.0, "normalized_score": 46, "improvement_score": 12, "highest_normalized_score": 88, "avg_normalized_score": 67, "created_at": "2017-08-02T20:18:19.089", "distribution": { "y": [ 0, 1, 0, 1 ], "x": [ "0-25%", "25-50%", "50-75%", "75-100%" ], "organization_rate": "25-50%" }, "score_weight": 1.0 } ]
Retrieves benchmark graphs
GET /api/{profile}/sample/{sample}/benchmarks/{path}
XXX change resp to a {count:, results:} format.
Returns a list of graphs with anonymized performance of peers for paths marked as visible (see ::ref::api_score).
Responses
200
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/sample/ce6dc2c4cf6b40dbacef91fa3e934eed/benchmarks/boxes-enclosures[ { "slug": "totals", "title": "Total Score", "nb_answers": 4, "nb_questions": 4, "nb_respondents": 2, "numerator": 12.0, "improvement_numerator": 8.0, "denominator": 26.0, "normalized_score": 46, "improvement_score": 30, "score_weight": 1.0, "highest_normalized_score": 88, "avg_normalized_score": 67, "created_at": "2017-08-02T20:18:19.089", "distribution": { "y": [ 0, 1, 0, 1 ], "x": [ "0-25%", "25-50%", "50-75%", "75-100%" ], "organization_rate": "25-50%" } }, { "slug": "energy-efficiency-management-basics", "title": "Management", "text": "/media/envconnect/management-basics.png", "tag": "management", "score_weight": 1.0 }, { "slug": "process-heating", "title": "Process heating", "text": "/media/envconnect/process-heating.png", "nb_questions": 4, "nb_answers": 4, "nb_respondents": 2, "numerator": 12.0, "improvement_numerator": 8.0, "denominator": 26.0, "normalized_score": 46, "improvement_score": 12, "highest_normalized_score": 88, "avg_normalized_score": 67, "created_at": "2017-08-02T20:18:19.089", "distribution": { "y": [ 0, 1, 0, 1 ], "x": [ "0-25%", "25-50%", "50-75%", "75-100%" ], "organization_rate": "25-50%" }, "score_weight": 1.0 } ]
Lists candidate answers
GET /api/{profile}/sample/{sample}/candidates/{path}
The list returned contains at least one answer for each question in the campaign. If there are no answer yet on a question, measured will be null.
There might be more than one answer per question as long as there are no duplicated unit per question. For example, to the question adjust-air-fuel-ratio, there could be an answer with unit assessment (Mostly Yes/ Yes / No / Mostly No) and an answer with unit freetext (i.e. a comment).
The sample must belong to organization.
path can be used to filter the tree of questions by a prefix.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Question the answer refers to
Unique identifier that can be used in URL
Short description
Unique identifier that can be used in a URL
Short description suitable for display
One of standard (metric system), imperial, rank, enum, or freetext
Hint for the user interface on how to present the input field
Whether an answer is required or not.
Examples
curl https://livedemo.djaoapp.com/api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/candidates/construction{ "count": 3, "previous": null, "next": null, "results": [ { "question": { "path": "/construction/governance/the-assessment-process-is-rigorous", "title": "The assessment process is rigorous", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "required": true, "measured": "yes", "unit": "assessment", "created_at": "2020-09-28T00:00:00.000000Z", "collected_by": "steve" }, { "question": { "path": "/construction/governance/the-assessment-process-is-rigorous", "title": "The assessment process is rigorous", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "measured": "Policy document on the public website", "unit": "freetext", "created_at": "2020-09-28T00:00:00.000000Z", "collected_by": "steve" }, { "question": { "path": "/construction/production/adjust-air-fuel-ratio", "title": "Adjust Air fuel ratio", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "required": true, "measured": null, "unit": null } ] }
Uses candidate answers
POST /api/{profile}/sample/{sample}/candidates/{path}
The list returned contains at least one answer for each question in the campaign. If there are no answer yet on a question, measured will be null.
There might be more than one answer per question as long as there are no duplicated unit per question. For example, to the question adjust-air-fuel-ratio, there could be an answer with unit assessment (Mostly Yes/ Yes / No / Mostly No) and an answer with unit freetext (i.e. a comment).
The sample must belong to organization.
path can be used to filter the tree of questions by a prefix.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unit the measured field is in
measurement in unit
Date/time of creation (in ISO format)
User that collected the answer
Question the answer refers to
Unique identifier that can be used in URL
Short description
Unique identifier that can be used in a URL
Short description suitable for display
One of standard (metric system), imperial, rank, enum, or freetext
Hint for the user interface on how to present the input field
Whether an answer is required or not.
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/candidates/construction{ "count": 3, "previous": null, "next": null, "results": [ { "question": { "path": "/construction/governance/the-assessment-process-is-rigorous", "title": "The assessment process is rigorous", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "required": true, "measured": "yes", "unit": "assessment", "created_at": "2020-09-28T00:00:00.000000Z", "collected_by": "steve" }, { "question": { "path": "/construction/governance/the-assessment-process-is-rigorous", "title": "The assessment process is rigorous", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "measured": "Policy document on the public website", "unit": "freetext", "created_at": "2020-09-28T00:00:00.000000Z", "collected_by": "steve" }, { "question": { "path": "/construction/production/adjust-air-fuel-ratio", "title": "Adjust Air fuel ratio", "default_unit": { "slug": "assessment", "title": "assessments", "system": "enum", "choices": [ { "rank": 1, "text": "mostly-yes", "descr": "Mostly yes" }, { "rank": 2, "text": "yes", "descr": "Yes" }, { "rank": 3, "text": "no", "descr": "No" }, { "rank": 4, "text": "mostly-no", "descr": "Mostly no" } ] }, "ui_hint": "radio" }, "required": true, "measured": null, "unit": null } ] }
Lists an assessment
GET /api/{profile}/sample/{sample}/content
The list returned contains at least one measurement for each question in the campaign. If there are no measurement yet on a question, measured will be null.
There might be more than one measurement per question as long as there are no duplicated unit per question. For example, to the question adjust-air-fuel-ratio, there could be a measurement with unit assessment (Mostly Yes/ Yes / No / Mostly No) and a measurement with unit freetext (i.e. a comment).
The {sample} must belong to {organization}.
{path} can be used to filter the tree of questions by a prefix.
Query parameters
A page number within the paginated result set.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier that can be used in URL paths
Picture icon that can be displayed alongside the title
Title of the page element
Long description of the page element
Reading time of the material (in hh:mm:ss)
Account that can edit the page element
Extra meta data (can be stringify JSON)
Examples
curl https://livedemo.djaoapp.com/api/andy-shop/sample/f1e2e916eb494b90f9ff0a36982342/content{ "count": 4, "results": [ { "count": 1, "slug": "sustainability", "path": "/sustainability", "indent": 0, "title": "Core Environment, Social and Governance (ESG) Assessment", "picture": null, "extra": { "pagebreak": true, "tags": [ "scorecard" ], "visibility": [ "public" ], "segments": [ "/sustainability" ] }, "avg_value": null, "environmental_value": null, "business_value": null, "profitability": null, "implementation_ease": null, "rank": -1, "required": false, "default_unit": null, "ui_hint": null, "nb_respondents": 0, "rate": {}, "opportunity": null }, { "count": 1, "slug": "governance", "path": "/sustainability/governance", "indent": 1, "title": "Strategy & Governance", "picture": "/tspproject/static/img/management-basics.png", "extra": { "segments": [ "/sustainability" ] }, "avg_value": null, "environmental_value": null, "business_value": null, "profitability": null, "implementation_ease": null, "rank": 1, "required": false, "default_unit": null, "ui_hint": null, "nb_respondents": 0, "rate": {}, "opportunity": null }, { "count": 1, "slug": "esg-strategy-heading", "path": "/sustainability/governance/esg-strategy-heading", "indent": 2, "title": "Environment, Social & Governance (ESG) Strategy", "picture": null, "extra": { "segments": [ "/sustainability" ] }, "avg_value": null, "environmental_value": null, "business_value": null, "profitability": null, "implementation_ease": null, "rank": 1, "required": false, "default_unit": null, "ui_hint": null, "nb_respondents": 0, "rate": {}, "opportunity": null }, { "count": 1, "slug": "formalized-esg-strategy", "path": "/sustainability/governance/esg-strategy-heading/formalized-esg-strategy", "indent": 3, "title": "(3) Does your company have a formalized ESG strategy and performance targets that: 1/ Define a future vision of ESG performance, 2/ Are clear, actionable, and achievable, 3/ Are resourced effectively, 4/ Address material issues for the business?", "picture": "/tspproject/static/img/management-basics.png", "extra": { "segments": [ "/sustainability" ] }, "avg_value": 0, "environmental_value": 1, "business_value": 1, "profitability": 1, "implementation_ease": 1, "rank": 4, "required": true, "default_unit": { "slug": "yes-no", "title": "Yes/No", "system": "enum", "choices": [ { "text": "Yes", "descr": "Yes" }, { "text": "No", "descr": "No" } ] }, "ui_hint": "yes-no-comments", "answers": [], "candidates": [], "planned": [], "nb_respondents": 0, "rate": {}, "opportunity": null } ] }
Lists part of an assessment
GET /api/{profile}/sample/{sample}/content/{path}
The list returned contains at least one measurement for each question in the campaign. If there are no measurement yet on a question, measured will be null.
There might be more than one measurement per question as long as there are no duplicated unit per question. For example, to the question adjust-air-fuel-ratio, there could be a measurement with unit assessment (Mostly Yes/ Yes / No / Mostly No) and a measurement with unit freetext (i.e. a comment).
The {sample} must belong to {organization}.
{path} can be used to filter the tree of questions by a prefix.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier that can be used in URL paths
Picture icon that can be displayed alongside the title
Title of the page element
Long description of the page element
Reading time of the material (in hh:mm:ss)
Account that can edit the page element
Extra meta data (can be stringify JSON)
Examples
curl https://livedemo.djaoapp.com/api/andy-shop/sample/f1e2e916eb494b90f9ff0a36982342/content/sustainability{ "count": 4, "results": [ { "count": 1, "slug": "sustainability", "path": "/sustainability", "indent": 0, "title": "Core Environment, Social and Governance (ESG) Assessment", "picture": null, "extra": { "pagebreak": true, "tags": [ "scorecard" ], "visibility": [ "public" ], "segments": [ "/sustainability" ] }, "avg_value": null, "environmental_value": null, "business_value": null, "profitability": null, "implementation_ease": null, "rank": -1, "required": false, "default_unit": null, "ui_hint": null, "nb_respondents": 0, "rate": {}, "opportunity": null }, { "count": 1, "slug": "governance", "path": "/sustainability/governance", "indent": 1, "title": "Strategy & Governance", "picture": "/tspproject/static/img/management-basics.png", "extra": { "segments": [ "/sustainability" ] }, "avg_value": null, "environmental_value": null, "business_value": null, "profitability": null, "implementation_ease": null, "rank": 1, "required": false, "default_unit": null, "ui_hint": null, "nb_respondents": 0, "rate": {}, "opportunity": null }, { "count": 1, "slug": "esg-strategy-heading", "path": "/sustainability/governance/esg-strategy-heading", "indent": 2, "title": "Environment, Social & Governance (ESG) Strategy", "picture": null, "extra": { "segments": [ "/sustainability" ] }, "avg_value": null, "environmental_value": null, "business_value": null, "profitability": null, "implementation_ease": null, "rank": 1, "required": false, "default_unit": null, "ui_hint": null, "nb_respondents": 0, "rate": {}, "opportunity": null }, { "count": 1, "slug": "formalized-esg-strategy", "path": "/sustainability/governance/esg-strategy-heading/formalized-esg-strategy", "indent": 3, "title": "(3) Does your company have a formalized ESG strategy and performance targets that: 1/ Define a future vision of ESG performance, 2/ Are clear, actionable, and achievable, 3/ Are resourced effectively, 4/ Address material issues for the business?", "picture": "/tspproject/static/img/management-basics.png", "extra": { "segments": [ "/sustainability" ] }, "avg_value": 0, "environmental_value": 1, "business_value": 1, "profitability": 1, "implementation_ease": 1, "rank": 4, "required": true, "default_unit": { "slug": "yes-no", "title": "Yes/No", "system": "enum", "choices": [ { "text": "Yes", "descr": "Yes" }, { "text": "No", "descr": "No" } ] }, "ui_hint": "yes-no-comments", "answers": [], "candidates": [], "planned": [], "nb_respondents": 0, "rate": {}, "opportunity": null } ] }
Freezes a sample
POST /api/{profile}/sample/{sample}/freeze
A frozen sample cannot be edited to add and/or update answers.
Responses
Campaign this sample is part of.
Unique identifier for the sample. It can be used in a URL.
Account this sample belongs to.
Date/time of creation (in ISO format)
Date/time of last update (in ISO format)
When True, answers to that sample cannot be updated.
URL at which the response is visible.
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/supplier-1/sample/0123456789abcdef/freeze{ "slug": "0123456789abcdef", "account": "supplier-1", "created_at": "2020-01-01T00:00:00Z", "is_frozen": true, "campaign": null, "updated_at": "2020-01-01T00:00:00Z" }
Freezes part of sample
POST /api/{profile}/sample/{sample}/freeze/{path}
A frozen sample cannot be edited to add and/or update answers.
Responses
Campaign this sample is part of.
Unique identifier for the sample. It can be used in a URL.
Account this sample belongs to.
Date/time of creation (in ISO format)
Date/time of last update (in ISO format)
When True, answers to that sample cannot be updated.
URL at which the response is visible.
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/supplier-1/sample/0123456789abcdef/freeze/construction{ "slug": "0123456789abcdef", "account": "supplier-1", "created_at": "2020-01-01T00:00:00Z", "is_frozen": true, "campaign": null, "updated_at": "2020-01-01T00:00:00Z" }
Clears answers
POST /api/{profile}/sample/{sample}/reset/{path}
The sample must belong to organization.
path can be used to filter the tree of questions by a prefix.
Responses
Campaign this sample is part of.
Unique identifier for the sample. It can be used in a URL.
Account this sample belongs to.
Date/time of creation (in ISO format)
Date/time of last update (in ISO format)
When True, answers to that sample cannot be updated.
URL at which the response is visible.
Examples
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' https://livedemo.djaoapp.com/api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/reset/construction{ "slug": "46f66f70f5ad41b29c4df08f683a9a7a", "created_at": "2018-01-24T17:03:34.926193Z", "campaign": "sustainability" }
Lists frozen samples
GET /api/{profile}/samples
Returns a list of frozen samples that belong to a profile. Typically this is a list of historical assessments.
Query parameters
A page number within the paginated result set.
Responses
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time an assessment was completed
Unique identifier that can be used in a URL
Account this sample belongs to.
Enter a campaign title.
This description will be displayed to interviewees.
Whether the campaign is available or not
Examples
curl https://livedemo.djaoapp.com/api/andy-shop/samples{ "count": 1, "previous": null, "next": null, "results": [ { "slug": "f1e2e916eb494b90f9ff0a36982340", "last_completed_at": "2016-07-15T00:35:26.565000Z", "campaign": { "slug": "sustainability", "account": "tspproject", "title": "ESG/Environmental practices", "description": "ESG/Environmental practices assessment", "active": true } } ] }