Practice Sharing Platform API Reference

This is the reference documentation for the Practice Sharing 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

Content readers

This section contains APIs related to content readers

Alphabetical

Retrieves attendance to live event

endpoint 
GET /api/attendance/{profile}/{sequence}/{rank}/{user}

Whenever a {user} participated in an live event (i.e. either a video call or an in-person event) for the {rank} element of a training course {sequence} provided by {profile} , the viewing_duration will be equal or greater to the min_viewing_time .

Responses
content
string

Page element the enumerated element is for

rank
integer

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

viewing_duration
string

Time spent by the user on the material (in hh:mm:ss)

Examples 
curl -H 'Authorization: Bearer JWT auth token' /api/attendance/alliance/ghg-accounting-training/1/steve
responds 
{
  "rank": 1,
  "content": "ghg-emissions-scope3-details",
  "viewing_duration": "00:00:00",
  "min_viewing_duration": "00:01:00"
}

Records attendance to a live event

endpoint 
POST /api/attendance/{profile}/{sequence}/{rank}/{user}

Indicates that a user attended a live event, hence fullfilling the requirements for the element of the sequence.

Responses
content
string

Page element the enumerated element is for

rank
integer

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

viewing_duration
string

Time spent by the user on the material (in hh:mm:ss)

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST /api/attendance/alliance/ghg-accounting-training/1/steve
responds 
{
  "rank": 1,
  "content": "ghg-emissions-scope3-details",
  "viewing_duration": "00:00:00",
  "min_viewing_duration": "00:01:00"
}

Resets a user's progress on a sequence

endpoint 
DELETE /api/attendance/{profile}/{sequence}/{user}
Responses

204 No Content

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE /api/attendance/alliance/ghg-accounting-training/steve

Lists tree of page elements

endpoint 
GET /api/content
Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

Examples 
curl /api/content
responds 
{
  "count": 8,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "metal",
      "path": null,
      "title": "Metal structures & equipment",
      "indent": 0
    },
    {
      "slug": "boxes-and-enclosures",
      "path": "/metal/boxes-and-enclosures",
      "title": "Boxes & enclosures",
      "indent": 1,
      "tags": [
        "industry",
        "pagebreak",
        "public",
        "scorecard"
      ]
    }
  ]
}

Lists questions accross all accessible campaigns

endpoint 
GET /api/content/campaigns
Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

Examples 
curl /api/content/campaigns
responds 
{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "path": null,
      "title": "Construction",
      "tags": [
        "public"
      ],
      "indent": 0
    },
    {
      "path": null,
      "title": "Governance & management",
      "picture": "https://assets.tspproject.org/management.png",
      "indent": 1
    },
    {
      "path": "/construction/governance/the-assessment-process-is-rigorous",
      "title": "The assessment process is rigorous",
      "indent": 2
    },
    {
      "path": null,
      "title": "Production",
      "picture": "https://assets.tspproject.org/production.png",
      "indent": 1
    },
    {
      "path": "/construction/production/adjust-air-fuel-ratio",
      "title": "Adjust Air fuel ratio",
      "indent": 2
    }
  ]
}

Lists questions in a campaign

endpoint 
GET /api/content/campaigns/{campaign}
Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

Examples 
curl /api/content/campaigns/sustainability
responds 
{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "path": null,
      "title": "Construction",
      "tags": [
        "public"
      ],
      "indent": 0
    },
    {
      "path": null,
      "title": "Governance & management",
      "picture": "https://assets.tspproject.org/management.png",
      "indent": 1
    },
    {
      "path": "/construction/governance/the-assessment-process-is-rigorous",
      "title": "The assessment process is rigorous",
      "indent": 2
    },
    {
      "path": null,
      "title": "Production",
      "picture": "https://assets.tspproject.org/production.png",
      "indent": 1
    },
    {
      "path": "/construction/production/adjust-air-fuel-ratio",
      "title": "Adjust Air fuel ratio",
      "indent": 2
    }
  ]
}

Lists comments on a page element

endpoint 
GET /api/content/comments/{path}
Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

text
string

Long description of the page element

created_at
string

Date/time the comment was submitted (in ISO format)

user
string

Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.

Examples 
curl /api/content/comments/adjust-air-fuel-ratio
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2020-09-28T00:00:00.0000Z",
      "user": "steve",
      "text": "How long does it take to see improvements?"
    }
  ]
}

Comments on a page element

endpoint 
POST /api/content/comments/{path}
Request body
text
string

Long description of the page element

Responses
text
string

Long description of the page element

created_at
string

Date/time the comment was submitted (in ISO format)

user
string

Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"text": "How long does it take to see improvements?"}' /api/content/comments/adjust-air-fuel-ratio
responds 
{
  "created_at": "2020-09-28T00:00:00.0000Z",
  "user": "steve",
  "text": "How long does it take to see improvements?"
}

Retrieves a page element

endpoint 
GET /api/content/detail/{path}
Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/content/detail/adjust-air-fuel-ratio
responds 
{
  "slug": "adjust-air-fuel-ratio",
  "picture": null,
  "title": "Adjust air/fuel ratio",
  "text": "<h2>Background</h2><p>Some manufacturing processes may involve heating operations.</p>",
  "extra": null
}

Downvotes a page element

endpoint 
POST /api/content/downvote/{path}

The authenticated user making the request indicates the practice is not worth implementing.

Request body
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/content/downvote/adjust-air-fuel-ratio
responds 
{
  "slug": "water-user",
  "title": "How to reduce water usage?"
}

Follows a page element

endpoint 
POST /api/content/follow/{path}

The authenticated user making the request will receive notification whenever someone comments on the practice.

Request body
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/content/follow/adjust-air-fuel-ratio
responds 
{
  "slug": "water-user",
  "title": "How to reduce water usage?"
}

Searches page elements

endpoint 
GET /api/content/search

Returns a list of page elements whose title matches a search criteria.

Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/content/search
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "hello",
      "path": "/hello",
      "title": "Hello"
    }
  ]
}

Lists available sequences

endpoint 
GET /api/content/sequences

Returns a list of page_size sequences available to the request user.

The queryset can be further refined to match a search filter ( q ) and sorted on specific fields ( o ).

Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

created_at
string

Date/time the sequence was created (in ISO format)

slug
string

Unique identifier that can be used in URL paths

title
string

Title of the sequence

account
string

Account that can edit the sequence

has_certificate
boolean

True when the sequence ends with a certificate of completion

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/content/sequences
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2024-01-01T00:00:00.0000Z",
      "slug": "ghg-accounting-webinar",
      "title": "GHG Accounting Training",
      "account": "djaopsp",
      "has_certificate": true
    }
  ]
}

Unfollows a page element

endpoint 
POST /api/content/unfollow/{path}

The authenticated user making the request will stop receiving notification whenever someone comments on the practice.

Request body
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/content/unfollow/adjust-air-fuel-ratio
responds 
{
  "slug": "water-user",
  "title": "How to reduce water usage?"
}

Upvotes a page element

endpoint 
POST /api/content/upvote/{path}

The authenticated user making the request indicates the practice is considered worthwhile implementing.

Request body
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/content/upvote/adjust-air-fuel-ratio
responds 
{
  "slug": "water-user",
  "title": "How to reduce water usage?"
}

Lists tree of page elements matching prefix

endpoint 
GET /api/content/{path}
Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

Examples 
curl /api/content/boxes-and-enclosures
responds 
{
  "count": 8,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "metal",
      "path": null,
      "title": "Metal structures & equipment",
      "indent": 0
    },
    {
      "slug": "boxes-and-enclosures",
      "path": "/metal/boxes-and-enclosures",
      "title": "Boxes & enclosures",
      "indent": 1,
      "tags": [
        "industry",
        "pagebreak",
        "public",
        "scorecard"
      ]
    }
  ]
}

Retrieves relevant news for a user

endpoint 
GET /api/content/{user}/newsfeed
Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

descr
string

first paragraph of HTML-formatted content

grantees
array

Profiles that made the request for a response to the questionnaire

created_at
string

Date at which the request was created

grantee
string

The profile that initiated the request

ends_at
string

Date before which the questionnaire should be answered

last_completed_at
string

Last time the questionnaire was completed

respondents
array

Users that previously responded to the questionnaire

share_url
string

URL to share the latest response

update_url
string

URL to answer the questionnaire

external_url
string

URL to external information

Examples 
curl -H 'Authorization: Bearer JWT auth token' /api/content/steve/newsfeed
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "path": "/metal/boxes-and-enclosures/production/energy-efficiency/process-heating/combustion/adjust-air-fuel-ratio",
      "text_updated_at": "2024-01-01T00:00:00Z",
      "last_read_at": "2023-12-01T00:00:00Z",
      "nb_comments_since_last_read": 5,
      "descr": ""
    }
  ]
}

Lists editable campaigns

endpoint 
GET /api/editables/{profile}/campaigns

Lists campaigns that belongs to a profile.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

Examples 
curl /api/alliance/campaigns
responds 
{
  "count": 1,
  "results": [
    {
      "slug": "construction",
      "account": "alliance",
      "title": "Assessment on sustainable construction practices",
      "is_active": true,
      "is_commons": true
    }
  ]
}

Creates a campaign

endpoint 
POST /api/editables/{profile}/campaigns

Creates a campaign against which profiles can be assessed.

Request body
title
string required

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

quizz_mode
boolean

