Introduction
Welcome to the UNGC API! You can use our API to access COP API endpoints, which can get information about communication of progress.
We have language bindings in Shell, Ruby, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Inclusion of Related Resources
We support an include request parameter that's allow you to customize which related resources should be returned.
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/cops/1?include=form%2Cform.form_categories
Internationalization
We support a locale request parameter that allows selecting the language of the returned resources.
Supported languages: English, French, Chinese, Hebrew
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/cops/1?locale=en
Cops
Get all cops
The endpoint that will get all cops
curl -X GET https://prod-cop-api.herokuapp.com/v1/cops \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
Response 200
{
"data": [
{
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 0,
"completed_percent_target": 0,
"level": "submitted",
"status": "published",
"visibility": "public",
"external_survey_link": null,
"name": "COP-2020",
"goals_count": 0,
"questions_count": 2,
"answered_questions": 0,
"signature_request_completed": false,
"external_id": null,
"publish_date": null,
"type": "early_adopter",
"submission_period_year": 2022
},
"relationships": {
"form": {
"data": {
"id": "2",
"type": "form"
}
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/{id}",
"current_question": "https://prod-cop-api.herokuapp.com/v1/cops/{id}/questions/{id}",
"current_category": "https://prod-cop-api.herokuapp.com/v1/cops/{id}/categories/{id}",
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
}
],
"included": [
{
"id": "2",
"type": "form",
"attributes": {
"name": "Upload form"
},
"relationships": {
"form_modules": {
"data": [
{
"id": "1",
"type": "form_module"
},
{
"id": "2",
"type": "form_module"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/{id}"
}
}
],
"meta": {
"current_submission_period": {
"year": 2023
}
},
"links": {
"sign": "https://prod-cop-api.herokuapp.com/v1/signature?cop_id={id}",
"delete": "https://prod-cop-api.herokuapp.com/v1/cops/{id}",
"reset_signature": "https://prod-cop-api.herokuapp.com/v1/cops/{id}/reset_signature"
}
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/cops
Links
| Link | Description |
|---|---|
| create | A link to create a new cop |
Filtering
You can filter cops by the following attributes: status and submission_published_year.
| Parameter | Required | Description |
|---|---|---|
| filter | false | Object specifying how to filter the result set. |
| filter[attribute] | true | Specifies the attribute on which the filtering will be done |
Get cop
The endpoint that will get a cop
curl -X GET \
https://prod-cop-api.herokuapp.com/v1/cops/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
Response 200
{
"data": {
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 0,
"completed_percent_target": 0,
"level": "submitted",
"status": "draft",
"visibility": "public",
"external_survey_link": null,
"name": "COP-2020",
"goals_count": 0,
"questions_count": 2,
"answered_questions": 0,
"signature_request_completed": false,
"external_id": null,
"publish_date": null,
"type": "early_adopter",
"submission_period_year": 2022
},
"relationships": {
"form": {
"data": {
"id": "1",
"type": "form"
}
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1",
"current_question": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"current_category": "https://prod-cop-api.herokuapp.com/v1/cops/1/categories/1",
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
},
"included": [
{
"id": "1",
"type": "upload",
"attributes": {
"position": 1,
"title": "Upload the COP statement",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "1",
"type": "selectable_choice",
"attributes": {
"position": 1,
"title": "CEO",
"details_required": null,
"value": "ceo"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "2",
"type": "selectable_choice",
"attributes": {
"position": 2,
"title": "Board of Directors",
"details_required": null,
"value": "board_of_directors"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "3",
"type": "selectable_choice",
"attributes": {
"position": 3,
"title": "Corporate Responsibility or Ethics officer",
"details_required": null,
"value": "corporate_responsibility_or_ethics_officer"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "2",
"type": "multiple_choice",
"attributes": {
"position": 2,
"title": "At what levels within your company are corporate responsibility policies and strategies developed and/or evaluated? Select all that apply:",
"answered": false,
"response_type": "answer",
"choices_limit": null
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
{
"id": "1",
"type": "selectable_choice"
},
{
"id": "2",
"type": "selectable_choice"
},
{
"id": "3",
"type": "selectable_choice"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "1",
"type": "form_category",
"attributes": {
"position": 1,
"title": "General",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "1",
"type": "upload"
},
{
"id": "2",
"type": "multiple_choice"
}
]
}
}
},
{
"id": "1",
"type": "form_module",
"attributes": {
"position": 1,
"title": "Sustainability Governance",
"questions_count": 2,
"answered_questions": 0,
"background_color": "#FFFFFF"
},
"relationships": {
"form_categories": {
"data": [
{
"id": "1",
"type": "form_category"
}
]
}
}
},
{
"id": "4",
"type": "selectable_choice",
"attributes": {
"position": 1,
"title": "Board discusses and acts on these issues as part of regular agenda",
"details_required": null,
"value": "board_part_of_regular agenda"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "5",
"type": "selectable_choice",
"attributes": {
"position": 2,
"title": "Board addresses these issues from time to time, as needed",
"details_required": null,
"value": "board_time_to_time"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "6",
"type": "selectable_choice",
"attributes": {
"position": 3,
"title": "Board does not address corporate responsibility issues ",
"details_required": null,
"value": "board_does_not_address"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "3",
"type": "single_choice",
"attributes": {
"position": 1,
"title": "How often does your company’s Board of Directors (or equivalent*) address corporate responsibility issues?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
{
"id": "4",
"type": "selectable_choice"
},
{
"id": "5",
"type": "selectable_choice"
},
{
"id": "6",
"type": "selectable_choice"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "4",
"type": "numeric",
"attributes": {
"position": 2,
"title": "What is the number of complaints received regarding human rights?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "5",
"type": "percentage",
"attributes": {
"position": 3,
"title": "What percentage of employees received a regular performance and career development review?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "6",
"type": "text_area",
"attributes": {
"position": 4,
"title": "Are there any other initiatives that your company is taking to address Human Rights?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "1",
"type": "sdg",
"attributes": {
"title": "SDG"
}
},
{
"id": "7",
"type": "text",
"attributes": {
"position": 5,
"title": "Description of the organization’s values, principles, standards, and norms of behavior",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
{
"id": "1",
"type": "sdg"
}
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null,
"create_document": "https://prod-cop-api.herokuapp.com/v1/documents"
}
},
{
"id": "2",
"type": "form_category",
"attributes": {
"position": 2,
"title": "Human Rights",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "3",
"type": "single_choice"
},
{
"id": "4",
"type": "numeric"
},
{
"id": "5",
"type": "percentage"
},
{
"id": "6",
"type": "text_area"
},
{
"id": "7",
"type": "text"
}
]
}
}
},
{
"id": "2",
"type": "form_module",
"attributes": {
"position": 2,
"title": "Human Rights",
"questions_count": 2,
"answered_questions": 0,
"background_color": "#FFFFFF"
},
"relationships": {
"form_categories": {
"data": [
{
"id": "2",
"type": "form_category"
}
]
}
}
},
{
"id": "1",
"type": "form",
"attributes": {
"name": "Test form"
},
"relationships": {
"form_modules": {
"data": [
{
"id": "1",
"type": "form_module"
},
{
"id": "2",
"type": "form_module"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1"
}
}
]
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/cops/1
Links
| Link | Description |
|---|---|
| self | A link to the object itself |
| current_question | A link to the current question for this cop |
| current_category | A link to the current category for this cop |
Filtering
You can filter cops form questions by the following attributes: tag.
| Parameter | Required | Description |
|---|---|---|
| filter | false | Object specifying how to filter the result set. |
| filter[attribute] | true | Specifies the attribute on which the filtering will be done |
Get cop form question
The endpoint that will get a cop form question
curl -X GET \
https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 200
{
"data": {
"id": "1",
"type": "text",
"attributes": {
"position": 1,
"title": "Are there any other initiatives that your company is taking to address Environment?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
{
"id": "1",
"type": "selectable_choice"
},
{
"id": "2",
"type": "selectable_choice"
},
{
"id": "3",
"type": "selectable_choice"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/2",
"next_question": "",
"prev_question": "",
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
"included": [
{
"id": "1",
"type": "form_category",
"attributes": {
"position": 1,
"title": "Environment",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
]
}
}
},
{
"id": "1",
"type": "selectable_choice",
"attributes": {
"position": 5,
"title": "We conduct specialized training on policies and procedures concerning aspects of human rights that are relevant to the company's operations",
"details_required": null,
"value": "conduct_human_rights_trainings"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "2",
"type": "selectable_choice",
"attributes": {
"position": 6,
"title": "We have operational guidance notes",
"details_required": null,
"value": "human_rights_guidance_notes"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "3",
"type": "selectable_choice",
"attributes": {
"position": 7,
"title": "Gender equality is embedded into our corporate sustainability strategy",
"details_required": null,
"value": "human_rights_gender_equality"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
}
]
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1
Filtering
You can filter a cop question using the following:
| Parameter | Required | Filter Values | Description |
|---|---|---|---|
| filter | false | N/A | Object specifying how to filter the result set. |
| filter[goals] | false | true/false | Include only child questions that have an associated goal. |
Get cop form category
The endpoint that will get a cop form category
curl -X GET \
https://prod-cop-api.herokuapp.com/v1/cops/1/categories/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 200
{
"data": {
"id": "1",
"type": "form_category",
"attributes": {
"position": 1,
"title": "General",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "1",
"type": "upload"
},
{
"id": "2",
"type": "multiple_choice"
}
]
}
}
},
"included": [
{
"id": "1",
"type": "upload",
"attributes": {
"position": 1,
"title": "Upload the COP statement",
"answered": false,
"response_type": "Answer"
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "1",
"type": "selectable_choice",
"attributes": {
"position": 1,
"title": "CEO",
"details_required": null,
"value": "ceo"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/v1/goals"
}
},
{
"id": "2",
"type": "selectable_choice",
"attributes": {
"position": 2,
"title": "Board of Directors",
"details_required": null,
"value": "board_of_directors"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/v1/goals"
}
},
{
"id": "3",
"type": "selectable_choice",
"attributes": {
"position": 3,
"title": "Corporate Responsibility or Ethics officer",
"details_required": null,
"value": "corporate_responsibility_or_ethics_officer"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/v1/goals"
}
},
{
"id": "2",
"type": "multiple_choice",
"attributes": {
"position": 2,
"title": "At what levels within your company are corporate responsibility policies and strategies developed and/or evaluated? Select all that apply:",
"answered": false,
"response_type": "Answer",
"choices_limit": null
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
{
"id": "1",
"type": "selectable_choice"
},
{
"id": "2",
"type": "selectable_choice"
},
{
"id": "3",
"type": "selectable_choice"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/2",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
}
]
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/cops/1/categories/1
Get cop goals
The endpoint that will get only cop questions that's have goals
curl -X GET \
https://prod-cop-api.herokuapp.com/v1/cops/1/goals \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 200
{
"data": {
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 0,
"completed_percent_target": 0,
"level": "submitted",
"status": "draft",
"visibility": "public",
"external_survey_link": null,
"name": "COP-2020",
"goals_count": 1,
"questions_count": 2,
"answered_questions": 0,
"signature_request_completed": false,
"external_id": null,
"publish_date": null,
"type": "qualtrics_submission",
"submission_period_year": 2024
},
"relationships": {
"form": {
"data": {
"id": "1",
"type": "form"
}
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1",
"current_question": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"current_category": "https://prod-cop-api.herokuapp.com/v1/cops/1/categories/1",
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
},
"included": [
{
"id": "4",
"type": "selectable_choice",
"attributes": {
"position": 1,
"title": "Board discusses and acts on these issues as part of regular agenda",
"details_required": null,
"value": "board_part_of_regular agenda"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "5",
"type": "selectable_choice",
"attributes": {
"position": 2,
"title": "Board addresses these issues from time to time, as needed",
"details_required": null,
"value": "board_time_to_time"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "6",
"type": "selectable_choice",
"attributes": {
"position": 3,
"title": "Board does not address corporate responsibility issues ",
"details_required": null,
"value": "board_does_not_address"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "1",
"type": "goal",
"attributes": {
"value": "board_time_to_time",
"notes": "notes",
"target_date": "2020-06-02T00:00:00+00:00"
}
},
{
"id": "3",
"type": "single_choice",
"attributes": {
"position": 1,
"title": "How often does your company’s Board of Directors (or equivalent*) address corporate responsibility issues?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
{
"id": "1",
"type": "goal"
}
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
{
"id": "4",
"type": "selectable_choice"
},
{
"id": "5",
"type": "selectable_choice"
},
{
"id": "6",
"type": "selectable_choice"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "2",
"type": "form_category",
"attributes": {
"position": 2,
"title": "Human Rights",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "3",
"type": "single_choice"
}
]
}
}
},
{
"id": "2",
"type": "form_module",
"attributes": {
"position": 2,
"title": "Human Rights",
"questions_count": 2,
"answered_questions": 0,
"background_color": "#FFFFFF"
},
"relationships": {
"form_categories": {
"data": [
{
"id": "2",
"type": "form_category"
}
]
}
}
},
{
"id": "1",
"type": "form",
"attributes": {
"name": "Test form"
},
"relationships": {
"form_modules": {
"data": [
{
"id": "2",
"type": "form_module"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1"
}
}
]
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/cops/1/goals
Filtering
You can filter cops form questions by the following attributes: tag.
| Parameter | Required | Description |
|---|---|---|
| filter | false | Object specifying how to filter the result set. |
| filter[attribute] | true | Specifies the attribute on which the filtering will be done |
Create a cop
The endpoint that will create a cop with the current active form.
curl -X POST https://prod-cop-api.herokuapp.com/v1/cops \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "cop",
"attributes": {
"visibility": "{visibility}"
},
"relationships": {
}
}
}'
Request example
{
"data": {
"type": "cop",
"attributes": {
"visibility": "{visibility}"
},
"relationships": {
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 0,
"completed_percent_target": 100,
"level": "submitted",
"status": "draft",
"visibility": "public",
"external_survey_link": null,
"name": "2023 Communication on progress",
"goals_count": 0,
"questions_count": 42,
"answered_questions": 0,
"signature_request_completed": false,
"external_id": null,
"publish_date": null,
"type": "early_adopter",
"submission_period_year": 2022
},
"relationships": {
"form": {
"data": {
"id": "1",
"type": "form"
}
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1",
"current_question": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"current_category": "https://prod-cop-api.herokuapp.com/v1/cops/1/categories/1",
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/cops
Payload
Payload must be a JSON Api object with the type cop and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| form | Form | true | The form relationship |
| visibility | String | false | The cop visiblity |
CopVisibility
| Value | Description |
|---|---|
| public | The default cop visibility on cop creation |
| private | Mark a cop as not available to the public |
Create a cop placeholder
This endpoint will allow the creation of an placeholder published COP.
curl -X POST https://prod-cop-api.herokuapp.com/v1/cops/placeholder \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "cop",
"attributes": {
"external_id": "42",
"level": "{level}",
"visibility": "{visibility}"
}
}
}'
Request example
{
"data": {
"type": "cop",
"attributes": {
"external_id": "42",
"level": "{level}",
"visibility": "{visibility}"
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 0,
"completed_percent_target": 0,
"level": "submitted",
"status": "published",
"visibility": "public",
"external_survey_link": null,
"name": "2023 Communication on progress",
"goals_count": 0,
"questions_count": 0,
"answered_questions": 0,
"signature_request_completed": false,
"external_id": "",
"publish_date": "2024-06-16T00:00:00.000+00:00",
"type": "mendix_submission",
"submission_period_year": 2023
},
"relationships": {
"form": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1",
"current_question": null,
"current_category": null,
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/cops/placeholder
Payload
Payload must be a JSON Api object with the type cop and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| external_id | String | true | The external resource id |
| visibility | CopVisibility | false | The cop visiblity |
CopVisibility
| Value | Description |
|---|---|
| public | The default cop visibility on cop creation |
| private | Mark a cop as not available to the public |
Update cop
The endpoint that will update a cop.
curl -X PATCH https://prod-cop-api.herokuapp.com/v1/cops/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "cop",
"id": "1",
"attributes": "{attributes}:non-string"
}
}'
Request example
{
"data": {
"type": "cop",
"id": "1",
"attributes": "{attributes}:non-string"
}
}
Response 200
{
"data": {
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 100,
"completed_percent_target": 0,
"level": "submitted",
"status": "draft",
"visibility": "public",
"external_survey_link": null,
"name": "COP-2020",
"goals_count": 0,
"questions_count": 2,
"answered_questions": 0,
"signature_request_completed": true,
"external_id": null,
"publish_date": null,
"type": "early_adopter",
"submission_period_year": 2022
},
"relationships": {
"form": {
"data": {
"id": "1",
"type": "form"
}
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1",
"current_question": "https://prod-cop-api.herokuapp.com/v1/cops/1/questions/1",
"current_category": "https://prod-cop-api.herokuapp.com/v1/cops/1/categories/1",
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
}
}
HTTP Request
PATCH https://prod-cop-api.herokuapp.com/v1/cops/1
Payload
Payload must be a JSON Api object with the type cop and attributes defined as below.
Attributes (all optional)
| Parameter | Type | Description |
|---|---|---|
| status | CopStatus | The cop status |
| visibility | CopVisibility | The cop visibility |
CopStatus
| Value | Description |
|---|---|
| published | Mark the cop as done and publish it |
CopVisibility
| Value | Description |
|---|---|
| public | The default cop visibility on cop creation |
| private | Mark a cop as not available to the public |
Delete a cop
The endpoint that will delete a cop.
curl -X DELETE https://prod-cop-api.herokuapp.com/v1/cops/1 \
-H 'Content-Type: application/vnd.api+json'
Response 204
HTTP Request
DELETE https://prod-cop-api.herokuapp.com/v1/cops/1
Reset cop signature
The endpoint that will reset the cop signature.
curl -X POST https://prod-cop-api.herokuapp.com/v1/cops/12/reset_signature \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 204
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/cops/12/reset_signature
Cops V2
Get a cop V2
The endpoint that will get a cop.
curl -X GET https://prod-cop-api.herokuapp.com/v2/cops/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 200
{
"data": {
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 0,
"completed_percent_target": 100,
"level": "submitted",
"status": "draft",
"visibility": "public",
"external_survey_link": "http://survey-link-example.com?cop_id=1&organization_id=0",
"name": "2024 Communication on progress",
"goals_count": 0,
"questions_count": 0,
"answered_questions": 0,
"signature_request_completed": false,
"external_id": null,
"publish_date": null,
"type": "qualtrics_submission",
"submission_period_year": 2024
},
"relationships": {
"form": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1",
"current_question": null,
"current_category": null,
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
}
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v2/cops/1
Create a cop V2
The endpoint that will create a cop.
curl -X POST https://prod-cop-api.herokuapp.com/v2/cops \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "cop",
"attributes": {
"visibility": "public"
}
}
}'
Request example
{
"data": {
"type": "cop",
"attributes": {
"visibility": "public"
}
}
}
Response 202 Accepted
{
"data": {
"id": "42",
"type": "job",
"attributes": {
"status": "{status}"
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/jobs/42"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v2/cops
Payload
Payload must be a JSON Api object with the type cop and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| visibility | String | false | The cop visiblity |
CopVisibility
| Value | Description |
|---|---|
| public | The default cop visibility on cop creation |
| private | Mark a cop as not available to the public |
Update cop V2
The endpoint that will update a cop.
curl -X PATCH https://prod-cop-api.herokuapp.com/v2/cops/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "cop",
"id": "1",
"attributes": {
"status": "published",
"visibility": "public",
"external_id": "42",
"external_survey_link": "http://external.com/survey/42"
}
}
}'
Request example
{
"data": {
"type": "cop",
"id": "1",
"attributes": {
"status": "published",
"visibility": "public",
"external_id": "42",
"external_survey_link": "http://external.com/survey/42"
}
}
}
Response 200
{
"data": {
"id": "1",
"type": "cop",
"attributes": {
"completed_percent": 100,
"completed_percent_target": 0,
"level": "submitted",
"status": "published",
"visibility": "public",
"external_survey_link": "http://external.com/survey/42",
"name": "2024 Communication on progress",
"goals_count": 0,
"questions_count": 0,
"answered_questions": 0,
"signature_request_completed": false,
"external_id": "42",
"publish_date": "2024-06-16T00:00:00.000+00:00",
"type": "qualtrics_submission",
"submission_period_year": 2024
},
"relationships": {
"form": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/cops/1",
"current_question": null,
"current_category": null,
"guidebook": "https://unglobalcompact.org/guidebook.pdf"
}
}
}
HTTP Request
PATCH https://prod-cop-api.herokuapp.com/v2/cops/1
Payload
Payload must be a JSON Api object with the type cop and attributes defined as below.
Attributes (all optional)
| Parameter | Type | Description |
|---|---|---|
| status | CopStatus | The cop status |
| visibility | CopVisibility | The cop visibility |
| external_id | Ext Reference | The external reference of the survey/responses |
| external_survey_link | Url | The external survey link |
CopStatus
| Value | Description |
|---|---|
| published | Mark the cop as done and publish it |
CopVisibility
| Value | Description |
|---|---|
| public | The default cop visibility on cop creation |
| private | Mark a cop as not available to the public |
Documents
Create a document
The endpoint that will create a document.
curl -X POST https://prod-cop-api.herokuapp.com/v1/documents \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "document",
"attributes": {
"name": "New Document",
"mime_type": "application/pdf"
},
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "1"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "document",
"attributes": {
"name": "New Document",
"mime_type": "application/pdf"
},
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "1"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "document",
"attributes": {
"name": "Document name",
"url": "https://storage.com/Document%20name.pdf",
"upload_link": "https://storage.com/upload/Document%20name.pdf",
"mime_type": "application/pdf"
},
"links": {
"update": "https://prod-cop-api.herokuapp.com/v1/documents/1",
"delete": "https://prod-cop-api.herokuapp.com/v1/documents/1"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/documents
Payload
Payload must be a JSON Api object with the type document and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| name | string | true | The document name |
| mime_type | MimeType | true | The mime type of the document |
| cop | Cop | true | The cop relationship |
| form_question | FormQuestion | true | The form_question relationship |
Mime Types
| Value | Description |
|---|---|
| application/pdf | The mime type for .pdf documents |
| application/msword | The mime type for .doc documents |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | The mime type for .docx documents |
| image/jpeg | The mime type for .jpg and .jpeg documents |
| image/png | The mime type for .png documents |
Upload document
After the document resource was created, an upload_link will be generated and provided to the client in POST https://prod-cop-api.herokuapp.com/v1/documents response.
The user should make a PUT request using the upload_link in order to upload the document in cloud.
curl -X PUT https://storage.com/upload/document-name.pdf \
-H 'Content-Type: application/pdf' \
-d data:image/jpeg;base64,<encoded-string>'
where
https://storage.com/upload/document-name.pdfis theupload_linkfromPOST https://prod-cop-api.herokuapp.com/v1/documentsresponse
Content-Typemust be the same with the one defined on the document creation.
HTTP Request
PUT https://storage.com/upload/document-name.pdf
Update document
The endpoint that will update a document.
curl -X PATCH https://prod-cop-api.herokuapp.com/v1/documents/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "document",
"id": "1",
"attributes": {
"name": "document-name"
}
}
}'
Request example
{
"data": {
"type": "document",
"id": "1",
"attributes": {
"name": "document-name"
}
}
}
Response 200
{
"data": {
"id": "1",
"type": "document",
"attributes": {
"name": "document-name",
"url": "https://storage.com/Document%20name.pdf",
"upload_link": "https://storage.com/upload/Document%20name.pdf",
"mime_type": "application/pdf"
},
"links": {
"update": "https://prod-cop-api.herokuapp.com/v1/documents/1",
"delete": "https://prod-cop-api.herokuapp.com/v1/documents/1"
}
}
}
HTTP Request
PATCH https://prod-cop-api.herokuapp.com/v1/documents/1
Payload
Payload must be a JSON Api object with the type document and attributes defined as below.
Attributes (all optional)
| Parameter | Type | Description |
|---|---|---|
| name | String | The document name |
Delete a document
The endpoint that will delete a document.
curl -X DELETE https://prod-cop-api.herokuapp.com/v1/documents/1 \
-H 'Content-Type: application/vnd.api+json'
Response 204
HTTP Request
DELETE https://prod-cop-api.herokuapp.com/v1/documents/1
Forms
Get form
The endpoint that will get a form
curl -X GET \
https://prod-cop-api.herokuapp.com/v1/forms/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
Response 200
{
"data": {
"id": "1",
"type": "form",
"attributes": {
"name": "Test form"
},
"relationships": {
"form_modules": {
"data": [
{
"id": "1",
"type": "form_module"
},
{
"id": "2",
"type": "form_module"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1"
}
},
"included": [
{
"id": "1",
"type": "upload",
"attributes": {
"position": 1,
"title": "Upload the COP statement",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "2",
"type": "multiple_choice",
"attributes": {
"position": 2,
"title": "At what levels within your company are corporate responsibility policies and strategies developed and/or evaluated? Select all that apply:",
"answered": false,
"response_type": "answer",
"choices_limit": null
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/2",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "1",
"type": "form_category",
"attributes": {
"position": 1,
"title": "General",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "1",
"type": "upload"
},
{
"id": "2",
"type": "multiple_choice"
}
]
}
}
},
{
"id": "1",
"type": "form_module",
"attributes": {
"position": 1,
"title": "Sustainability Governance",
"questions_count": 2,
"answered_questions": 0,
"background_color": "#FFFFFF"
},
"relationships": {
"form_categories": {
"data": [
{
"id": "1",
"type": "form_category"
}
]
}
}
},
{
"id": "3",
"type": "single_choice",
"attributes": {
"position": 1,
"title": "How often does your company’s Board of Directors (or equivalent*) address corporate responsibility issues?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/3",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "4",
"type": "numeric",
"attributes": {
"position": 2,
"title": "What is the number of complaints received regarding human rights?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/4",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "5",
"type": "percentage",
"attributes": {
"position": 3,
"title": "What percentage of employees received a regular performance and career development review?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/5",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "6",
"type": "text_area",
"attributes": {
"position": 4,
"title": "Are there any other initiatives that your company is taking to address Human Rights?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/6",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "7",
"type": "text",
"attributes": {
"position": 5,
"title": "Description of the organization’s values, principles, standards, and norms of behavior",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/7",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null,
"create_document": "https://prod-cop-api.herokuapp.com/v1/documents"
}
},
{
"id": "2",
"type": "form_category",
"attributes": {
"position": 2,
"title": "Human Rights",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "3",
"type": "single_choice"
},
{
"id": "4",
"type": "numeric"
},
{
"id": "5",
"type": "percentage"
},
{
"id": "6",
"type": "text_area"
},
{
"id": "7",
"type": "text"
}
]
}
}
},
{
"id": "2",
"type": "form_module",
"attributes": {
"position": 2,
"title": "Human Rights",
"questions_count": 2,
"answered_questions": 0,
"background_color": "#FFFFFF"
},
"relationships": {
"form_categories": {
"data": [
{
"id": "2",
"type": "form_category"
}
]
}
}
}
]
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/forms/1
Links
| Link | Description |
|---|---|
| self | A link to the object itself |
Create form
The endpoint to create a form, allowing to fill in responses in cop
curl -X POST https://prod-cop-api.herokuapp.com/v1/forms \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "form",
"attributes": {
"name": "{form_name}"
},
"relationships": {
"form_modules": {
"data": [
{
"type": "form_module",
"id": 1
},
{
"type": "form_module",
"id": 2
}
]
}
}
}
}'
Request example
{
"data": {
"type": "form",
"attributes": {
"name": "{form_name}"
},
"relationships": {
"form_modules": {
"data": [
{
"type": "form_module",
"id": 1
},
{
"type": "form_module",
"id": 2
}
]
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "form",
"attributes": {
"name": "Some form"
},
"relationships": {
"form_modules": {
"data": [
{
"type": "form_module",
"id": 1
},
{
"type": "form_module",
"id": 2
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1"
}
}
}
Payload
Payload must be a JSON Api object with the type of form.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| name | String | true | The of a form |
Get form question
The endpoint that will get a form question.
curl -X GET \
https://prod-cop-api.herokuapp.com/v1/forms/1/questions/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 200
{
"data": {
"id": "1",
"type": "text",
"attributes": {
"position": 1,
"title": "Are there any other initiatives that your company is taking to address Environment?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
}
},
"included": [
{
"id": "1",
"type": "form_category",
"attributes": {
"position": 1,
"title": "Environment",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "1",
"type": "text"
}
]
}
}
}
]
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/forms/1/questions/1
Get all forms
The endpoint that will get all forms
curl -X GET https://prod-cop-api.herokuapp.com/v1/forms \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
Response 200
{
"data": [
{
"id": "1",
"type": "form",
"attributes": {
"name": "Test form"
},
"relationships": {
"form_modules": {
"data": [
{
"id": "1",
"type": "form_module"
},
{
"id": "2",
"type": "form_module"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1"
}
}
],
"included": [
{
"id": "1",
"type": "upload",
"attributes": {
"position": 1,
"title": "Upload the COP statement",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/1",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "1",
"type": "selectable_choice",
"attributes": {
"position": 5,
"title": "We conduct specialized training on policies and procedures concerning aspects of human rights that are relevant to the company's operations",
"details_required": null,
"value": "conduct_human_rights_trainings"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "2",
"type": "selectable_choice",
"attributes": {
"position": 6,
"title": "We have operational guidance notes",
"details_required": null,
"value": "human_rights_guidance_notes"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "3",
"type": "selectable_choice",
"attributes": {
"position": 7,
"title": "Gender equality is embedded into our corporate sustainability strategy",
"details_required": null,
"value": "human_rights_gender_equality"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "2",
"type": "multiple_choice",
"attributes": {
"position": 2,
"title": "At what levels within your company are corporate responsibility policies and strategies developed and/or evaluated? Select all that apply:",
"answered": false,
"response_type": "answer",
"choices_limit": null
},
"relationships": {
"form_category": {
"data": {
"id": "1",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
{
"id": "1",
"type": "selectable_choice"
},
{
"id": "2",
"type": "selectable_choice"
},
{
"id": "3",
"type": "selectable_choice"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/2",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "1",
"type": "form_category",
"attributes": {
"position": 1,
"title": "General",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "1",
"type": "upload"
},
{
"id": "2",
"type": "multiple_choice"
}
]
}
}
},
{
"id": "1",
"type": "form_module",
"attributes": {
"position": 1,
"title": "Sustainability Governance",
"questions_count": 2,
"answered_questions": 0,
"background_color": "#FFFFFF"
},
"relationships": {
"form_categories": {
"data": [
{
"id": "1",
"type": "form_category"
}
]
}
}
},
{
"id": "1",
"type": "selectable_choice",
"attributes": {
"position": 5,
"title": "We conduct specialized training on policies and procedures concerning aspects of human rights that are relevant to the company's operations",
"details_required": null,
"value": "conduct_human_rights_trainings"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "2",
"type": "selectable_choice",
"attributes": {
"position": 6,
"title": "We have operational guidance notes",
"details_required": null,
"value": "human_rights_guidance_notes"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "3",
"type": "selectable_choice",
"attributes": {
"position": 7,
"title": "Gender equality is embedded into our corporate sustainability strategy",
"details_required": null,
"value": "human_rights_gender_equality"
},
"relationships": {
"choices": {
"data": [
]
}
},
"links": {
"create_goal": "https://prod-cop-api.herokuapp.com/goals"
}
},
{
"id": "3",
"type": "single_choice",
"attributes": {
"position": 1,
"title": "How often does your company’s Board of Directors (or equivalent*) address corporate responsibility issues?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
},
"choices": {
"data": [
{
"id": "1",
"type": "selectable_choice"
},
{
"id": "2",
"type": "selectable_choice"
},
{
"id": "3",
"type": "selectable_choice"
}
]
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/3",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "4",
"type": "numeric",
"attributes": {
"position": 2,
"title": "What is the number of complaints received regarding human rights?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/4",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "5",
"type": "percentage",
"attributes": {
"position": 3,
"title": "What percentage of employees received a regular performance and career development review?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/5",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "6",
"type": "text_area",
"attributes": {
"position": 4,
"title": "Are there any other initiatives that your company is taking to address Human Rights?",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/6",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null
}
},
{
"id": "7",
"type": "text",
"attributes": {
"position": 5,
"title": "Description of the organization’s values, principles, standards, and norms of behavior",
"answered": false,
"response_type": "answer"
},
"relationships": {
"form_category": {
"data": {
"id": "2",
"type": "form_category"
}
},
"references": {
"data": [
]
},
"tags": {
"data": [
]
},
"goals": {
"data": [
]
},
"goal_recommendations": {
"data": [
]
},
"responses": {
"data": [
]
},
"documents": {
"data": [
]
},
"note": {
"data": null
}
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/v1/forms/1/questions/7",
"next_question": null,
"prev_question": null,
"next_question_with_goal": null,
"prev_question_with_goal": null,
"create_document": "https://prod-cop-api.herokuapp.com/v1/documents"
}
},
{
"id": "2",
"type": "form_category",
"attributes": {
"position": 2,
"title": "Human Rights",
"completed": false
},
"relationships": {
"form_questions": {
"data": [
{
"id": "3",
"type": "single_choice"
},
{
"id": "4",
"type": "numeric"
},
{
"id": "5",
"type": "percentage"
},
{
"id": "6",
"type": "text_area"
},
{
"id": "7",
"type": "text"
}
]
}
}
},
{
"id": "2",
"type": "form_module",
"attributes": {
"position": 2,
"title": "Human Rights",
"questions_count": 2,
"answered_questions": 0,
"background_color": "#FFFFFF"
},
"relationships": {
"form_categories": {
"data": [
{
"id": "2",
"type": "form_category"
}
]
}
}
}
]
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/forms
Modules
Create module
The endpoint to create a module
curl -X POST https://prod-cop-api.herokuapp.com/v1/modules \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "module",
"attributes": {
"title": "Governance"
}
}
}'
Request example
{
"data": {
"type": "module",
"attributes": {
"title": "Governance"
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "module",
"attributes": {
"title": "Governance"
}
}
}
Payload
Payload must be a JSON Api object with the type of module.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| title | String | true | The title of the module |
Create a form module
The endpoint relationship a module to a form
curl -X POST https://prod-cop-api.herokuapp.com/v1/form_modules \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "form_module",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"module": {
"data": {
"type": "module",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "form_module",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"module": {
"data": {
"type": "module",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "form_module",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"module": {
"data": {
"type": "module",
"id": "1"
}
}
}
}
}
Payload
Payload must be a JSON Api object with the type of form_module.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| form | Form | true | The form relationship |
| module | Module | true | The module relationship |
| position | Integer | true | The position of the module in a form |
| backgroundColor | Hex | false | The form module background colour |
Categories
Create category
The endpoint to create a category
curl -X POST https://prod-cop-api.herokuapp.com/v1/categories \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "category",
"attributes": {
"title": "Prevention"
}
}
}'
Request example
{
"data": {
"type": "category",
"attributes": {
"title": "Prevention"
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "category",
"attributes": {
"title": "Prevention"
}
}
}
Payload
Payload must be a JSON Api object with the type of category.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| title | String | true | The title of the category |
Create a form category
The endpoint relationship a category to a form module
curl -X POST https://prod-cop-api.herokuapp.com/v1/form_categories \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "form_category",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"form_module": {
"data": {
"type": "form_module",
"id": "1"
}
},
"category": {
"data": {
"type": "category",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "form_category",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"form_module": {
"data": {
"type": "form_module",
"id": "1"
}
},
"category": {
"data": {
"type": "category",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "form_category",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"form_module": {
"data": {
"type": "form_module",
"id": "1"
}
},
"category": {
"data": {
"type": "category",
"id": "1"
}
}
}
}
}
Payload
Payload must be a JSON Api object with the type of form_category.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| form | Form | true | The form relationship |
| form_module | FormModule | true | The form module relationship |
| category | Category | true | The category relationship |
| position | Integer | true | The position of the category in a module |
Questions
Create question
The endpoint to create a question, the bread and butter of a form
curl -X POST https://prod-cop-api.herokuapp.com/v1/questions \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "question",
"attributes": {
"title": "Does the company have a publicly stated commitment regarding the following sustainability topics?",
"question_type": "single_choice"
}
}
}'
Request example
{
"data": {
"type": "question",
"attributes": {
"title": "Does the company have a publicly stated commitment regarding the following sustainability topics?",
"question_type": "single_choice"
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "single_choice",
"attributes": {
"title": "Does the company have a publicly stated commitment regarding the following sustainability topics?"
}
}
}
Payload
Payload must be a JSON Api object with the type of the question, see the table bellow for question types, and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| title | String | true | The title of the question |
| question_type | QuestionType | true | The question type |
QuestionTypes (refer to the COP team for a full description)
| Value | Description |
|---|---|
| text | |
| textarea | |
| numeric | |
| percentage | |
| single_choice | |
| multiple_choice | |
| question_set | |
| upload | |
| ratio | |
| polar | |
| matrix_single_choice | |
| matrix_multiple_choice |
Create a form question
The endpoint relationship a question to a form
curl -X POST https://prod-cop-api.herokuapp.com/v1/form_questions \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "form_question",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"question": {
"data": {
"type": "question",
"id": "1"
}
},
"form_category": {
"data": {
"type": "form_category",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "form_question",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"question": {
"data": {
"type": "question",
"id": "1"
}
},
"form_category": {
"data": {
"type": "form_category",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "form_question",
"attributes": {
"position": 3
},
"relationships": {
"form": {
"data": {
"type": "form",
"id": "1"
}
},
"question": {
"data": {
"type": "question",
"id": "1"
}
},
"form_category": {
"data": {
"type": "form_category",
"id": "1"
}
}
}
}
}
Payload
Payload must be a JSON Api object with the type of form_question.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| form | Form | true | The form relationship |
| question | Question | true | The quesiton relationship |
| form_category | FormCategory | true | The form_category relationship |
| position | Integer | true | The position of the question in a form category |
| choices_limit | Integer | false | The choice number limit for the multiple choice questions |
| additional_documents | Bool | false | Enables file upload for specific questions |
Choices
Create choice
The endpoint to create a choice, it will need to be connected to a question that has a type that requires choices
curl -X POST https://prod-cop-api.herokuapp.com/v1/choices \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "choice",
"attributes": {
"title": "Some title",
"value": "1",
"position": 1,
"choice_type": "selectable"
},
"relationships": {
"question": {
"data": {
"type": "question",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "choice",
"attributes": {
"title": "Some title",
"value": "1",
"position": 1,
"choice_type": "selectable"
},
"relationships": {
"question": {
"data": {
"type": "question",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "selectable_choice",
"attributes": {
"title": "Some title",
"value": "1",
"position": 1,
"details_required": null
},
"relationships": {
"question": {
"data": {
"type": "question",
"id": "1"
}
}
}
}
}
Payload
Payload must be a JSON Api object with the type choice and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| title | String | true | The title of the choice |
| question | Question | true | The question relationship |
| position | Integer | true | The position of the choice in the question |
| value | String | true | The value of the choice |
| details_required | String | false | Will mark the choice with the required additional details |
| choice_type | ChoiceType | false | The type of choice, see bellow table for a list |
| exclusive | Bool | false | Will make the choice exclusive inside the question |
ChoiceType
| Value | Description |
|---|---|
| selectable | A normal choice (default) |
| numeric | A choice that allows the user to fill a number |
| percentage | A choice that allows the user to fill a percentage |
| text | A choice that allows the user to fill a free text |
| textarea | A choice that allows the user to fill multiline free text |
| ratio | A choice that allows the user to fill in a ratio |
| collection | A choice that will allow the user open a collection |
Notes
Create a note
The endpoint that will create a note.
curl -X POST https://prod-cop-api.herokuapp.com/v1/notes \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "note",
"attributes": {
"value": "note"
},
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "{cop_id}"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "note",
"attributes": {
"value": "note"
},
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "{cop_id}"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "{id}",
"type": "note",
"attributes": {
"value": "note"
},
"links": {
"update": "https://prod-cop-api.herokuapp.com/v1/notes/{id}",
"delete": "https://prod-cop-api.herokuapp.com/v1/notes/{id}"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/notes
Payload
Payload must be a JSON Api object with the type note and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| value | string | true | The note value |
| cop | Cop | true | The cop relationship |
| form_question | FormQuestion | true | The form_question relationship |
Update note
The endpoint that will update a note.
curl -X PATCH https://prod-cop-api.herokuapp.com/v1/notes/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"id": "1",
"type": "note",
"attributes": {
"value": "note"
}
}
}'
Request example
{
"data": {
"id": "1",
"type": "note",
"attributes": {
"value": "note"
}
}
}
Response 200
{
"data": {
"id": "1",
"type": "note",
"attributes": {
"value": "note"
},
"links": {
"update": "https://prod-cop-api.herokuapp.com/v1/notes/1",
"delete": "https://prod-cop-api.herokuapp.com/v1/notes/1"
}
}
}
HTTP Request
PATCH https://prod-cop-api.herokuapp.com/v1/notes/1
Payload
Payload must be a JSON Api object with the type note and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| value | string | true | The note value |
Delete a note
The endpoint that will delete a note.
curl -X DELETE https://prod-cop-api.herokuapp.com/v1/notes/1 \
-H 'Content-Type: application/vnd.api+json'
Response 204
HTTP Request
DELETE https://prod-cop-api.herokuapp.com/v1/notes/1
Goals
Create a goal
The endpoint that will create a goal.
curl -X POST https://prod-cop-api.herokuapp.com/v1/goals \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "goal",
"attributes": {
"value": "goal-value",
"notes": "notes",
"target_date": "2020-06-02"
},
"relationships": {
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "goal",
"attributes": {
"value": "goal-value",
"notes": "notes",
"target_date": "2020-06-02"
},
"relationships": {
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "goal",
"attributes": {
"value": "goal-value",
"notes": "notes",
"target_date": "2020-06-02"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/goals
Payload
Payload must be a JSON Api object with the type goal and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| value | string | (only for multiple choice questions) | The goal value (the recommended goal will be used when no value is provided) |
| notes | string | false | Additional goal notes |
| target_date | date_time | false | The day by which the goal must be accomplished. Defaults to cop due date. |
| form_question | FormQuestion | true | The form_question relationship |
Update goal
The endpoint that will update a goal.
curl -X PATCH https://prod-cop-api.herokuapp.com/v1/goals/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"id": "1",
"type": "goal",
"attributes": {
"value": "new-value",
"notes": "some-notes",
"target_date": "2020-05-05"
}
}
}'
Request example
{
"data": {
"id": "1",
"type": "goal",
"attributes": {
"value": "new-value",
"notes": "some-notes",
"target_date": "2020-05-05"
}
}
}
Response 200
{
"data": {
"id": "1",
"type": "goal",
"attributes": {
"value": "new-value",
"notes": "some-notes",
"target_date": "2020-05-05"
}
}
}
HTTP Request
PATCH https://prod-cop-api.herokuapp.com/v1/goals/1
Payload
Payload must be a JSON Api object with the type goal and attributes defined as below.
Attributes (all optional)
| Parameter | Type | Description |
|---|---|---|
| value | string | The goal value |
| notes | string | Additional goal notes |
| target_date | date_time | The day by which the goal must be accomplished |
Delete a goal
The endpoint that will delete a goal.
curl -X DELETE https://prod-cop-api.herokuapp.com/v1/goals/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 204
HTTP Request
DELETE https://prod-cop-api.herokuapp.com/v1/goals/1
Responses
Create a response
The endpoint that will create a response.
curl -X POST https://prod-cop-api.herokuapp.com/v1/responses \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "response",
"attributes": {
"value": "response",
"details": "{details}"
},
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "1"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
},
"choice": {
"data": {
"type": "choice",
"id": "{choice_id}"
}
}
}
}
}'
Request example
{
"data": {
"type": "response",
"attributes": {
"value": "response",
"details": "{details}"
},
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "1"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
},
"choice": {
"data": {
"type": "choice",
"id": "{choice_id}"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "response",
"attributes": {
"value": "choice_value",
"details": "details"
},
"relationships": {
"cop": {
"data": {
"id": "1",
"type": "cop"
}
},
"choice": {
"data": {
"id": "1",
"type": "choice"
}
}
},
"links": {
"delete": "https://prod-cop-api.herokuapp.com/v1/responses/1"
}
},
"meta": {
"next_form_question_ids": [
]
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/responses
Payload
Payload must be a JSON Api object with the type response and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| value | array | true | The array with response values |
| cop | Cop | true | The cop relationship |
| form_question | FormQuestion | true | The form_question relationship |
Delete a response
The endpoint that will delete a response.
curl -X DELETE https://prod-cop-api.herokuapp.com/v1/responses/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 200
HTTP Request
DELETE https://prod-cop-api.herokuapp.com/v1/responses/:id
Delete responses
The endpoint that will delete all responses for a specific form question.
curl -X DELETE https://prod-cop-api.herokuapp.com/v1/responses \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "response",
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "1"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "response",
"relationships": {
"cop": {
"data": {
"type": "cop",
"id": "1"
}
},
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}
Response 200
HTTP Request
DELETE https://prod-cop-api.herokuapp.com/v1/responses
Payload
Payload must be a JSON Api object with the type response and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| cop | Cop | true | The cop relationship |
| form_question | FormQuestion | true | The form_question relationship |
Sessions
Create a session
The endpoint that will create a session.
curl -X POST https://prod-cop-api.herokuapp.com/v1/sessions \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "session",
"attributes": {
"access_token": "{access_token}",
"organization_id": 1
}
}
}'
Request example
{
"data": {
"type": "session",
"attributes": {
"access_token": "{access_token}",
"organization_id": 1
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "session",
"attributes": {
"token": "jwt-token"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/sessions
Payload
Payload must be a JSON Api object with the type session and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| organization_id | integer | false | The id of the organization |
| access_token | string | true | The token provided by the authorization server |
Signature
Fetch sign url
Fetch a fresh embedded sign url using a provided signature_id.
The sign url is to be used on the client to open the associated document signing iframe.
curl -X GET https://prod-cop-api.herokuapp.com/v1/signature/url?signature_id=6652ad9d9bee190de \
-H 'Authorization: jwt_token_you_get_after_create_session'
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/signature/url?signature_id=6652ad9d9bee190de
Response 200
{
"data": {
"id": "a9118e57-b2bc-4eae-b6ae-7f3b3d1155e7",
"type": "sign_url",
"attributes": {
"url": "https://app.hellosign.com/editor/embeddedSign?signature_id=abcd1234&token=abcd1234"
}
}
}
Fetch signature request
This endpoint will return the COP signature request.
curl -X GET https://prod-cop-api.herokuapp.com/v1/signature?cop_id=42 \
-H 'Authorization: jwt_token_you_get_after_create_session'
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/signature?cop_id=42
Response 200
{
"data": {
"id": "uuid",
"type": "signature",
"attributes": {
"signature_ids": [
"signature_id"
]
}
}
}
Get signature view file
This endpoint will return the signature view file as PDF.
curl -X GET https://prod-cop-api.herokuapp.com/v1/signature/view?cop_id=42 \
-H 'Authorization: jwt_token_you_get_after_create_session'
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/signature/view?cop_id=42
Response 200 (a PDF file will be returned as binary)
Tags
List available tags
The endpoint that list the available tags.
curl -X GET https://prod-cop-api.herokuapp.com/v1/tags \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 200
{
"data": [
{
"id": "1",
"type": "tag",
"attributes": {
"value": "later",
"name": "Later"
}
}
],
"meta": {
"available_tags": [
{
"name": "Later",
"value": "later"
},
{
"name": "Verification",
"value": "verification"
},
{
"name": "Bookmarked",
"value": "bookmarked"
}
]
}
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/tags
Create a tag
The endpoint that will create a tag.
curl -X POST https://prod-cop-api.herokuapp.com/v1/tags \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
-d '{
"data": {
"type": "tag",
"attributes": {
"value": "later"
},
"relationships": {
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}'
Request example
{
"data": {
"type": "tag",
"attributes": {
"value": "later"
},
"relationships": {
"form_question": {
"data": {
"type": "form_question",
"id": "1"
}
}
}
}
}
Response 201
{
"data": {
"id": "1",
"type": "tag",
"attributes": {
"value": "later",
"name": "Later"
}
}
}
HTTP Request
POST https://prod-cop-api.herokuapp.com/v1/tags
Payload
Payload must be a JSON Api object with the type tag and attributes defined as below.
Attributes
| Parameter | Type | Required? | Description |
|---|---|---|---|
| value | Tag | true | The tag value |
| form_question | FormQuestion | true | The form_question relationship |
Delete a tag
The endpoint that will delete a tag.
curl -X DELETE https://prod-cop-api.herokuapp.com/v1/tags/1 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session'
Response 204
HTTP Request
DELETE https://prod-cop-api.herokuapp.com/v1/tags/1
Submission periods
Get submission periods
The endpoint that will get the requested submission periods
curl -X GET https://prod-cop-api.herokuapp.com/v1/submission_periods \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: jwt_token_you_get_after_create_session' \
Response 200
{
"data": {
"id": "{id}",
"type": "submission_period",
"attributes": {
"year": 2023,
"start_date": "2023-02-03T00:00:00+00:00",
"due_date": "2023-02-03T23:59:59+00:00",
"end_date": "2023-02-03T23:59:59+00:00"
}
}
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v1/submission_periods
Filtering
You can filter submission periods by the following attributes: period.
| Parameter | Required | Description |
|---|---|---|
| filter | true | Object specifying how to filter the result set. |
| filter[attribute] | true | Specifies the attribute on which the filtering will be done |
| filter['next_year'] | true | Returns the submission period for the next year |
| filter['current'] | true | Returns the current submission period (404 if outside of the current submission period) |
Jobs
Get job
The endpoint that will get a job
curl -X GET \
https://prod-cop-api.herokuapp.com/v2/jobs/1 \
-H 'Content-Type: application/vnd.api+json'
Response 200
{
"data": {
"id": "42",
"type": "job",
"attributes": {
"status": "{status}"
},
"links": {
"self": "https://prod-cop-api.herokuapp.com/jobs/42"
}
}
}
HTTP Request
GET https://prod-cop-api.herokuapp.com/v2/jobs/1
Links
| Link | Description |
|---|---|
| self | A link to the object itself |
Errors
The UNGC COP API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The kitten requested is hidden for administrators only. |
| 404 | Not Found -- The specified kitten could not be found. |
| 405 | Method Not Allowed -- You tried to access a kitten with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 410 | Gone -- The kitten requested has been removed from our servers. |
| 418 | I'm a teapot. |
| 429 | Too Many Requests -- You're requesting too many kittens! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |