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

Assessments

Clears answers
Clears answers for a subset of questions
Creates a sample
Formats answers
Formats answers for a subset of questions
Freezes answers
Freezes answers for a subset of questions
Lists answers
Lists answers for a subset of questions
Lists candidate answers
Lists candidate answers for a subset of questions
Lists profiles with a frozen response
Lists quantitative measurements
Lists quantitative measurements for a group
Lists respondents
Lists respondents for a subset of questions
Lists samples
Records quantitative measurements
Retrieves a sample
Updates an answer
Uses candidate answers
Uses candidate answers for a subset of questions

This section contains APIs related to assessments

This section contains APIs related to sharing data

Reporting

Deletes a matrix of scores for cohorts against a metric
Lists campaigns available for reporting
Lists engagement for reporting profiles
Retrieves a matrix of scores for cohorts against a metric
Retrieves aggregated quantitative measurements over a time period
Retrieves up-to-date engagement rate
Retrieves week-by-week completion rate
Retrieves week-by-week verification rate
Updates a matrix of scores for cohorts against a metric

This section contains APIs related to reporting

Benchmarks

Benchmarks against accessible profiles
Benchmarks against accessible profiles for a subset of questions
Benchmarks against all peers
Benchmarks against all peers for a subset of questions
Benchmarks against all profiles
Benchmarks against all profiles for a subset of questions
Benchmarks against engaged profiles
Benchmarks against engaged profiles for a subset of questions
Benchmarks against selected profiles
Benchmarks against selected profiles for a subset of questions

This section contains APIs related to anonymized aggregated benchmarks.

Cohorts

Adds a profile to a group
Creates a group of profiles
Deletes a group of profiles
Lists groups of profiles
Lists profiles in a group
Removes a selector from a group
Renames a group of profiles
Retrieves a selector in a group
Updates a selector in a group

This section contains APIs related to creating cohorts for anonymized aggregated benchmarks.

Content readers

Comments on a page element
Downvotes a page element
Follows a page element
Lists available sequences
Lists comments on a page element
Lists progress on a sequence
Lists questions accross all accessible campaigns
Lists questions in a campaign
Lists tree of page elements
Lists tree of page elements matching prefix
Lists units
Retrieves a page element
Retrieves a unit
Retrieves attendance to live event
Retrieves enumerated choices for a unit
Retrieves relevant news for a user
Retrieves viewing duration for an element
Searches page elements
Unfollows a page element
Updates viewing duration for an element
Upvotes a page element

This section contains APIs related to content readers

Content editors

Creates a campaign
Creates a page element
Creates a page element under a prefix
Creates a question
Creates a question under a prefix
Creates a segment in a campaign
Creates a sequence
Deletes a campaign
Deletes a page element
Deletes a sequence
Deletes a subset of questions
Inserts a page element in a sequence
Lists editable campaigns
Lists editable page elements
Lists editable sequences
Lists page elements in a sequence
Lists questions in an editable campaign
Lists segments in a campaign
Records attendance to a live event
Removes a page element from a sequence
Resets a user's progress on a sequence
Retrieves a sequence
Retrieves an editable page element
Retrieves an editable question
Updates a page element
Updates a question
Updates a sequence

This section contains APIs related to content editors

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

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

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

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

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

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

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

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

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

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

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

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

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

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.

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

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

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

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

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

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

string

Which field to use when ordering the results.

page

integer

A page number within the paginated result set.

string

A search term.

Responses

count

integer

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

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

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

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.

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

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

string

units that can be used intercheably with this one

page

integer

A page number within the paginated result set.

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

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

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

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.

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

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

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

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

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

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.

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

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

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.

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

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

Responses

count

integer

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

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.

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

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

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

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)

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)

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

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.

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

string

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

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

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.

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

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.

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

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

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

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

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.

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

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

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.

The sample must belong to organization .

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

Responses

count

integer

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.

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

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.

The sample must belong to organization .

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

Responses

count

integer

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.

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

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.

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

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

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.

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

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.

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"
    }
  ]
}