If checked, correct answser are required

questions
array

title
string required

Title of the question as displayed in user interfaces

text
string

Long form description about the question

default_unit
string

Default unit for measured field when none is specified

extra
string

Extra meta data (can be stringify JSON)

required
boolean

Whether an answer is required or not when the question is part of a campaign

Responses
slug
string

Unique identifier that can be used in a URL

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

quizz_mode
boolean

If checked, correct answser are required

questions
array

title
string

Title of the question as displayed in user interfaces

text
string

Long form description about the question

default_unit
string

Default unit for measured field when none is specified

extra
string

Extra meta data (can be stringify JSON)

path
string

Unique identifier that can be used in URL

required
boolean

Whether an answer is required or not when the question is part of a campaign

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Sustainable construction practices"}' /api/alliance/campaigns
responds 
{
  "slug": "sustainable-construction-practices",
  "title": "Sustainable construction practices"
}

Lists questions in an editable campaign

endpoint 
GET /api/editables/{profile}/campaigns/{campaign}
Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

Examples 
curl /api/editables/djaopsp/campaigns/sustainability
responds 
{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "path": null,
      "title": "Construction",
      "tags": [
        "public"
      ],
      "indent": 0
    },
    {
      "path": null,
      "title": "Governance & management",
      "picture": "https://assets.tspproject.org/management.png",
      "indent": 1
    },
    {
      "path": "/construction/governance/the-assessment    -process-is-rigorous",
      "title": "The assessment process is rigorous",
      "indent": 2
    },
    {
      "path": null,
      "title": "Production",
      "picture": "https://assets.tspproject.org/production.png",
      "indent": 1
    },
    {
      "path": "/construction/production/adjust-air-fuel    -ratio",
      "title": "Adjust Air fuel ratio",
      "indent": 2
    }
  ]
}

Creates a question

endpoint 
POST /api/editables/{profile}/campaigns/{campaign}

Updates the title, text and, if applicable, the metrics associated associated to the content element referenced by path .

Request body
title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

url
string

Location of the text description for the practice

segments
array

parents
array required

slug
string

title
string

Responses
slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

parents
array

slug
string

title
string

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Adjust air/fuel ratio", "parents": []}' /api/editables/alliance/campaigns/sustainability
responds 
{
  "title": "Adjust air/fuel ratio",
  "parents": []
}

Deletes a campaign

endpoint 
DELETE /api/editables/{profile}/campaigns/{campaign}

Removes a Campaign and all associated Sample . The underlying Answer that were grouped in a Sample remain present in the database. These Answer are just no longer grouped logically in a Sample .

Responses

204 No Content

Examples 
curl -X DELETE /api/alliance/campaign/sustainability

Lists segments in a campaign

endpoint 
GET /api/editables/{profile}/campaigns/{campaign}/segments
Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

Examples 
curl /api/editables/alliance/campaigns/sustainability/segments
responds 
{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "path": null,
      "title": "Construction",
      "tags": [
        "public"
      ],
      "indent": 0
    },
    {
      "path": null,
      "title": "Governance & management",
      "picture": "https://assets.tspproject.org/management.png",
      "indent": 1
    },
    {
      "path": "/construction/governance/the-assessment    -process-is-rigorous",
      "title": "The assessment process is rigorous",
      "indent": 2
    },
    {
      "path": null,
      "title": "Production",
      "picture": "https://assets.tspproject.org/production.png",
      "indent": 1
    },
    {
      "path": "/construction/production/adjust-air-fuel    -ratio",
      "title": "Adjust Air fuel ratio",
      "indent": 2
    }
  ]
}

Creates a segment in a campaign

endpoint 
POST /api/editables/{profile}/campaigns/{campaign}/segments
Request body
title
string required

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Boxes enclosures"}' /api/editables/alliance/campaigns/sustainability/segments
responds 
{
  "slug": "boxes-enclosures",
  "title": "Boxes enclosures"
}

Retrieves an editable question

endpoint 
GET /api/editables/{profile}/campaigns/{campaign}/{path}

Retrieves title , text and default_unit of a question.

Responses
title
string

Title of the question as displayed in user interfaces

text
string

Long form description about the question

default_unit
string

Default unit for measured field when none is specified

extra
string

Extra meta data (can be stringify JSON)

path
string

Unique identifier that can be used in URL

Examples 
curl /api/editables/djaopsp/campaigns/sustainability/construction/governance/the-assessment-process-is-rigorous
responds 
{
  "path": "/construction/governance/the-assessment-process-is-rigorous",
  "title": "The assessment process is rigorous",
  "default_unit": "assessment"
}

Creates a question under a prefix

endpoint 
POST /api/editables/{profile}/campaigns/{campaign}/{path}

Creates a new question under prefix path .

Request body
title
string required

Title of the question as displayed in user interfaces

text
string

Long form description about the question

default_unit
string

Default unit for measured field when none is specified

extra
string

Extra meta data (can be stringify JSON)

required
boolean

Whether an answer is required or not when the question is part of a campaign

Responses
title
string

Title of the question as displayed in user interfaces

text
string

Long form description about the question

default_unit
string

Default unit for measured field when none is specified

extra
string

Extra meta data (can be stringify JSON)

path
string

Unique identifier that can be used in URL

required
boolean

Whether an answer is required or not when the question is part of a campaign

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "The assessment process is rigorous"}' /api/editables/alliance/campaigns/sustainability/construction/governance
responds 
{
  "path": "/construction/governance/the-assessment-process-is-rigorous",
  "title": "The assessment process is rigorous",
  "default_unit": "assessment"
}

Updates a question

endpoint 
PUT /api/editables/{profile}/campaigns/{campaign}/{path}

Updates the title, text and, if applicable, the metrics associated associated to the content element referenced by path .

Request body
title
string

Title of the question as displayed in user interfaces

text
string

Long form description about the question

default_unit
string

Default unit for measured field when none is specified

extra
string

Extra meta data (can be stringify JSON)

required
boolean

Whether an answer is required or not when the question is part of a campaign

Responses
title
string

Title of the question as displayed in user interfaces

text
string

Long form description about the question

default_unit
string

Default unit for measured field when none is specified

extra
string

Extra meta data (can be stringify JSON)

path
string

Unique identifier that can be used in URL

required
boolean

Whether an answer is required or not when the question is part of a campaign

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Adjust air/fuel ratio"}' /api/editables/alliance/campaigns/sustainability
responds 
{
  "path": "/construction/governance/the-assessment-process-is-rigorous",
  "title": "The assessment process is rigorous",
  "default_unit": "assessment"
}

Deletes a subset of questions

endpoint 
DELETE /api/editables/{profile}/campaigns/{campaign}/{path}

Deletes all questions under prefix path .

Responses

204 No Content

Examples 
curl -X DELETE /api/editables/alliance/campaigns/sustainability/construction

Lists editable page elements

endpoint 
GET /api/editables/{profile}/content

This API endpoint lists page elements that are owned and thus editable by an account.

Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/editables/alliance/content
responds 
{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "path": null,
      "title": "Construction",
      "tags": [
        "public"
      ],
      "indent": 0
    },
    {
      "path": null,
      "title": "Governance & management",
      "picture": "https://assets.tspproject.org/management.png",
      "indent": 1
    },
    {
      "path": "/construction/governance/the-assessment-process-is-rigorous",
      "title": "The assessment process is rigorous",
      "indent": 2,
      "extra": {
        "intrinsic_values": {
          "environmental_value": 1,
          "business_value": 1,
          "profitability": 1,
          "implementation_ease": 1,
          "avg_value": 1
        }
      }
    },
    {
      "path": null,
      "title": "Production",
      "picture": "https://assets.tspproject.org/production.png",
      "indent": 1
    },
    {
      "path": "/construction/production/adjust-air-fuel-ratio",
      "title": "Adjust Air fuel ratio",
      "indent": 2,
      "extra": {
        "intrinsic_values": {
          "environmental_value": 2,
          "business_value": 2,
          "profitability": 2,
          "implementation_ease": 2,
          "avg_value": 2
        }
      }
    }
  ]
}

Creates a page element

endpoint 
POST /api/editables/{profile}/content
Request body
title
string required

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Boxes enclosures"}' /api/editables/alliance/content
responds 
{
  "slug": "boxes-enclosures",
  "title": "Boxes enclosures"
}

Retrieves an editable page element

endpoint 
GET /api/editables/{profile}/content/{path}
Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/editables/alliance/content/boxes-enclosures
responds 
{
  "slug": "boxes-enclosures",
  "path": "/boxes-enclosures",
  "text": "Hello"
}

Creates a page element under a prefix

endpoint 
POST /api/editables/{profile}/content/{path}
Request body
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Boxes enclosures"}' /api/editables/alliance/content/boxes-enclosures
responds 
{
  "slug": "boxes-enclosures",
  "text": "Hello"
}

Updates a page element

endpoint 
PUT /api/editables/{profile}/content/{path}
Request body
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

Responses
slug
string

Unique identifier that can be used in URL paths

picture
string

Picture icon that can be displayed alongside the title

title
string

Title of the page element

content_format
string

Format of the content, HTML or MD

text_updated_at
string

Last updated at date for the text field

reading_time
string

Reading time of the material (in hh:mm:ss)

lang
string

Language the material is written in

account
string

Account that can edit the page element

extra
string

