Developer API

The Articheck API allows external systems and software to send report and artifact data into Articheck programatically.

The API expects all POST requests to be made with valid JSON.

 

Authentication

The API uses bearer tokens for authentication of all endpoints.

Prompt a user to login with their email address and password. The API will exchange these credentials for a token.

POST https://api.articheck.com/v2/auth-token/

Request

 {
     "username":  "email@email.com",
     "password": "12345"
 }

Response

 {
     "token": "affb305ae401117ff33392f6ccd634676e72f1ae"
 }

Use the token in every request using headers:

Authorization: Bearer affb305ae401117ff33392f6ccd634676e72f1ae

 

Upload an artifact

POST https://api.articheck.com/v2/reports/

  • id string required – the object ID from your external system
  • artifact_id int
  • title string required
  • media_template string required (see list of available values below)
  • artist string
  • alt_id string
  • alt_id2 string
  • date_of_creation string
  • dimensions string – 24 x 5.716 x 10 always in centimetres (height x width x depth). Use a decimal separator; commas like in 24,5 are not currently supported.
  • frame_dimensions string (like dimensions)
  • packed_dimensions string (like dimensions)
  • dimensions_notes string
  • groups list (see below)
  • general_conditions_category string
  • general_conditions_notes string
  • examination_location string
  • examined_by string
  • examiner_title string
  • lender string
  • image string – base64-encoded image (Note: images are never shown in the response)
  • image_2 string – base64-encoded image (Note: images are never shown in the response)
  • image_3 string – base64-encoded image (Note: images are never shown in the response)
  • complete boolean – only required when adding images using the “pictures” endpoint (see the next section)

Notes

  • All non-required string values can be left out of the request entirely or be an empty string (neither will be present in the update).
  • Up to three images can be uploaded for each report (you can upload more than three images using the images endpoint documented in the next section). Images are optional. Only those images sent in the request will be part of the new report; any existing images will be deleted during report creation.

Example request
Your data should be formatted in valid JSON.

{
    "id": "819",
    "title": "Testing public API",
    "media_template": "painting",
    "dimensions": "30 x 5 x 20",
    "examination_location": "Here",
    "examined_by": "Dan"
}

Example response

{
     "id": "819",
     "report_id": 5437,
     "artifact_id": 5427,
     "artifact_url": "https://portal.articheck.com/artifacts/5427",
     "pdf_url": "https://portal.articheck.com/reports/download/pdf/494fc2abefea4cdca8360feb27ec5627/5427_14AUG20_5437.pdf",
     "summary_pdf_url": "https://portal.articheck.com/reports/download/pdf/494fc2abefea4cdca8360feb27ec5627/5427_14AUG20_5437_summary.pdf"
     "updated_at": "1565699519",
     "updated_by": "dan@articheck.com",
     "created_at": "1565699519",
     "title": "Testing public API",
     "artist": "Unknown artist",
     "alt_id": null,
     "alt_id2": null,
     "alt_id3": "",
     "media": null,
     "date_of_creation": null,
     "groups": [],
     "dimensions": "30 x 5 x 20",
     "general_conditions_category": "",
     "general_conditions_notes": "Alright but a bit worse for wear.",
     "examination_location": "Here",
     "examined_by": "Dan",
     "examiner_title": "",
     "media_template": "Painting - Standard"
}

Add more than three images to a report

You may have an artifact which has more than three images. In this case,  you can make use of the “pictures” and “submit” endpoints.

Up to 100 images are accepted per report.

1. Create an incomplete report

The first step is to include a new complete value in the original request to /v2/reports/:

{
    ...
    "complete": false
}

This tells the system that the report is not yet finished so that it can accept image uploads.

2. Upload images

The second step is to upload images one by one to the “pictures” endpoint (using the report_id value returned in the report creation request).

POST https://api.articheck.com/v2/reports/[report_id]/pictures/

  • image string required – base64-encoded image
  • title string
  • created string – UNIX timestamp
Example request
Your data should be formatted in valid JSON.

{
    "image": "data:image/jpeg;base64,iVBORw0KAAAEAAAABAQAAAAA3bvkkA...",
    "title": "Front of sculpture"
}

3. Submit the incomplete report

Once all images have been uploaded, the final step is to “submit” the report.

POST https://api.articheck.com/v2/reports/[report_id]/submit/

No request body is required.

Successful submissions will return a HTTP 200 response with an empty body. If there is an issue (for example, lack of report credits) a HTTP 400 error will be returned, with an error message.

If an incomplete report is not submitted in this final step, it will not appear in Articheck.

Updating artifacts

If you need to update artifact data in Articheck, send data to the same endpoint as above and include either an artifact_id or id.

  • If artifact_id is used and matches an existing artifact in Articheck, a new report will be added to that artifact, merging all existing values plus those in the request.
  • If id (the ID from your external system) is used and artifact_id is not, the system will attempt to find an artifact with the same ID. A new report version of that artifact will be add if there is ONE matching artifact.
    Note that if your organisation has the “Unique report codes” setting turned ON, you will not be able to update artifacts with just the id field. In this case you have to use the artifact_id.

Important note about images in updates

When using the API, only images sent in an update request will be available in the new report. Any existing images for that artifact will be deleted and replaced with the new images you send over the API.

Adding to groups

groups should be a JSON list of objects. Reports will be added to every group listed in groups. Reports cannot currently be removed from groups over the API.

Groups will be added or updated within Articheck based on the code value you provide. If the code is already in use in Articheck, the group will be updated with any details sent in the request.

  • code string required
  • type string – empty string (defaults to general), general or exhibition
  • name string
  • description string

Exhibition groups have these extra fields:

  • start date required (YYYY-MM-DD format)
  • end date required (YYYY-MM-DD format)
  • venues string required

Example response

 {
   "examiner_title": "", 
   "general_conditions_category": "", 
   "updated_at": "1565790890", 
   "date_of_creation": null, 
   "alt_id": null, 
   "general_conditions_notes": "", 
   "media_template": "Painting - Standard", 
   "alt_id2": null, 
   "dimensions": null, 
   "title": "Testing report upload", 
   "media": null, 
   "updated_by": "test2@articheck.com", 
   "id": "71917", 
   "report_id": 18, 
   "artifact_id": 18, 
   "examination_location": "", 
   "groups": [
     {
       "code": "7", 
       "end": "2019-08-31", 
       "description": "Some description.", 
       "venues": "A location", 
       "start": "2019-07-01", 
       "type": "exhibition", 
       "id": 8, 
       "name": "New name"
     }
   ], 
   "alt_id3": "", 
   "artist": null, 
   "created_at": "1565790890",
   "examined_by": ""
 }

 

Media template values

Articheck has a defined list of templates that can be used to expose different fields in the condition report forms.

Whenever a report is added to Articheck over the API, a media template must be chosen (use an ID from below).

“Artwork / Object – Basic” artwork-object-basic
“Painting – Basic” painting-basic
“Painting – Standard” painting-standard
“Painting – Detailed” painting-detailed
“Paper – Basic” paper-basic
“Paper – Standard” paper-standard
“Paper – Detailed” paper-detailed
“Sculpture – Basic” sculpture-basic
“Sculpture – Standard” sculpture-standard
“Sculpture – Detailed” sculpture-detailed
“Object – Basic” object-basic
“Object – Standard” object-standard
“Object – Detailed” object-detailed
“Antique – Basic” antique-basic
“Antique – Detailed” antique-detailed
“Antique – Standard” antique-standard
“Inventory Item” inventory-item
“Textile – Detailed” textile-detailed
“Books, Manuscripts and Bound Materials” books
“Photograph” photograph