# Get Result Report

:::{tip}
**API reference:**
{{ swagger_v2_link }}.
:::

Returns the **raw bytes of a PDF report** — the same document available from the
Results tab on the uCheck HR Platform. Save the response body to a `.pdf` file.
Authenticate with your unique organisation **key** in the JSON body.

## Overview

This document outlines the results report API included within the uCheck HR Platform, describing the API itself and the requirement that must be fulfilled to use this API.

This API returns in the body of the response the raw data of a pdf file. This is the same document you can download via the results tab on the uCheck HR Platform. This data can be saved to your calling server as a .pdf file.

Prior to use of either API endpoint, a company account must be setup and location IP address registered such that it can be entered into the uCheck firewall / used for logging requests.

One unique key will be supplied per organisation unit. You may be issued with many keys depending on the size of your company, you should check with your uCheck representative if you are unsure on this.

### Rate limiting

You may make **only one request at a time**; parallel requests are rejected with an error. Each request takes roughly 500–1500 ms to complete plus streaming time, depending on server load, report size and bandwidth. Repeat requests are throttled (see [Error responses](#error-responses)).

### Overview diagram

Below is a flow chart of the results report process.

```{mermaid}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'system-ui, -apple-system, Helvetica, Arial, sans-serif','fontSize':'15px','lineColor':'#f28e00','primaryColor':'#0094dd','primaryTextColor':'#ffffff','primaryBorderColor':'#112e51'}}}%%
flowchart TD
    A([Customer registers for the<br/>uCheck getResultReport API]):::endpoint
    B[Customer makes a JSON request<br/>to the API endpoint]:::step
    C([Customer receives the<br/>raw PDF report]):::endpoint
    A ==> B ==> C

    classDef endpoint fill:#112e51,stroke:#0094dd,stroke-width:2px,color:#ffffff,rx:8,ry:8;
    classDef step fill:#0094dd,stroke:#112e51,stroke-width:2px,color:#ffffff,rx:8,ry:8;
```

## Process explanation

- Customer registers with uCheck for the 'Result Report API

- Customer provides IP address(es) to be white listed

- Customer makes a JSON request including

  - Unique organization key

  - hrRef, the HR reference number the result report is for obtain by either the getResults or pushResults API

- A single raw pdf data output will be returned.

## Request format

| Property | Value |
|----------|-------|
| API URL endpoint | `https://api.ucheck.co.uk/getResultReport/v1` |
| Request type | `POST` |
| POST data required | Key = `json`, Value = JSON-encoded object with `key` and `hrRef` |

- Requests are raw 'POSTED' in the form of a JSON encoded string

- JSON request must include the following key pairs

  - key*: (Unique organization key)*

  - hrRef

i.e.

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "hrRef": "HR00000001"
}
```

NOTE: the above is example, the key is just for display and not a valid working one. You will be issued your own working key(s).

## Response format

- A successful request returns **HTTP 200**.
- The response body is the **raw bytes of the PDF report**, streamed back to your
  server. Write the body directly to a `.pdf` file.

:::{note}
The body is binary PDF data, not JSON. The source specification shows a partial
raw dump for illustration, which is not reproduced here.
:::

## Error responses

All error responses will be sent with an HTTP 400 Bad Request response header

### No JSON provided

```json
{
  "response": {
    "success": "false",
    "error": "no json data provided"
  }
}
```

You need to ensure you are providing json via a raw POST request

### Invalid key element

```json
{
  "response": {
    "success": "false",
    "error": "invalid key element supplied"
  }
}
```

The key element you have supplied is not valid. Please ensure you have been issued a valid key by uCheck and are not using a sample from this document are providing this correctly in your request.

### Element missing

```json
{
  "response": {
    "success": "false",
    "error": "element missing [hrRef]"
  }
}
```

Please ensure you are providing all elements are per the spec. The error will indicate which one it requires.

### Request rejected

```json
{
  "response": {
    "success": "false",
    "error": "request rejected, last request at 2018-07-24 03:31:27, requests can only be made every 600 seconds"
  }
}
```

You are trying to make a repeat result request too soon after the last successful request. You can only make result requests every 10 minutes.

### Company account disabled

```json
{
  "response": {
    "success": "false",
    "error": "company account disabled"
  }
}
```

The company account that is being used is not enabled for API use.