Extra meta data (can be stringify JSON)

nb_upvotes
integer

Number of times the content has been upvoted

nb_followers
integer

Number of followers notified when content is updated

upvote
string

Set to true when the request user upvoted the content

follow
string

Set to true when the request user follows the content

last_read_at
string

Last time the PageElement was read

nb_comments_since_last_read
string

Number of comments since last read

path
string

path from the root of content tree

text
string

Long description of the page element

html_formatted
string

Text field formatted as HTML

count
integer

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Boxes and enclosures"}' /api/editables/alliance/content/boxes-enclosures
responds 
{
  "slug": "boxes-enclosures",
  "text": "Hello"
}

Deletes a page element

endpoint 
DELETE /api/editables/{profile}/content/{path}
Responses

204 No Content

Examples 
curl -X DELETE /api/editables/alliance/content/boxes-enclosures

Lists editable sequences

endpoint 
GET /api/editables/{profile}/sequences

Returns a list of page_size sequences editable by profile.

The queryset can be further refined to match a search filter ( q ) and sorted on specific fields ( o ).

Query parameters
o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

q
string

A search term.

Responses
count
integer

next
string

previous
string

results
array

created_at
string

Date/time the sequence was created (in ISO format)

slug
string

Unique identifier that can be used in URL paths

title
string

Title of the sequence

account
string

Account that can edit the sequence

has_certificate
boolean

True when the sequence ends with a certificate of completion

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/editables/alliance/sequences
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2020-09-28T00:00:00.0000Z",
      "slug": "ghg-accounting-webinar",
      "title": "GHG Accounting Training",
      "account": "djaopsp",
      "has_certificate": true
    }
  ]
}

Creates a sequence

endpoint 
POST /api/editables/{profile}/sequences

Creates a new sequence editable by profile.

Request body
slug
string

Unique identifier for the sequence

title
string required

Title of the sequence

has_certificate
boolean

True when the sequence ends with a certificate of completion

extra
string

Extra meta data (can be stringify JSON)

Responses
created_at
string

Date/time the sequence was created (in ISO format)

slug
string

Unique identifier for the sequence

title
string

Title of the sequence

account
string

Account that can edit the sequence

has_certificate
boolean

True when the sequence ends with a certificate of completion

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"slug": "ghg-accounting-webinar", "title": "GHG Accounting Training"}' /api/editables/alliance/sequences
responds 
{
  "created_at": "2023-01-01T04:00:00.000000Z",
  "slug": "ghg-accounting-webinar",
  "title": "GHG Accounting Training",
  "account": null,
  "has_certificate": true
}

Retrieves a sequence

endpoint 
GET /api/editables/{profile}/sequences/{sequence}
Responses
created_at
string

Date/time the sequence was created (in ISO format)

slug
string

Unique identifier that can be used in URL paths

title
string

Title of the sequence

account
string

Account that can edit the sequence

has_certificate
boolean

True when the sequence ends with a certificate of completion

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/editables/alliance/sequences/ghg-accounting-webinar
responds 
{
  "created_at": "2023-12-29T04:33:33.078661Z",
  "slug": "ghg-accounting-webinar",
  "title": "GHG Accounting Training",
  "account": null,
  "has_certificate": true
}

Updates a sequence

endpoint 
PUT /api/editables/{profile}/sequences/{sequence}
Request body
slug
string

Unique identifier for the sequence

title
string

Title of the sequence

has_certificate
boolean

True when the sequence ends with a certificate of completion

extra
string

Extra meta data (can be stringify JSON)

Responses
created_at
string

Date/time the sequence was created (in ISO format)

slug
string

Unique identifier for the sequence

title
string

Title of the sequence

account
string

Account that can edit the sequence

has_certificate
boolean

True when the sequence ends with a certificate of completion

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Updated GHG Accounting Training Title", "has_certificate": false, "extra": "Additional info"}' /api/editables/alliance/sequences/ghg-accounting-webinar
responds 
{
  "created_at": "2023-12-29T04:33:33.078661Z",
  "slug": "ghg-accounting-webinar",
  "title": "Updated GHG Accounting Training Title",
  "account": null,
  "has_certificate": false,
  "extra": "Additional info"
}

Deletes a sequence

endpoint 
DELETE /api/editables/{profile}/sequences/{sequence}
Responses

204 No Content

Examples 
curl -X DELETE /api/editables/alliance/sequences/ghg-accounting-webinar

Lists page elements in a sequence

endpoint 
GET /api/editables/{profile}/sequences/{sequence}/elements
Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

content
string

Page element the enumerated element is for

rank
integer

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

Examples 
curl /api/editables/alliance/sequences/ghg-accounting-webinar/elements
responds 
{
  "previous": null,
  "next": null,
  "count": 2,
  "results": [
    {
      "rank": 1,
      "content": "text-content",
      "min_viewing_duration": "00:00:10"
    },
    {
      "rank": 2,
      "content": "survey-event",
      "min_viewing_duration": "00:00:20"
    }
  ]
}

Inserts a page element in a sequence

endpoint 
POST /api/editables/{profile}/sequences/{sequence}/elements
Request body
content
string required

Page element the enumerated element is for

rank
integer required

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

Responses
content
string

Page element the enumerated element is for

rank
integer

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"content": "production", "rank": 10}' /api/editables/alliance/sequences/ghg-accounting-webinar/elements
responds 
{
  "rank": 1,
  "content": "text-content",
  "min_viewing_duration": "00:00:00"
}

Removes a page element from a sequence

endpoint 
DELETE /api/editables/{profile}/sequences/{sequence}/elements/{rank}
Responses

204 No Content

Examples 
curl -X DELETE /api/editables/alliance/sequences/ghg-accounting-webinar/elements/1

Lists progress on a sequence

endpoint 
GET /api/progress/{user}/{sequence}
Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

content
string

Page element the enumerated element is for

rank
integer

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

viewing_duration
string

Time spent by the user on the material (in hh:mm:ss)

Examples 
curl /api/progress/steve/ghg-accounting-training
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "rank": 1,
      "content": "ghg-emissions-scope3-details",
      "viewing_duration": "00:00:00"
    }
  ]
}

Retrieves viewing duration for an element

endpoint 
GET /api/progress/{user}/{sequence}/{rank}

Retrieves how long {user} was engaged with the element {rank} of the training course {sequence} .

Responses
content
string

Page element the enumerated element is for

rank
integer

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

viewing_duration
string

Time spent by the user on the material (in hh:mm:ss)

Examples 
curl /api/progress/steve/ghg-accounting-training/1
responds 
{
  "rank": 1,
  "content": "metal",
  "viewing_duration": "00:00:00"
}

Updates viewing duration for an element

endpoint 
POST /api/progress/{user}/{sequence}/{rank}

A {user} can update the viewing duration for an element {rank} of a training course {sequence} by regularling pinging the server with this API call.

Responses
content
string

Page element the enumerated element is for

rank
integer

Used to order elements when presenting a sequence

min_viewing_duration
string

Minimum viewing time of the material (in hh:mm:ss)

certificate
boolean

Field to indicate if the PageElement being added to the Sequence is a Certificate

viewing_duration
string

Time spent by the user on the material (in hh:mm:ss)

Examples 
curl -X POST /api/progress/steve/ghg-accounting-training/1
responds 
{
  "rank": 1,
  "content": "metal",
  "viewing_duration": "00:00:56.000000"
}

Lists profiles with a frozen response

endpoint 
GET /api/respondents

Returns page_size profiles with a frozen response

Query parameters
o
string

sort by printable_name, created_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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: full_name, email. searches all fields when unspecified.

Responses
count
integer

next
string

previous
string

results
array

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

Examples 
curl /api/respondents
responds 
{
  "count": 4,
  "results": [
    {
      "picture": null,
      "printable_name": "S1"
    },
    {
      "picture": null,
      "printable_name": "S2"
    },
    {
      "picture": null,
      "printable_name": "S3"
    },
    {
      "picture": null,
      "printable_name": "S4"
    }
  ]
}

Lists units

endpoint 
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
eq
string

units that can be used intercheably with this one

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug. searches all fields when unspecified.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

Examples 
curl /api/units
responds 
{
  "count": 1,
  "previous": null,
  "next": null,
  "results": [
    {
      "slug": "assessment",
      "title": "assessments",
      "system": "enum"
    }
  ]
}

Retrieves a unit

endpoint 
GET /api/units/{unit}

Retrieves the details of a Unit .

Responses
slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

choices
string

equivalences
array

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

Examples 
curl /api/units/assessment
responds 
{
  "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 enumerated choices for a unit

endpoint 
GET /api/units/{unit}/choices

Retrieves choices of a Unit with an enum system. The results can be filtered by a search criteria.

Query parameters
q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: text, descr. searches all fields when unspecified.

Responses
slug
string

title
string

system
string

results
array

text
string

short name for the enumerated value (as used in source code)

descr
string

long form description of the enumerated value (for help tooltips)

Examples 
curl /api/units/assessment/search?q=yes
responds 
{
  "slug": "assessment",
  "title": "assessments",
  "system": "enum",
  "results": [
    {
      "rank": 1,
      "text": "mostly-yes",
      "descr": "Mostly yes"
    },
    {
      "rank": 2,
      "text": "yes",
      "descr": "Yes"
    }
  ]
}

Benchmarks against accessible profiles

endpoint 
GET /api/{profile}/benchmarks/accessibles

Returns a list of questions decorated with a 'benchmarks' field that contains aggregated statistics accross the set of profiles accessible to a grantee {profile} .

The set of profiles whose responses are taken into account in the aggregate can be reduced to a subset of profiles accessbile in the time period [accounts_start_at, accounts_ends_at[.

Aggregation can be done for samples created in the time period [start_at, ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
accounts_ends_at
string

end of the range as a date/time in ISO 8601 format

accounts_start_at
string

start of the range as a date/time in ISO 8601 format

ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

unit
string

Unit to return values in

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/accessibles
responds 
{
  "title": "Accessibles",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 1,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "accessibles",
          "title": "Accessibles",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              {
                "Yes": 1
              }
            ]
          ]
        }
      ]
    }
  ]
}

