Canopy's /answers API displays all fields of data held in the Supplier Profile for each supplier in Canopy.
It does not display any flags or status indicators about the supplier. Please refer to the /suppliers API if you require access to the status of the supplier record.
It also does not pull documents that have been uploaded to the Supplier Profile. Please refer to the /file API if you require access to this information.
The /answers API displays the fields of information held in the supplier record.
In this article you will learn:
GET data: Structure of the API call
GET data: How the data is displayed on the 'answersGET' request
Where to find the data dictionary
Which version of the data is displayed on the /answers API
POST data: Structure of the API call
POST data: How to use the 'answersPOST' request
For technical documentation, please following this link
GET data: Structure of the API call
The GET call using the /answers API will require the following components:
| URL | https://stage-api.canopy-sm.com/answers |
| x-api-key |
This is a unique key identifying your specific instance of Canopy Please ask your administrator to obtain this from the Canopy Support Team |
| showAll (optional) |
Includes all supplier records, including those that have never been published If this is not included, the API will only pull records of suppliers that have been published at least once |
| startId (optional) |
The UID of the first supplier record you would like to pull If this is not included, the API will pull all supplier records |
| startDate (optional) |
The earliest date when you would like to pull suppliers from, referring to the Last Updated Date in the format yyyy-MM-dd If this is not included, the API will pull all supplier records |
GET data: How the data is displayed on the 'answersGET' request
When browsing data on the Supplier Profile, data is referenced using the full Question Wording. Sometimes this wording is only a few words long, but often it can stretch to full sentences. This phrasing is too long to use for reporting purposes, so instead Canopy references each question using a Policy Title.
The information in the /answers API is referenced using the Policy Title. The Policy Title is a unique phrase given to each data point to help identify it for reporting purposes.
Below is an example of the information you will receive back when running the GET request on the /answers API:
{
"results":[
{
"UID":10003321,
"Company Name":"Acme Supplier Limited",
"Answer Groups":[
{
"UID":7305,
"Name":"Default",
"Group Name":"Default",
"Answers":{
"companyName": "Acme Supplier Limited",
"erpStatus": "Active",
"erpId":"SAP12345",
"geographicCoverageInArea": [
"Germany",
"Ireland",
"United Kingdom"
],
...
},
}
{
"UID": 7306,
"Name": "Banking Details",
"Group Name": "Banking Details",
"Answers": {
"primaryBankName": "HSBC",
"primaryBankCountry": "GBR",
"primaryBankCurrency": "GBP"
"primaryBankSwiftCode": "ABCDE12",
"ibanNumber": "GB12ABCD12345678901234",
"primaryBankAccountNumber": "12345678",
"primaryBankSortCode": "123456",
"primaryBankRemittanceEmail": "finance@acmelimited.com",
"primaryNameOnBankAccount": "Acme Supplier Limited",
}
}
]
},
// Next Supplier
]
}
As you can see from the example above, the field is named after the Policy Title.
To understand which question each Policy Title refers to, please consult the data dictionary which provides a mapping between Question Wording and Policy Titles for every data point in Canopy.
Where to find the data dictionary
The Question Set Export report provides a mapping between the Policy Title and Question Wording for every data point on the Supplier Profile. The Policy Title is used to identify each data point in the /answers API.
Click here to learn how to download the Question Set Export report for your instance of Canopy.
Which version of the data is displayed on the /answers API
The /answers API always provides the ‘best version’ of the data. If a supplier has been fully onboarded to Canopy, their ‘Published’ record is regarded as the best version of their profile, as this is the information that has been approved.
- If the supplier has been Published, the API will display the Published data
- If the supplier has never been Published, but has Submitted, the API will display the Submitted data
- If the Supplier has never been Published or Submitted, the API will display the Draft data
If a Published supplier makes a change to their profile, but that change has not been approved, the API will continue to display the Published version of the answer (i.e. the last approved version) until the supplier is re-published.
POST data: Structure of the API call
The POST call using the /answers API will require the following components:
| URL | https://stage-api.canopy-sm.com/answers |
| x-api-key |
This is a unique key identifying your specific instance of Canopy Please ask your administrator to obtain this from the Canopy Support Team |
| Content-Type |
This needs to be set to 'application/json' The JSON file format is outlined below For text fields: "Policy Title": "text you want to enter" For date fields: "Policy Title": "YYYY-MM-DD" For number fields: "Policy Title": 12345 |
POST data: How to use the 'answersPOST' request
You can use the API to update fields in Canopy over API. This is particularly useful for things like ERP IDs and ERP Status information.
Follow the steps below to send data to Canopy via the API using the 'answersPOST' request:
1. Create a JSON file using the following format:
{
"supplierId": ENTER THE UID OF THE SUPPLIER,
"groupId": ENTER THE UID OF THE DATA GROUPING CONTAINING THE FIELD(S) YOU WANT TO UPDATE,
"answers": {
"POLICY TITLE": "FIELD VALUE"
}
}
For example, if you wanted to update the ERP ID field for the supplier 'Acme Supplier Limited' used in the example above, the JSON file would look like this:
{
"supplierId": 10003321,
"groupId": 7305,
"answers": {
"erpId": "SAP12345"
}
}
2. Use the ‘answersPOST’ request to post the JSON file to https://api.canopy-sm.com/answers
The requested fields will automatically update on each of the Draft, Submitted and Published versions for the specified supplier. The POST request performs a hard replace, which means the action cannot be undone and will overwrite any pre-existing information contained in the field.
For more information about how to perform a POST request, please speak to your Administrator.