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 matching prefix
Freezes answers
Freezes answers matching prefix
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 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 defined group 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 comments on a page element
Lists progress for a user on a sequence
Lists sequences of page elements
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 relevant news for a user
Retrieves viewing time for an element
Searches page elements
Unfollows a page element
Updates viewing time 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 practice
Creates a question
Creates a segment in a campaign
Creates a sequence of page elements
Deletes a campaign
Deletes a page element
Deletes a sequence
Deletes questions
Inserts a page element in a sequence
List editable page elements
List questions in a campaign
List questions in a campaign
List segments in a campaign
Lists editable sequences
Lists page elements in a sequence
Lists profile campaigns
Marks a user's attendance to a live event
Removes a page element from a sequence
Resets a user's progress on a sequence
Retrieves a campaign
Retrieves a question
Retrieves a sequence
Retrieves an editable page element
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}

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

Marks a user's 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 -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 -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

path

string

path from the root of content tree

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

string

Long description of the page element

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

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

score_weight

string

rank

string

required

string

frozen

string

url

string

segments

array

html_formatted

string

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

List 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

score_weight

string

rank

string

required

string

frozen

string

url

string

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

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

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

text

string

Long description of the page element

reading_time

string

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

lang

string

Language the material is written in

nb_upvotes

integer

Number of times the content has been upvoted

nb_followers

integer

Number of followers notified when content is updated

count

integer

results

array

title

string

Title of the page element

picture

string

Picture icon that can be displayed alongside the title

Responses

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

Examples

curl -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

text

string

Long description of the page element

reading_time

string

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

lang

string

Language the material is written in

nb_upvotes

integer

Number of times the content has been upvoted

nb_followers

integer

Number of followers notified when content is updated

count

integer

results

array

title

string

Title of the page element

picture

string

Picture icon that can be displayed alongside the title

Responses

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

Examples

curl -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

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

Examples

curl /api/content/search

responds

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "hello",
      "path": "/hello",
      "title": "Hello"
    }
  ]
}

Lists sequences of page elements

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

text

string

Long description of the page element

reading_time

string

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

lang

string

Language the material is written in

nb_upvotes

integer

Number of times the content has been upvoted

nb_followers

integer

Number of followers notified when content is updated

count

integer

results

array

title

string

Title of the page element

picture

string

Picture icon that can be displayed alongside the title

Responses

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

Examples

curl -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

text

string

Long description of the page element

reading_time

string

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

lang

string

Language the material is written in

nb_upvotes

integer

Number of times the content has been upvoted

nb_followers

integer

Number of followers notified when content is updated

count

integer

results

array

title

string

Title of the page element

picture

string

Picture icon that can be displayed alongside the title

Responses

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

Examples

curl -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

path

string

path from the root of content tree

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

string

Long description of the page element

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

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

score_weight

string

rank

string

required

string

frozen

string

url

string

segments

array

html_formatted

string

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

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

text_updated_at

string

Datetime of last update on the page element's text

nb_comments_since_last_read

integer

Number of comments since last read

last_read_at

string

Last time the PageElement was read

descr

string

Examples

curl /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": ""
    }
  ]
}

List questions in a 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

score_weight

string

rank

string

required

string

frozen

string

url

string

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 practice

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

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

score_weight

string

rank

string

required

string

frozen

string

url

string

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

List 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

score_weight

string

rank

string

required

string

frozen

string

url

string

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 a question

endpoint

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

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

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)

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 -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)

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

List 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

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

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

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

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

text

string

Long description of the page element

reading_time

string

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

lang

string

Language the material is written in

nb_upvotes

integer

Number of times the content has been upvoted

nb_followers

integer

Number of followers notified when content is updated

count

integer

results

array

title

string

Title of the page element

picture

string

Picture icon that can be displayed alongside the title

Responses

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

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

text

string

Long description of the page element

reading_time

string

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

lang

string

Language the material is written in

nb_upvotes

integer

Number of times the content has been upvoted

nb_followers

integer

Number of followers notified when content is updated

count

integer

results

array

title

string

Title of the page element

picture

string

Picture icon that can be displayed alongside the title

Responses

path

string

path from the root of content tree

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

string

Long description of the page element

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

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)

html_formatted

string

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 of page elements

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 for a user 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 time for an element

endpoint

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

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 time for an element

endpoint

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

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": [
    {
      "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
    }
  ]
}

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

choices

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

responds

{
  "count": 1,
  "previous": null,
  "next": null,
  "results": [
    {
      "slug": "assessment",
      "title": "assessments",
      "system": "enum",
      "choices": [
        {
          "rank": 1,
          "text": "mostly-yes",
          "descr": "Mostly yes"
        },
        {
          "rank": 2,
          "text": "yes",
          "descr": "Yes"
        },
        {
          "rank": 3,
          "text": "no",
          "descr": "No"
        },
        {
          "rank": 4,
          "text": "mostly-no",
          "descr": "Mostly no"
        }
      ]
    }
  ]
}