Benchmarks against accessible profiles for a subset of questions

endpoint 
GET /api/{profile}/benchmarks/accessibles/{path}

Returns a list of questions whose path is prefixed by {path} , decorated with a 'benchmarks' field that contains aggregated statistics accross the set of profiles accessible to a grantee profile .

The set of profiles whose responses are taken into account in the aggregate can be reduced to a subset of profiles accessbile in the time period [accounts_start_at, accounts_ends_at[.

Aggregation can be done for samples created in the time period [start_at,ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
accounts_ends_at
string

end of the range as a date/time in ISO 8601 format

accounts_start_at
string

start of the range as a date/time in ISO 8601 format

ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

unit
string

Unit to return values in

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/accessibles/sustainability/esg-strategy-heading/formalized-esg-strategy
responds 
{
  "title": "Accessibles",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 1,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "accessibles",
          "title": "Accessibles",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              {
                "Yes": 1
              }
            ]
          ]
        }
      ]
    }
  ]
}

Benchmarks against all profiles

endpoint 
GET /api/{profile}/benchmarks/all

Returns a list of questions decorated with a 'benchmarks' field that contains aggregated statistics accross the set of all profiles on the platform.

Aggregation can be done for samples created in the time period [start_at,ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/all
responds 
{
  "title": "All",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 2,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "all",
          "title": "All",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              [
                "Yes",
                1
              ]
            ]
          ]
        }
      ]
    },
    {
      "path": "/sustainability/esg-strategy-heading/esg-point-person",
      "title": "1.1 Does your company have a ESG point person?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "all",
          "title": "All",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              [
                "Yes",
                1
              ]
            ]
          ]
        }
      ]
    }
  ]
}

Benchmarks against all profiles for a subset of questions

endpoint 
GET /api/{profile}/benchmarks/all/{path}

Returns a list of questions decorated with a 'benchmarks' field that contains aggregated statistics accross the set of all profiles on the platform.

Aggregation can be done for samples created in the time period [start_at,ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/all/sustainability/esg-strategy-heading/formalized-esg-strategy
responds 
{
  "title": "All",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 1,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "all",
          "title": "All",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              [
                "Yes",
                1
              ]
            ]
          ]
        }
      ]
    }
  ]
}

Benchmarks against engaged profiles

endpoint 
GET /api/{profile}/benchmarks/engaged

Returns a list of questions decorated with a 'benchmarks' field that contains aggregated statistics accross the set of profiles engaged by a profile .

The set of profiles whose responses are taken into account in the aggregate can be reduced to a subset of profiles engaged in the time period [accounts_start_at, accounts_ends_at[.

Aggregation can be done for samples created in the time period [start_at,ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
accounts_ends_at
string

end of the range as a date/time in ISO 8601 format

accounts_start_at
string

start of the range as a date/time in ISO 8601 format

ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

unit
string

Unit to return values in

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/engaged
responds 
{
  "title": "Engaged",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 1,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "engaged",
          "title": "Engaged",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              {
                "Yes": 1
              }
            ]
          ]
        }
      ]
    }
  ]
}

Benchmarks against engaged profiles for a subset of questions

endpoint 
GET /api/{profile}/benchmarks/engaged/{path}

Returns a list of questions whose path is prefixed by {path} , decorated with a 'benchmarks' field that contains aggregated statistics accross the set of profiles engaged by a profile .

The set of profiles whose responses are taken into account in the aggregate can be reduced to a subset of profiles engaged in the time period [accounts_start_at, accounts_ends_at[.

Aggregation can be done for samples created in the time period [start_at,ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
accounts_ends_at
string

end of the range as a date/time in ISO 8601 format

accounts_start_at
string

start of the range as a date/time in ISO 8601 format

ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

unit
string

Unit to return values in

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/engaged/sustainability/esg-strategy-heading/formalized-esg-strategy
responds 
{
  "title": "Engaged",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 1,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "engaged",
          "title": "Engaged",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              {
                "Yes": 1
              }
            ]
          ]
        }
      ]
    }
  ]
}

Benchmarks against selected profiles

endpoint 
GET /api/{profile}/benchmarks/{editable_filter}

Returns a list of questions decorated with a 'benchmarks' field that contains aggregated statistics accross the set of profiles selected by the {editable_filter} filter.

The set of profiles whose responses are taken into account in the aggregate can be reduced to a subset of profiles created in the time period [accounts_start_at, accounts_ends_at[.

Aggregation can be done for samples created in the time period [start_at,ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
accounts_ends_at
string

end of the range as a date/time in ISO 8601 format

accounts_start_at
string

start of the range as a date/time in ISO 8601 format

ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

unit
string

Unit to return values in

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/tier1-suppliers
responds 
{
  "title": "Tier1 suppliers",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 1,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "tier1-suppliers",
          "title": "Tier1 suppliers",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              {
                "Yes": 1
              }
            ]
          ]
        }
      ]
    }
  ]
}

Benchmarks against selected profiles for a subset of questions

endpoint 
GET /api/{profile}/benchmarks/{editable_filter}/{path}

Returns a list of questions whose path is prefixed by {path} , decorated with a 'benchmarks' field that contains aggregated statistics accross the set of profiles selected by the {editable_filter} filter.

The set of profiles whose responses are taken into account in the aggregate can be reduced to a subset of profiles created in the time period [accounts_start_at, accounts_ends_at[.

Aggregation can be done for samples created in the time period [start_at,ends_at[, either as a whole period, or as period trenches ( yearly , monthly ).

When period_type is specified, nb_periods and ends_at can be used instead of start_at to filter the samples.

Query parameters
accounts_ends_at
string

end of the range as a date/time in ISO 8601 format

accounts_start_at
string

start of the range as a date/time in ISO 8601 format

ends_at
string

date/time in ISO 8601 format

nb_periods
integer

number of periods

period_type
string

aggregate period (yearly or monthly)

start_at
string

date/time in ISO 8601 format

unit
string

Unit to return values in

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/benchmarks/tier1-suppliers/sustainabilityesg-strategy-heading/formalized-esg-strategy
responds 
{
  "title": "Tier1 suppliers",
  "unit": "profiles",
  "scale": 1,
  "labels": null,
  "count": 1,
  "results": [
    {
      "path": "/sustainability/esg-strategy-heading/formalized-esg-strategy",
      "title": "1.1 Does your company have a formalized ESG strategy?",
      "default_unit": {
        "slug": "yes-no",
        "title": "Yes/No",
        "system": "enum",
        "choices": []
      },
      "benchmarks": [
        {
          "slug": "tier1-suppliers",
          "title": "Tier1 suppliers",
          "values": [
            [
              "2018-01-01T00:00:00Z",
              {
                "Yes": 1
              }
            ]
          ]
        }
      ]
    }
  ]
}

Lists groups of profiles

endpoint 
GET /api/{profile}/filters/accounts

Returns a list of page_size groups that belong to {profile} .

The queryset can be further refined to match a search filter ( q ) and sorted on specific fields ( o ).

Query parameters
o
string

sort by . 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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, title. searches all fields when unspecified.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier for the group that can be used in a URL

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/energy-utility/filters/accounts
responds 
{
  "count": 1,
  "previous": null,
  "next": null,
  "results": [
    {
      "slug": "supplier-1",
      "title": "Supplier 1",
      "extra": null
    }
  ]
}

Creates a group of profiles

endpoint 
POST /api/{profile}/filters/accounts

After the group is created, nomminative profiles or select-profiles-by-answer filters can be added to it through Adds a profile to a group endpoint.

Request body
slug
string

title
string required

Title for the group

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Supplier 1"}' /api/energy-utility/filters/accounts
responds 
{
  "slug": "supplier-1",
  "title": "Supplier 1"
}

Lists quantitative measurements

endpoint 
GET /api/{profile}/filters/accounts/values

Returns a list of page_size data points that were previously entered in the platform through the Records quantitative measurements API call.

Query parameters
ends_at
string

date/time in ISO 8601 format

page
integer

A page number within the paginated result set.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

next
string

previous
string

results
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

account
string

Account this sample belongs to.

Examples 
curl /api/supplier-1/filters/accounts/values
responds 
{
  "count": 0,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2020-01-01T00:00:00Z",
      "measured": 12,
      "unit": "t"
    }
  ]
}

Lists profiles in a group

endpoint 
GET /api/{profile}/filters/accounts/{editable_filter}

Returns a list of page_size nomminative profiles and select-profiles-by-answer filters that form the group.

{profile} must be the owner of the {editable_filter} .

Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier for the profile

full_name
string

Human readable name for the profile

path
string

Path for the question used to filter profiles

measured
string

Answer to the question used to filter profiles

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/energy-utility/filters/accounts/suppliers
responds 
{
  "count": 1,
  "results": [
    {
      "facility": "Main factory",
      "fuel_type": "natural-gas",
      "allocation": "Energy utility",
      "created_at": null,
      "ends_at": null,
      "amount": 100,
      "unit": "mmbtu"
    }
  ]
}

Adds a profile to a group

endpoint 
POST /api/{profile}/filters/accounts/{editable_filter}

Either full_name (optionally slug ) or a pair ( question , measured ) must be specified.

When a full_name / slug is specified, the associated nomminative profile will be added to the group.

When a ( question , measured ) pair is specified, a select-profiles-by-answer filter will be used to add all profiles that answered measured to a question to the group.

{profile} must be the owner of the {editable_filter} .

Request body
slug
string

Unique identifier for the profile

full_name
string

Human readable name for the profile

path
string

Path for the question used to filter profiles

measured
string

Answer to the question used to filter profiles

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

Unique identifier for the profile

full_name
string

Human readable name for the profile

path
string

Path for the question used to filter profiles

measured
string

Answer to the question used to filter profiles

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"full_name": "Main"}' /api/energy-utility/filters/accounts/suppliers
responds 
{
  "slug": "main",
  "full_name": "Main"
}

Renames a group of profiles

endpoint 
PUT /api/{profile}/filters/accounts/{editable_filter}

Updates the name of a group of profiles.

{profile} must be the owner of the {editable_filter} .

Request body
slug
string

title
string required

Title for the group

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Energy utility suppliers"}' /api/energy-utility/filters/accounts/suppliers
responds 
{
  "slug": "suppliers",
  "title": "Energy utility suppliers",
  "extra": null
}

Deletes a group of profiles

endpoint 
DELETE /api/{profile}/filters/accounts/{editable_filter}

{profile} must be the owner of the {editable_filter} .

Responses

204 No Content

Examples 
curl -X DELETE /api/energy-utility/filters/accounts/suppliers

Lists quantitative measurements for a group

endpoint 
GET /api/{profile}/filters/accounts/{editable_filter}/values

Returns a list of page_size data points for a group {editable_filter}} that were previously entered in the platform through the Records quantitative measurements API call.

