> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.morphiaone.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.morphiaone.ai/_mcp/server. # List colour Candidates GET https://api.morphiaone.ai/v1/digitisation/candidates Your candidates, newest first: the review queue. Repeat `review_status` (`pending`, `accepted`, `rejected`) to narrow the list, or send `assessment_id` for the candidates one assessment produced. Pages are chained with `next_cursor`, opaque and bound to this query's filters and to you: send it back with the same filters, or the answer is `400 INVALID_CURSOR`. An unknown or repeated parameter, and a filter value that is not valid, is `400 INVALID_REQUEST` naming it. Requires the `digitisation.read` scope, which your account operator provisions; served only where digitisation is enabled for your environment. Reference: https://docs.morphiaone.ai/api-reference/endpoints/digitisation/candidates-list ## Authentication - `X-API-Key` header (required) — API key for one environment of your account. Keep server-side; never expose in browser clients. ## Request ### Query parameters - `limit` (string, optional, nullable) — Page size, an integer 1-100 (default 20). - `cursor` (string, optional, nullable) — The previous page's `next_cursor`. - `review_status` (list of string, optional, nullable) — Only candidates in these review states (repeatable): `pending`, `accepted`, `rejected`. - `assessment_id` (string, optional, nullable) — Only the candidates measured by this assessment. ## Response ### 200 A page of the caller's candidates, newest first - `data` (list of DigitisationCandidate, required) - `has_more` (boolean, required) - `next_cursor` (string, required, nullable) ## Errors ### 400 Bad Request Error Invalid list parameter or cursor - `error` (ErrorDetail, required) ### 401 Unauthorized Error Missing or invalid API key - `error` (ErrorDetail, required) ### 403 Forbidden Error API key lacks the digitisation.read scope - `error` (ErrorDetail, required) ### 429 Too Many Requests Error Rate limited - `error` (ErrorDetail, required) ### 503 Service Unavailable Error Digitisation unavailable - `error` (ErrorDetail, required) ## Types ### DigitisationCandidate One candidate and its review. Its ``candidate`` never changes. - `assessment_id` (string, required) - `candidate` (map from string to any, required) - `candidate_sha256` (string, required) - `colour_contract_version` (integer, required) - `created_at` (datetime, required) - `derived_from_candidate_id` (string, required, nullable) - `fields` (map from string to CandidateField, required) - `id` (string, required) - `review_status` (enum, required) - Allowed values: `pending`, `accepted`, `rejected` - `reviewed_at` (datetime, required, nullable) - `review_url` (string, optional, nullable) - `reviewed_by` (ReviewActor, optional, nullable) — Who made a decision: ``user``, a person in the Platform, or ``api_key``. It names no person; the Platform shows who. ### ErrorDetail - `code` (string, required) - `message` (string, required) - `request_id` (string, required) - `details` (ErrorDetailDetails, optional) - `doc_url` (string, optional, nullable) - `retryable` (boolean, optional, nullable) ### CandidateField One field a candidate says: its status, and its value unless abstained. - `status` (enum, required) - Allowed values: `measured`, `abstained`, `edited` - `value` (string, optional, nullable) ### ReviewActor Who made a decision: ``user``, a person in the Platform, or ``api_key``. It names no person; the Platform shows who. - `type` (enum, required) - Allowed values: `user`, `api_key` ### ErrorDetailDetails - map from string to any - list of map from string to any ## Examples **Response** ```json { "data": [ { "assessment_id": "assessment_3t38gf4mbt0y96z8pzmp4w5mpq", "candidate": { "assessment_id": "assessment_3t38gf4mbt0y96z8pzmp4w5mpq", "assessment_output_sha256": "67b810e77d19f628534a2128d402605b8cc81aa1d43828793f2701f19ce8b97a", "colour_contract_version": 1, "kind": "digitisation.candidate", "report": { "analyzed_bytes_sha256": "9229dacfcfb7a93b54efccf2119c2e417546d10ed3fce2a18a067294b646c5a2", "clipped_fraction": 0, "colour_contract_version": 1, "icc_profile_sha256": null, "image": { "height": 64, "width": 64 }, "kind": "digitisation.colour_report", "lab_d65": [ 33.3028, 42.2729, -74.7134 ], "mean_linear_rgb": [ 0.012983, 0.045186, 0.57758 ], "region": [ 0, 0, 32, 32 ], "source_colour": "untagged", "srgb_hex": "#1E3CC8" }, "report_sha256": "13b9231215003368dc58598699f5aaf93c8b49b13561c1667aebbb065681110f", "source": { "analyzed_bytes_sha256": "9229dacfcfb7a93b54efccf2119c2e417546d10ed3fce2a18a067294b646c5a2", "evidence_id": "evidence_6952rp5rnjq4bpn9sk93vbq6pv", "region": [ 0, 0, 32, 32 ] } }, "candidate_sha256": "e1e9fdf2e1a9fe90712dad6a3247af7c4b6b6144d770a9070983f1d665fe71bb", "colour_contract_version": 1, "created_at": "2026-10-22T03:21:05.118204Z", "derived_from_candidate_id": null, "fields": { "display_color": { "status": "measured", "value": "#1E3CC8" }, "material.finish": { "status": "abstained", "value": null } }, "id": "candidate_5w2kq8n4fz7yr3tm6vx9bhcj1d", "review_status": "pending", "reviewed_at": null } ], "has_more": false, "next_cursor": null } ``` **SDK Code** ```python Digitisation_candidatesList_example import requests url = "https://api.morphiaone.ai/v1/digitisation/candidates" headers = {"X-API-Key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript Digitisation_candidatesList_example const url = 'https://api.morphiaone.ai/v1/digitisation/candidates'; const options = {method: 'GET', headers: {'X-API-Key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Digitisation_candidatesList_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.morphiaone.ai/v1/digitisation/candidates" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-API-Key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Digitisation_candidatesList_example require 'uri' require 'net/http' url = URI("https://api.morphiaone.ai/v1/digitisation/candidates") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-API-Key"] = '' response = http.request(request) puts response.read_body ``` ```java Digitisation_candidatesList_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.morphiaone.ai/v1/digitisation/candidates") .header("X-API-Key", "") .asString(); ``` ```php Digitisation_candidatesList_example request('GET', 'https://api.morphiaone.ai/v1/digitisation/candidates', [ 'headers' => [ 'X-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp Digitisation_candidatesList_example using RestSharp; var client = new RestClient("https://api.morphiaone.ai/v1/digitisation/candidates"); var request = new RestRequest(Method.GET); request.AddHeader("X-API-Key", ""); IRestResponse response = client.Execute(request); ``` ```swift Digitisation_candidatesList_example import Foundation let headers = ["X-API-Key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.morphiaone.ai/v1/digitisation/candidates")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```