Retrieves a unit

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

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

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

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

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

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)

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

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

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)

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

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

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)

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

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

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)

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

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

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)

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

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

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)

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

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

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)

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

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

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)

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 profile campaigns

endpoint

GET /api/{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

active

boolean

Whether the campaign is available or not

Examples

curl /api/alliance/campaigns

responds

{
  "count": 1,
  "results": [
    {
      "slug": "construction",
      "account": "alliance",
      "title": "Assessment on sustainable construction practices",
      "active": true
    }
  ]
}

Creates a campaign

endpoint

POST /api/{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)

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

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

Retrieves a campaign

endpoint

GET /api/{profile}/campaigns/{campaign}

Retrieves the details of a Campaign.

Responses

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

active

boolean

Whether the campaign is available or not

quizz_mode

boolean

If checked, correct answser are required

questions

array

path

string

Unique identifier that can be used in URL

title

string

Short description

default_unit

object

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

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)

ui_hint

string

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

Examples

curl /api/alliance/campaigns/sustainability

responds

{
  "slug": "construction",
  "account": "alliance",
  "title": "Assessment on sustainable construction practices",
  "active": true,
  "quizz_mode": false,
  "questions": [
    {
      "path": "/construction/product-design",
      "title": "Product Design",
      "default_unit": {
        "slug": "assessment",
        "title": "assessments",
        "system": "enum",
        "choices": [
          {
            "rank": 1,
            "text": "mostly-yes",
            "descr": "Mostly yes"
          },
          {
            "rank": 2,
            "text": "yes",
            "descr": "Yes"
          },
          {
            "rank": 3,
            "text": "no",
            "descr": "No"
          },
          {
            "rank": 4,
            "text": "mostly-no",
            "descr": "Mostly no"
          }
        ]
      },
      "ui_hint": "radio"
    },
    {
      "path": "/construction/packaging-design",
      "title": "Packaging Design",
      "default_unit": {
        "slug": "assessment",
        "title": "assessments",
        "system": "enum",
        "choices": [
          {
            "rank": 1,
            "text": "mostly-yes",
            "descr": "Mostly yes"
          },
          {
            "rank": 2,
            "text": "yes",
            "descr": "Yes"
          },
          {
            "rank": 3,
            "text": "no",
            "descr": "No"
          },
          {
            "rank": 4,
            "text": "mostly-no",
            "descr": "Mostly no"
          }
        ]
      },
      "ui_hint": "radio"
    }
  ]
}

Deletes a campaign

endpoint

DELETE /api/{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 defined group 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 records. XXX What was entered in the system?

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

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 records. XXX What was entered in the system?

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

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

slug

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

slug

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

If you want to get all requests that have been initiated by account, see /api/{account}/requests. If you want to get all grants that have been initiated account, see /api/{account}/grants.

Query parameters

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

account

string

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

active

boolean

Whether the campaign is available or not

created_at

string

Date/time at which the grant/request was created

ends_at

string

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

Query parameters

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

account

string

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

active

boolean

Whether the campaign is available or not

created_at

string

Date/time at which the grant/request was created

ends_at

string

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 required

string

Responses

count

integer

string

results

array

grantee

string

account

string

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

active

boolean

Whether the campaign is available or not

created_at

string

Date/time at which the grant/request was created

ends_at

string

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

Responses

grantee

string

account

string

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

active

boolean

Whether the campaign is available or not

created_at

string

Date/time at which the grant/request was created

ends_at

string

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

Lists initiated requests

endpoint

GET /api/{profile}/portfolios/requests

Lists all requests currently pending initiated by account.

Query parameters

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

account

string

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

active

boolean

Whether the campaign is available or not

created_at

string

Date/time at which the grant/request was created

ends_at

string

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 required

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

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

account

string

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

active

boolean

Whether the campaign is available or not

created_at

string

Date/time at which the grant/request was created

ends_at

string

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

Accepts request

endpoint

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

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

Note that account is the actual account we are looking to access data from here, while the account parameter is the grantee when calling POST /api/{account}/requests.

Responses

grantee

string

account

string

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

active

boolean

Whether the campaign is available or not

created_at

string

Date/time at which the grant/request was created

ends_at

string

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

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

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

active

boolean

Whether the campaign is available or not

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

active

boolean

Whether the campaign is available or not

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

active

boolean

Whether the campaign is available or not

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

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

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)

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

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

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)

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

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

score_weight

string

rank

string

required

string

frozen

string

url

string

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

score_weight

string

rank

string

required

string

frozen

string

url

string

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

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

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)

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

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

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)

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

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

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)

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

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

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)

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

score_weight

string

rank

string

required

string

frozen

string

url

string

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 matching prefix

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

score_weight

string

rank

string

required

string

frozen

string

url

string

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

active

boolean

Whether the campaign is available or not

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 matching prefix

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

active

boolean

Whether the campaign is available or not

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

active

boolean

Whether the campaign is available or not

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

active

boolean

Whether the campaign is available or not

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