Query parameters
ends_at
string

date/time in ISO 8601 format

page
integer

A page number within the paginated result set.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

next
string

previous
string

results
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

account
string

Account this sample belongs to.

Examples 
curl /api/supplier-1/filters/accounts/ghg-emissions/values
responds 
{
  "count": 0,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2020-01-01T00:00:00Z",
      "measured": 12,
      "unit": "t"
    }
  ]
}

Records quantitative measurements

endpoint 
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
baseline_at
string

created_at
string required

items
array required

unit
string required

Unit the measured field is in

measured
string required

measurement in unit

created_at
string

Date/time of creation (in ISO format)

account
string required

Account this sample belongs to.

Responses
baseline_at
string

created_at
string

items
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

account
string

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": "t"}]}' /api/supplier-1/filters/accounts/ghg-emissions/values
responds 
{
  "created_at": "2020-01-01T00:00:00Z",
  "items": [
    {
      "slug": "main-factory",
      "measured": 12,
      "unit": "t"
    }
  ]
}

Retrieves a selector in a group

endpoint 
GET /api/{profile}/filters/accounts/{editable_filter}/{rank}

Returns the nominative profile or select-profiles-by-answer filter at index {rank} in the group {editable_filter} .

{profile} must be the owner of the {editable_filter} .

Responses
slug
string

Unique identifier for the profile

full_name
string

Human readable name for the profile

path
string

Path for the question used to filter profiles

measured
string

Answer to the question used to filter profiles

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/energy-utility/filters/accounts/suppliers/1
responds 
{
  "slug": "main-factory",
  "full_name": "Main factory"
}

Updates a selector in a group

endpoint 
PUT /api/{profile}/filters/accounts/{editable_filter}/{rank}

Updates the selector at {rank} in the group {editable_filter} , and returns the updated nominative profile or select-profiles-by-answer filter.

{profile} must be the owner of the {editable_filter} .

Request body
slug
string

Unique identifier for the profile

full_name
string

Human readable name for the profile

path
string

Path for the question used to filter profiles

measured
string

Answer to the question used to filter profiles

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

Unique identifier for the profile

full_name
string

Human readable name for the profile

path
string

Path for the question used to filter profiles

measured
string

Answer to the question used to filter profiles

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"full_name": "Main factory"}' /api/energy-utility/filters/accounts/suppliers/1
responds 
{
  "slug": "main-factory",
  "full_name": "Main factory"
}

Removes a selector from a group

endpoint 
DELETE /api/{profile}/filters/accounts/{editable_filter}/{rank}

Upon successful completion, the nomminative profile, or select-profiles-by-answer filter, at index {rank} will no longer be present in the group {editable_filter} .

{profile} must be the owner of the {editable_filter} .

Responses

204 No Content

Examples 
curl -X DELETE /api/energy-utility/filters/accounts/suppliers/1

Retrieves aggregated quantitative measurements over a time period

endpoint 
GET /api/{profile}/metrics/aggregate/{path}

Returns the aggregate of quantitative data for question {path} .

Query parameters
unit
string

Unit to return values in

Responses
unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl /api/supplier-1/metrics/aggregate/ghg-emissions
responds 
{
  "created_at": "2020-01-01T00:00:00Z",
  "measured": 12,
  "unit": "t"
}

Lists active grants and requests

endpoint 
GET /api/{profile}/portfolios

Lists all grants and requests that have to be accepted or denied by {profile} .

If you want to get all requests that have been initiated by {profile} , see Lists initiated requests . If you want to get all grants that have been initiated {profile} , see Lists initiated grants .

Query parameters
campaign
string

filter by campaign ()

ends_at
string

date/time in ISO 8601 format

o
string

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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: grantee__full_name, account__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

state
string

filter by state (grant-initiated, grant-accepted, grant-denied, grant-expired, request-initiated, request-accepted, request-denied, request-expired)

Responses
count
integer

next
string

previous
string

results
array

grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

Examples 
curl /api/energy-utility/portfolios
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "grantee": "energy-utility",
      "account": "supplier-1",
      "campaign": {
        "slug": "sustainability",
        "title": "ESG/Environmental practices",
        "account": "djaopsp"
      },
      "ends_at": "2022-01-01T00:00:00Z",
      "state": "request-initiated",
      "api_accept": "/api/supplier-1/portfolios/requests/0000000000000000000000000000000000000002/"
    }
  ]
}

Lists initiated grants

endpoint 
GET /api/{profile}/portfolios/grants

Lists all grants currently pending initiated by {profile} .

Query parameters
campaign
string

filter by campaign ()

ends_at
string

date/time in ISO 8601 format

o
string

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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: grantee__full_name, account__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

state
string

filter by state (grant-initiated, grant-accepted, grant-denied, grant-expired, request-initiated, request-accepted, request-denied, request-expired)

Responses
count
integer

next
string

previous
string

results
array

grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/supplier-1/portfolios/grants
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "grantee": "water-utility",
      "account": "supplier-1",
      "campaign": {
        "slug": "sustainability",
        "title": "ESG/Environmental practices",
        "account": "djaopsp"
      },
      "ends_at": "2022-01-01T00:00:00Z",
      "state": "grant-initiated",
      "api_accept": "/api/water-utility/portfolios/grants/0000000000000000000000000000000000000003/"
    }
  ]
}

Initiates grant

endpoint 
POST /api/{profile}/portfolios/grants

Initiate a grant of data to a grantee

Request body
accounts
array

campaign
string

Unique identifier that can be used in a URL

message
string

grantee
object required

slug
string required

full_name
string

email
string

Responses
count
integer

next
string

previous
string

results
array

grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"grantee": {"slug": "energy-utility", "full_name": "Energy Utility"}}' /api/supplier-1/portfolios/grants
responds 
{
  "count": 1,
  "results": [
    {
      "grantee": "water-utility",
      "account": "supplier-1",
      "campaign": null,
      "ends_at": "2022-01-01T00:00:00Z",
      "state": "grant-initiated",
      "api_accept": "/api/water-utility/portfolios/grants/0000000000000000000000000000000000000003/"
    }
  ]
}

Accepts grant

endpoint 
POST /api/{profile}/portfolios/grants/{verification_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 {profile} parameter is the grantee we have send data to here, while the {profile} parameter is the account owning that data when calling POST /api/{account}/grants .

Responses
grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST /api/energy-utility/portfolios/grants/0123456789abcef
responds 
{
  "grantee": "energy-utility",
  "account": "supplier-1",
  "campaign": {
    "slug": "sustainability",
    "title": "ESG/Environmental practices",
    "account": "djaopsp"
  },
  "ends_at": "2025-01-01T00:00:00Z",
  "state": "grant-accepted"
}

Ignores grant

endpoint 
DELETE /api/{profile}/portfolios/grants/{verification_key}
Responses

204 No Content

Examples 
curl -X DELETE /api/energy-utility/portfolios/grants/0123456789abcef

Updates extra field in a portfolio

endpoint 
PUT /api/{profile}/portfolios/metadata/{target}

The requestor/grantor uses this API call to add metadata about the request/grant.

Request body
extra
string

Extra meta data (can be stringify JSON)

Responses
grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"extra": {"tags": "tier1"}}' /api/energy-utility/portfolios/metadata/supplier-1
responds 
{
  "grantee": "energy-utility",
  "account": "supplier-1",
  "campaign": {
    "slug": "sustainability",
    "title": "ESG/Environmental practices",
    "account": "djaopsp"
  },
  "ends_at": "2022-01-01T00:00:00Z",
  "state": "request-denied",
  "api_accept": null,
  "extra": {
    "tags": "tier1"
  }
}

