Welcome to the SAM APIv2
The documents can be accessed at https://apiv2docs.sam.org.au
These documents list all the endpoints on the left.
Clicking one of these will take you to the details for that endpoint and shows if it’s a GET, POST or PUT.
Below are a couple of examples of endpoints.
Two-way Communication - please be aware that you are now able to send sales that are created in an online store back to the art centre’s SAM Database. If you plan to use the SAM two-way communication component - please ensure that the art centre manager is aware that sales may be automatically generated in SAM based on those online sales. The online store sale prices can also override the prices in SAM if using the two-way communication.
GST – Items retrieved from the SAM API (Artworks & Prints) will display three prices. An exGST value, a GST amount and a Total price. GST is based on a number of factors. Some items will have GST applied, whereas others will not. In the case of items that do not have GST, the exGST will be the same as the Total, and the GST amount will be 0
Prints – Prints within SAM can have editions that effectively mean the same print/artwork appears as multiple records in SAM. The API will only return a maximum of one record for each edition. If an edition has multiple webactive prints then only 1 of these prints will be returned by the API. Once this is sold, the next print will appear in the edition until all webactive prints have been sold. A/P or P/P prints will show as a separate artwork in the online store.
Collaborations: - As with prints, collaborations are represented in SAM as multiple records, each with an individual artist and price. When returned via the API, these records will show as 1 artwork, the code will be eg. 24-20, though in SAM 24a-20 & 24b-20. In order to make a collaboration webactive, only one of the artworks in SAM needs to be webactive, however there is no issue with more than one being webactive. As long as one of the component artworks is webactive, all component artworks will be combined into a single artwork, tallying the price of all component artworks, and adding all artists to an array or artists that will be returned by the api.
Access Keys - these are the keys that are specific to an individual art centre’s data. If you need an access key to be deleted please contact email@example.com.
Product variations - SAM Database is being updated to allow for product variations. This update will be enabled through the SAM APIv2 soon.
Choosing The Right API:
This is important. Access keys are issued for a specific Art Centre. This Art Centre will either be in the SAM Live database or the SAM testing database.
If using a key for an Art Centre in the LIVE database, you will need to use the LIVE api.
If using a key for an Art Centre in the TEST database, you will need to use the TEST api.
This also applies to all request made through means other than the documentation site.
The next section of the doc provides a place to add authorisation. Doing this allows you to actually hit the api endpoints directly form the documentation and request data. These requests will be processed the same as any other request made to the API.
If you are using an access token (as opposed to getting a user token) you will need to set the authorisation type to Bearer.
Basically this means you will need to fill this field in as Bearer ********* (where ******* is the key that you have been provided).
After entering the Authorisation and clicking set, it should look something like the below screenshot.
Eg. Clicking on the Store:Artist “Get a list of artists” looks like the screenshot below.
The top line is the name of the endpoint. And the next line shows if it’s a GET, POST or PUT. (In this case it’s a GET endpoint) The second line also shows the URL to the endpoint.
So to access this endpoint, I need to send a GET request to https://apiv2.sam.org.au/store/artists.
The next section lists any query string or path parameters. For some endpoints these are mandatory, some they are optional, and others they are not available.
In this case nothing is needed (I’ll give another example that does require this, further down in these instructions.
Below this is the authorisation details as well as the option to run the query if authorisation has been provided.
So the above screenshot shows that I have added an API Key (Authorisation) in header. If I had not applied a key at the top of the page, it would display "No API key applied"
By having a Key setup, I can hit the TRY button to actually make the request with my API key.
Before I hit the TRY button, the response below will show example data. It shows the Schema (structure) of what keys and values will be returned.
Clicking the EXAMPLE tab will give me an example data set.
Because I have added an auth key, I can click the TRY button. This will then make the request for my actual data from my art centre.
Doing this, an actual response appears above the example response.
This response c contains data from my art centre. It also lists the Response headers if I click on the tab
I can also get a complete CURL request by clicking the CURL tab. (I have blurred the Authorisation Key in the below screenshot)
As mentioned above, some endpoints will require parameters to be passed.
Eg Clicking on the Store:Artist “Get an artists details” look like the screenshot below.
This is similar to getting the list of artists, but this request requires an id parameter which needs to be the id of the artist that you want details for.
So looking at our artist list endpoint, we can see that one of our artists had the id 1235784
If we enter that id into the id field and click TRY we get the following response: And we can see from the CURL tab the corresponding CURL request.
Updated 27th July 2021