Lists initiated requests

endpoint 
GET /api/{profile}/portfolios/requests

Lists all requests currently pending initiated by {profile} .

Query parameters
campaign
string

filter by campaign ()

ends_at
string

date/time in ISO 8601 format

o
string

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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: grantee__full_name, account__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

state
string

filter by state (grant-initiated, grant-accepted, grant-denied, grant-expired, request-initiated, request-accepted, request-denied, request-expired)

Responses
count
integer

next
string

previous
string

results
array

grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/energy-utility/portfolios/requests
responds 
{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "grantee": "energy-utility",
      "account": "supplier-1",
      "campaign": {
        "slug": "sustainability",
        "title": "ESG/Environmental practices",
        "account": "djaopsp"
      },
      "ends_at": "2022-01-01T00:00:00Z",
      "state": "request-denied",
      "api_accept": null
    },
    {
      "grantee": "energy-utility",
      "account": "supplier-1",
      "campaign": {
        "slug": "sustainability",
        "title": "ESG/Environmental practices",
        "account": "djaopsp"
      },
      "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": {
        "slug": "sustainability",
        "title": "ESG/Environmental practices",
        "account": "djaopsp"
      },
      "ends_at": "2022-01-01T00:00:00Z",
      "state": "request-initiated",
      "api_accept": "/api/andy-shop/portfolios/requests/0000000000000000000000000000000000000004/"
    }
  ]
}

Initiates request

endpoint 
POST /api/{profile}/portfolios/requests

Initiate a request of data for an account.

Request body
accounts
array required

slug
string required

full_name
string

email
string

campaign
string

Unique identifier that can be used in a URL

message
string

extra
string

Extra meta data (can be stringify JSON)

Responses
accounts
array

slug
string

full_name
string

email
string

printable_name
string

campaign
string

Unique identifier that can be used in a URL

message
string

ends_at
string

When the request/grant expires

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"accounts": [{"slug": "supplier-1", "full_name": "Supplier 1"}]}' /api/energy-utility/portfolios/requests
responds 
{
  "accounts": [
    {
      "slug": "supplier-1",
      "full_name": "Supplier 1"
    }
  ]
}

Updates extra field in a request/grant

endpoint 
PUT /api/{profile}/portfolios/requests/metadata/{target}

The requestor/grantor uses this API call to add metadata about the request/grant.

Request body
extra
string

Extra meta data (can be stringify JSON)

Responses
grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"extra": {"tags": "tier1"}}' /api/energy-utility/portfolios/requests/metadata/supplier-1
responds 
{
  "grantee": "energy-utility",
  "account": "supplier-1",
  "campaign": {
    "slug": "sustainability",
    "title": "ESG/Environmental practices",
    "account": "djaopsp"
  },
  "ends_at": "2022-01-01T00:00:00Z",
  "state": "request-denied",
  "api_accept": null,
  "extra": {
    "tags": "tier1"
  }
}

Resends requests

endpoint 
POST /api/{profile}/portfolios/requests/send

Resends all requests directed to {profile}

Request body
username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Full name (effectively first name followed by last name)

email
string required

E-mail address for the originating user

Responses
username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Full name (effectively first name followed by last name)

email
string

E-mail address for the originating user

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "steve@example.com"}' /api/supplier-1/portfolios/requests/send
responds 
{}

Accepts request

endpoint 
POST /api/{profile}/portfolios/requests/{verification_key}

A grantee has made a request to {profile} 's portfolio. The {profile} accepts the request, making the {profile} 's answers up-to-date ends_at available to grantee .

Note that {profile} is the actual {profile} we are looking to access data from here, while the {profile} parameter is the grantee when calling Initiates request .

Responses
grantee
string

Profile a dataset will be shared with

account
string

Profile the dataset belongs to

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

created_at
string

Date/time at which the grant/request was created

ends_at
string

When the request/grant expires

state
object

expected_behavior
object

api_accept
string

api_remove
string

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X POST /api/supplier-1/portfolios/requests/0123456789abcef
responds 
{
  "grantee": "energy-utility",
  "account": "supplier-1",
  "campaign": {
    "slug": "sustainability",
    "title": "ESG/Environmental practices",
    "account": "djaopsp"
  },
  "ends_at": "2025-01-01T00:00:00Z",
  "state": "request-accepted"
}

Ignores request

endpoint 
DELETE /api/{profile}/portfolios/requests/{verification_key}
Responses

204 No Content

Examples 
curl -X DELETE /api/supplier-1/portfolios/requests/0123456789abcef

Lists last sample by campaign for reporting profiles

endpoint 
GET /api/{profile}/reporting

Lists last accessible sample by campaign for reporting profiles.

Query parameters
o
string

sort by created_at, full_name. 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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email. searches all fields when unspecified.

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

printable_name
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

created_at
string

Date/time of creation (in ISO format)

state
string

state of response

url
string

URL to access response

normalized_score
string

score on the response

Examples 
curl /api/energy-utility/reporting
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "andy-shop",
      "printable_name": "Andy's Shop",
      "values": [
        [
          "2023-01-01T00:00:00Z",
          "complete",
          95
        ],
        [
          "2022-01-01T00:00:00Z",
          "complete",
          95
        ],
        [
          "2021-01-01T00:00:00Z",
          "declined",
          null
        ],
        [
          "2020-01-01T00:00:00Z",
          "no-data",
          null
        ],
        [
          "2019-01-01T00:00:00Z",
          "no-data",
          null
        ],
        [
          "2018-01-01T00:00:00Z",
          "no-data",
          null
        ]
      ]
    },
    {
      "slug": "supplier-1",
      "printable_name": "Supplier 1",
      "values": [
        [
          "2023-01-01T00:00:00Z",
          "complete",
          82
        ],
        [
          "2022-01-01T00:00:00Z",
          "complete",
          82
        ],
        [
          "2021-01-01T00:00:00Z",
          "declined",
          null
        ],
        [
          "2020-01-01T00:00:00Z",
          "no-data",
          null
        ],
        [
          "2019-01-01T00:00:00Z",
          "no-data",
          null
        ],
        [
          "2018-01-01T00:00:00Z",
          "no-data",
          null
        ]
      ]
    }
  ]
}

Lists campaigns available for reporting

endpoint 
GET /api/{profile}/reporting/campaigns

Lists campaigns that are public, belongs to a profile, or in general are available to a profile for reporting purposes.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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.

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

Examples 
curl /api/alliance/reporting/campaigns
responds 
{
  "count": 1,
  "results": [
    {
      "slug": "construction",
      "account": "alliance",
      "title": "Assessment on sustainable construction practices",
      "is_active": true,
      "is_commons": true
    }
  ]
}

Retrieves week-by-week verification rate

endpoint 
GET /api/{profile}/reporting/notes

Returns the verification completed week-by-week.

Responses
scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
string

Unit the measured field is in

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/reporting/notes
responds 
{
  "title": "Completion rate (%)",
  "scale": 1,
  "unit": "percentage",
  "results": [
    {
      "slug": "completion-rate",
      "printable_name": "% 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
        ]
      ]
    },
    {
      "slug": "last-year",
      "printable_name": "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
        ]
      ]
    },
    {
      "slug": "alliance",
      "printable_name": "Alliance",
      "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
        ]
      ]
    }
  ]
}

Removes access to a profile samples

endpoint 
DELETE /api/{profile}/reporting/{campaign}/accessibles/{account}
Responses

204 No Content

Examples 
curl -X DELETE /api/energy-utility/reporting/sustainability/accessibles/supplier-1

Retrieves week-by-week completion rate

endpoint 
GET /api/{profile}/reporting/{campaign}/completion-rate

Returns the week-by-week percentage of requested accounts that have completed a scorecard.

Responses
scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
string

Unit the measured field is in

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/reporting/sustainability/completion-rate
responds 
{
  "title": "Completion rate (%)",
  "scale": 1,
  "unit": "percentage",
  "results": [
    {
      "slug": "completion-rate",
      "printable_name": "% 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
        ]
      ]
    },
    {
      "slug": "last-year",
      "printable_name": "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
        ]
      ]
    },
    {
      "slug": "alliance",
      "printable_name": "Alliance",
      "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
        ]
      ]
    }
  ]
}

Lists engagement for reporting profiles

endpoint 
GET /api/{profile}/reporting/{campaign}/engaged

reporting_status can be one of: - invited - updated / work-in-progress - completed - declined (to respond) - completed declined to share

Query parameters
page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email. searches all fields when unspecified.

Responses
count
integer

next
string

previous
string

results
array

slug
string

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

extra
string

Extra meta data (can be stringify JSON)

rank
string

rank in filter

sample
string

reporting_status
string

current reporting status

last_activity_at
string

Most recent time an assessment was updated

last_reminder_at
string

Most recent time a reminder was sent

requested_at
string

Datetime at which the scorecard was requested

normalized_score
integer

score_url
string

link to the scorecard

api_remove
string

Examples 
curl /api/energy-utility/reporting/sustainability/engaged
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "grantee": "energy-utility",
      "account": "supplier-1",
      "campaign": "sustainability",
      "created_at": "2022-01-01T00:00:00Z",
      "ends_at": "2023-01-01T00:00:00Z",
      "state": "request-denied",
      "api_accept": null,
      "reporting_status": "completed",
      "last_activity_at": "2022-11-01T00:00:00Z",
      "requested_at": "2022-01-01T00:00:00Z"
    },
    {
      "grantee": "energy-utility",
      "account": "andy-shop",
      "campaign": "sustainability",
      "created_at": "2022-01-01T00:00:00Z",
      "ends_at": "2023-01-01T00:00:00Z",
      "state": "request-accepted",
      "api_accept": null,
      "reporting_status": "completed",
      "last_activity_at": "2022-11-01T00:00:00Z",
      "requested_at": "2022-01-01T00:00:00Z"
    }
  ]
}

Retrieves up-to-date engagement rate

endpoint 
GET /api/{profile}/reporting/{campaign}/engaged/stats

Returns the engagement as of Today

Responses
scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
string

Unit the measured field is in

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

Examples 
curl /api/energy-utility/reporting/sustainability/engaged/stats
responds 
{
  "title": "Completion rate (%)",
  "scale": 1,
  "unit": "percentage",
  "results": [
    {
      "slug": "completion-rate",
      "printable_name": "% 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
        ]
      ]
    },
    {
      "slug": "last-year",
      "printable_name": "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
        ]
      ]
    },
    {
      "slug": "alliance",
      "printable_name": "Alliance",
      "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 a matrix of scores for cohorts against a metric

endpoint 
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
slug
string

title
string

metric
object

slug
string

Unique identifier for the group that can be used in a URL

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

cohorts
array

slug
string

Unique identifier for the group that can be used in a URL

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

cut
object

slug
string

Unique identifier for the group that can be used in a URL

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl /api/energy-utility/reporting/sustainability/matrix/totals
responds 
{
  "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

endpoint 
PUT /api/{profile}/reporting/{campaign}/matrix/{path}
Request body
slug
string

title
string required

metric
object

slug
string required

Unique identifier for the group that can be used in a URL

title
string required

Title for the group

extra
string

Extra meta data (can be stringify JSON)

cohorts
array required

slug
string required

Unique identifier for the group that can be used in a URL

title
string required

Title for the group

extra
string

Extra meta data (can be stringify JSON)

cut
object

slug
string required

Unique identifier for the group that can be used in a URL

title
string required

Title for the group

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

title
string

metric
object

slug
string

Unique identifier for the group that can be used in a URL

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

cohorts
array

slug
string

Unique identifier for the group that can be used in a URL

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

cut
object

slug
string

Unique identifier for the group that can be used in a URL

title
string

Title for the group

account
string

Account the group belongs to

extra
string

Extra meta data (can be stringify JSON)

Examples 
curl -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Average scores by supplier industry sub-sector", "cohorts": []}' /api/energy-utility/reporting/sustainability/matrix/languages
responds 
{
  "slug": "languages",
  "title": "All cohorts for all questions",
  "cohorts": []
}

Deletes a matrix of scores for cohorts against a metric

endpoint 
DELETE /api/{profile}/reporting/{campaign}/matrix/{path}
Responses

204 No Content

Examples 
curl -X DELETE /api/energy-utility/reporting/sustainability/matrix/languages

Lists samples

endpoint 
GET /api/{profile}/sample

Returns all samples for a profile

Query parameters
campaign
string

filter by campaign ()

ends_at
string

date/time in ISO 8601 format

o
string

sort by created_at, campaign__title, is_frozen. 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.

page
integer

A page number within the paginated result set.

start_at
string

date/time in ISO 8601 format

state
string

filter by state (active, completed)

Responses
count
integer

next
string

previous
string

results
array

campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

slug
string

Unique identifier for the sample. It can be used in a URL.

account
string

Account this sample belongs to

created_at
string

Date/time of creation (in ISO format)

updated_at
string

Date/time of last update (in ISO format)

is_frozen
boolean

When True, answers to that sample cannot be updated.

location
string

URL at which the response is visible

grantees
array

Profiles with which sample was shared

verified_status
string

verification status

Examples 
curl /api/supplier-1/sample
responds 
{
  "count": 1,
  "previous": null,
  "next": null,
  "results": [
    {
      "slug": "46f66f70f5ad41b29c4df08f683a9a7a",
      "created_at": "2018-01-24T17:03:34.926193Z",
      "campaign": "sustainability",
      "is_frozen": false,
      "extra": null,
      "verified_status": "no-review"
    }
  ]
}

Creates a sample

endpoint 
POST /api/{profile}/sample

Creates a new sample to record qualitative and/or quantitative data.

Request body
campaign
string

Campaign this sample is part of.

Responses
campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

slug
string

Unique identifier for the sample. It can be used in a URL.

account
string

Account this sample belongs to

created_at
string

Date/time of creation (in ISO format)

updated_at
string

Date/time of last update (in ISO format)

is_frozen
boolean

When True, answers to that sample cannot be updated.

location
string

URL at which the response is visible

grantees
array

Profiles with which sample was shared

verified_status
string

verification status

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/supplier-1/sample
responds 
{
  "slug": "46f66f70f5ad41b29c4df08f683a9a7a",
  "created_at": "2018-01-24T17:03:34.926193Z",
  "campaign": "sustainability"
}

Retrieves a sample

endpoint 
GET /api/{profile}/sample/{sample}

Returns top level information about a sample.

Responses
campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

slug
string

Unique identifier for the sample. It can be used in a URL.

account
string

Account this sample belongs to

created_at
string

Date/time of creation (in ISO format)

updated_at
string

Date/time of last update (in ISO format)

is_frozen
boolean

When True, answers to that sample cannot be updated.

location
string

URL at which the response is visible

grantees
array

Profiles with which sample was shared

Examples 
curl /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a
responds 
{
  "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": {
    "slug": "sustainability",
    "title": "ESG/Environmental practices"
  }
}

Lists answers

endpoint 
GET /api/{profile}/sample/{sample}/answers

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
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

required
boolean

Whether an answer is required or not.

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/answers
responds 
{
  "count": 3,
  "previous": null,
  "next": null,
  "results": [
    {
      "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,
      "answers": [
        {
          "measured": "yes",
          "unit": "assessment",
          "created_at": "2020-09-28T00:00:00.000000Z",
          "collected_by": "steve"
        }
      ]
    },
    {
      "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,
      "answers": [
        {
          "measured": "Policy document on the public website",
          "unit": "freetext",
          "created_at": "2020-09-28T00:00:00.000000Z",
          "collected_by": "steve"
        }
      ]
    },
    {
      "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,
      "answers": []
    }
  ]
}

Lists answers for a subset of questions

endpoint 
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.

Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

required
boolean

Whether an answer is required or not.

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/answers/construction
responds 
{
  "count": 3,
  "previous": null,
  "next": null,
  "results": [
    {
      "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,
      "answers": [
        {
          "measured": "yes",
          "unit": "assessment",
          "created_at": "2020-09-28T00:00:00.000000Z",
          "collected_by": "steve"
        }
      ]
    },
    {
      "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,
      "answers": [
        {
          "measured": "Policy document on the public website",
          "unit": "freetext",
          "created_at": "2020-09-28T00:00:00.000000Z",
          "collected_by": "steve"
        }
      ]
    },
    {
      "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,
      "answers": []
    }
  ]
}

Updates an answer

endpoint 
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
string

Unit the measured field is in

measured
string required

measurement in unit

created_at
string

Date/time of creation (in ISO format)

Responses
unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"measured": "Yes"}' /api/supplier-1/sample/4c6675a5d5af46c796b8033a7731a86e/answers/code-of-conduct
responds 
{
  "created_at": "2020-09-28T00:00:00.000000Z",
  "collected_by": "steve",
  "measured": "Yes",
  "unit": "yes-no"
}

Benchmarks against all peers

endpoint 
GET /api/{profile}/sample/{sample}/benchmarks

Returns a list of graphs with anonymized performance of peers for paths marked as visible (see ::ref:: api_score ).

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

avg_normalized_score
integer

highest_normalized_score
integer

nb_respondents
integer

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

avg_normalized_score
integer

Average score for the campaign

highest_normalized_score
integer

Highest score for the campaign

Examples 
curl /api/supplier-1/sample/ce6dc2c4cf6b40dbacef91fa3e934eed/benchmarks
responds 
{
  "highest_normalized_score": 100,
  "avg_normalized_score": 50,
  "results": [
    {
      "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,
      "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%"
        ]
      }
    },
    {
      "slug": "energy-efficiency-management-basics",
      "title": "Management",
      "tag": "management",
      "score_weight": 1.0
    },
    {
      "slug": "process-heating",
      "title": "Process heating",
      "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,
      "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%"
        ]
      },
      "score_weight": 1.0
    }
  ]
}

Benchmarks against all peers for a subset of questions

endpoint 
GET /api/{profile}/sample/{sample}/benchmarks/{path}

Returns a list of graphs with anonymized performance of peers for paths marked as visible (see ::ref:: api_score ).

Responses
title
integer

Title for the results table

scale
integer

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands)

unit
integer

Unit the measured field is in

nb_accounts
integer

Total number of accounts evaluated

labels
array

Labels for the x-axis when present

count
integer

The number of records

results
array

Items in the queryset

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

avg_normalized_score
integer

highest_normalized_score
integer

nb_respondents
integer

benchmarks
array

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

Datapoints in the serie

avg_normalized_score
integer

Average score for the campaign

highest_normalized_score
integer

Highest score for the campaign

Examples 
curl /api/supplier-1/sample/ce6dc2c4cf6b40dbacef91fa3e934eed/benchmarks/boxes-enclosures
responds 
{
  "avg_normalized_score": 50,
  "highest_normalized_score": 100,
  "results": [
    {
      "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,
      "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%"
        ]
      }
    },
    {
      "slug": "energy-efficiency-management-basics",
      "title": "Management",
      "text": "/media/djaopsp/management-basics.png",
      "tag": "management",
      "score_weight": 1.0
    },
    {
      "slug": "process-heating",
      "title": "Process heating",
      "text": "/media/djaopsp/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,
      "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%"
        ]
      },
      "score_weight": 1.0
    }
  ]
}

Lists candidate answers

endpoint 
GET /api/{profile}/sample/{sample}/candidates

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.

Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

required
boolean

Whether an answer is required or not.

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/candidates
responds 
{
  "count": 2,
  "previous": null,
  "next": null,
  "results": [
    {
      "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,
      "candidates": [
        {
          "measured": "yes",
          "unit": "assessment",
          "created_at": "2020-09-28T00:00:00.000000Z",
          "collected_by": "steve"
        }
      ]
    },
    {
      "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",
      "candidates": []
    }
  ]
}

Uses candidate answers for a subset of questions

endpoint 
POST /api/{profile}/sample/{sample}/candidates

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
count
integer

next
string

previous
string

results
array

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

required
boolean

Whether an answer is required or not.

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/candidates
responds 
{
  "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 candidate answers for a subset of questions

endpoint 
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.

Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

required
boolean

Whether an answer is required or not.

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/candidates/construction
responds 
{
  "count": 2,
  "previous": null,
  "next": null,
  "results": [
    {
      "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,
      "candidates": [
        {
          "measured": "yes",
          "unit": "assessment",
          "created_at": "2020-09-28T00:00:00.000000Z",
          "collected_by": "steve"
        }
      ]
    },
    {
      "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",
      "candidates": []
    }
  ]
}

Uses candidate answers

endpoint 
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
count
integer

next
string

previous
string

results
array

path
string

Unique identifier that can be used in URL

title
string

Short description

default_unit
object

Default unit for measured field when none is specified

slug
string

Unique identifier that can be used in a URL

title
string

Short description suitable for display

system
string

One of standard (metric system), imperial, rank, enum, or freetext

ui_hint
string

Hint for the user interface on how to present the input field

required
boolean

Whether an answer is required or not.

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/candidates/construction
responds 
{
  "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
    }
  ]
}

Formats answers

endpoint 
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
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

ui_hint
string

text
string

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

planned
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

notes
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

normalized_score
string

opportunity
string

Examples 
curl /api/andy-shop/sample/f1e2e916eb494b90f9ff0a36982342/content
responds 
{
  "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"
        ]
      },
      "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"
        ]
      },
      "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"
        ]
      },
      "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?",
      "picture": "/tspproject/static/img/management-basics.png",
      "extra": {
        "segments": [
          "/sustainability"
        ]
      },
      "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
    }
  ]
}

Formats answers for a subset of questions

endpoint 
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.

Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Unique identifier that can be used in URL paths

path
string

path from the root of content tree

indent
string

level in the content tree

account
string

Account that can edit the page element

title
string

Title of the page element

picture
string

Picture icon that can be displayed alongside the title

extra
string

Extra meta data (can be stringify JSON)

default_unit
string

Default unit used to select the primary answer

score_weight
string

rank
string

Natural number to present practices in a logical order

required
string

True when an answer with a default_unit is required

ref_num
string

Purely visual short identifier for the question (ex: 1, 1.1, 2a)

frozen
string

True when answers cannot be changed

url
string

Location of the text description for the practice

segments
array

ui_hint
string

text
string

answers
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

candidates
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

planned
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

notes
array

unit
string

Unit the measured field is in

measured
string

measurement in unit

created_at
string

Date/time of creation (in ISO format)

collected_by
string

User that collected the answer

normalized_score
string

opportunity
string

Examples 
curl /api/andy-shop/sample/f1e2e916eb494b90f9ff0a36982342/content/sustainability
responds 
{
  "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"
        ]
      },
      "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"
        ]
      },
      "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"
        ]
      },
      "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?",
      "picture": "/tspproject/static/img/management-basics.png",
      "extra": {
        "segments": [
          "/sustainability"
        ]
      },
      "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 answers

endpoint 
POST /api/{profile}/sample/{sample}/freeze

A frozen sample cannot be edited to add and/or update answers.

Request body
grantees
array

Profiles with which sample was shared

Responses
campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

slug
string

Unique identifier for the sample. It can be used in a URL.

account
string

Account this sample belongs to

created_at
string

Date/time of creation (in ISO format)

updated_at
string

Date/time of last update (in ISO format)

is_frozen
boolean

When True, answers to that sample cannot be updated.

location
string

URL at which the response is visible

grantees
array

Profiles with which sample was shared

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/supplier-1/sample/0123456789abcdef/freeze
responds 
{
  "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 answers for a subset of questions

endpoint 
POST /api/{profile}/sample/{sample}/freeze/{path}

A frozen sample cannot be edited to add and/or update answers.

Request body
grantees
array

Profiles with which sample was shared

Responses
campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

slug
string

Unique identifier for the sample. It can be used in a URL.

account
string

Account this sample belongs to

created_at
string

Date/time of creation (in ISO format)

updated_at
string

Date/time of last update (in ISO format)

is_frozen
boolean

When True, answers to that sample cannot be updated.

location
string

URL at which the response is visible

grantees
array

Profiles with which sample was shared

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/supplier-1/sample/0123456789abcdef/freeze/construction
responds 
{
  "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

endpoint 
POST /api/{profile}/sample/{sample}/reset

Clears all answers for {sample} .

{sample} must belong to {profile} otherwise no action is taken and an error is returned.

Responses
campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

slug
string

Unique identifier for the sample. It can be used in a URL.

account
string

Account this sample belongs to

created_at
string

Date/time of creation (in ISO format)

updated_at
string

Date/time of last update (in ISO format)

is_frozen
boolean

When True, answers to that sample cannot be updated.

location
string

URL at which the response is visible

grantees
array

Profiles with which sample was shared

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/reset
responds 
{
  "slug": "46f66f70f5ad41b29c4df08f683a9a7a",
  "created_at": "2018-01-24T17:03:34.926193Z",
  "campaign": "sustainability"
}

Clears answers for a subset of questions

endpoint 
POST /api/{profile}/sample/{sample}/reset/{path}

Clears answers for {sample} for which {path} is a prefix of the question's path.

{sample} must belong to {profile} otherwise no action is taken and an error is returned.

Responses
campaign
object

Short description of the campaign

slug
string

Unique identifier that can be used in a URL

account
string

Account this sample belongs to.

title
string

Title of the campaign as displayed in user interfaces

description
string

Long form description displayed to users responding to the campaign

created_at
string

is_active
boolean

Whether the campaign is available or not

is_commons
boolean

True when the campaign is for the benefit of the community

slug
string

Unique identifier for the sample. It can be used in a URL.

account
string

Account this sample belongs to

created_at
string

Date/time of creation (in ISO format)

updated_at
string

Date/time of last update (in ISO format)

is_frozen
boolean

When True, answers to that sample cannot be updated.

location
string

URL at which the response is visible

grantees
array

Profiles with which sample was shared

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{}' /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/reset/construction
responds 
{
  "slug": "46f66f70f5ad41b29c4df08f683a9a7a",
  "created_at": "2018-01-24T17:03:34.926193Z",
  "campaign": "sustainability"
}

Lists respondents

endpoint 
GET /api/{profile}/sample/{sample}/respondents

The list returned contains the information about the users who answered at least one question.

The {sample} must belong to {organization}.

{path} can be used to filter the tree of questions by a prefix.

Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

last_login
string

Date/time of last login (in ISO format)

Examples 
curl /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/respondents
responds 
{
  "count": 1,
  "previous": null,
  "next": null,
  "results": [
    {
      "slug": "steve",
      "full_name": "Steve"
    }
  ]
}

Lists respondents for a subset of questions

endpoint 
GET /api/{profile}/sample/{sample}/respondents/{path}

The list returned contains the information about the users who answered at least one question.

The {sample} must belong to {organization}.

{path} can be used to filter the tree of questions by a prefix.

Query parameters
page
integer

A page number within the paginated result set.

Responses
count
integer

next
string

previous
string

results
array

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

last_login
string

Date/time of last login (in ISO format)

Examples 
curl /api/supplier-1/sample/46f66f70f5ad41b29c4df08f683a9a7a/respondents/construction
responds 
{
  "count": 1,
  "previous": null,
  "next": null,
  "results": [
    {
      "slug": "steve",
      "full_name": "Steve"
    }
  ]
}