{"info":{"_postman_id":"b37733f7-e242-46c4-81d9-91643c7d4805","name":"Healthier Business Portal API V1","description":"

Healthier Business (HB) provides occupational health checks and online training for clients. Current portal processes require that candidates are added to the HB portal and that these candidates access the HB website to complete the necessary processes. This may require that candidate details held on client systems are rekeyed in the HB portal and that candidates log into both a client system and the portal to complete the required processing.
The API on the HB portal allows clients to integrate their internal systems with the portal in order to streamline this process as far as possible; provide two-directional communications between systems; keep the candidates on the client site where possible and offer feedback to the client system for monitoring the status of their candidates.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"24438176","collectionId":"b37733f7-e242-46c4-81d9-91643c7d4805","publishedId":"2s93m1ZQ5H","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-11-21T11:35:57.000Z"},"item":[{"name":"Candidate Requests","item":[{"name":"Get All Candidates","id":"9004d580-64bf-4a4c-8d79-38ed44dc1c86","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"accept":true}},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"API-Version","value":"1.0","type":"text"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"per_page","value":"10","type":"text","disabled":true}]},"url":"https://portal.hbcompliance.co.uk/api/candidates","description":"

This endpoint retrieves a list of all non-archived candidates.

The URI format is: https://hb-host.tld/api/candidates/
The request is HTTP GET (RFC2616).

This endpoint retrieves candidate data. The URI format is: https://hb-host.tld/api/candidates/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

The request is HTTP GET (RFC2616) and use candidate_ref as resource identifier,
which is a UUID string, identifying the candidate uniquely at HB.

First name

\n"},{"key":"last_name","value":"Last Name","description":"

Last Name

\n","type":"text"},{"key":"email","value":"email@domain.co.uk","description":"

E-mail address

\n","type":"text"},{"key":"client_record_ref","value":"Text","description":"

Foreign candidate identifier (at client)

\n","type":"text"},{"key":"consultant_name","value":"Text","description":"

Name of the consultant (at client)

\n","type":"text"},{"key":"activate_candidate","value":"1","description":"

Flag to activate the candidate at creation { 0 | 1 } default 0

\n","type":"text"},{"key":"archived","value":"0","description":"

Flag to show the archived state of the candidate { 0 | 1 } default 0

\n","type":"text"},{"key":"form_set","value":"","description":"

Comma-separated list of currently assigned form refs

\n","type":"text"},{"key":"return_email","value":"","description":"

Result e-mail address

\n","type":"text"},{"key":"send_activation_mail","value":"","description":"

Flag to ask HB backend to send the activation mail { 0 | 1 } default 1

\n","type":"text"},{"key":"clearance_type","value":"","description":"

Clearance Type { epp | non_epp }

\n","type":"text"},{"key":"job_role","value":"","description":"

Job Role

\n","type":"text"},{"key":"documents_required","value":"","description":"

Flag to indicate if candidate is required to submit documents with next the submission { 0 | 1 } default 0

\n","type":"text"},{"key":"document_list","value":"","description":"

List of documents required from the candidate in current submission; displayed to candidate in the portal; require

\n","type":"text"}]},"url":"https://portal.hbcompliance.co.uk/api/candidates","description":"

The request is HTTP POST (RFC 2616), application/x-www-form-urlencoded or multipart/form-data (RFC7578) and holds all the required details of the candidate.

If the operation was successful, the response message is HTTP 201 Created , application/json, holding a JSON string in the following format:
{ “response”: { “candidate_ref”:”XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” “candidate_id”:”” } }
where,
candidate_ref is a UUID string, identifying the candidate uniquely at HB.
candidate_id is an integer ID string, used internally by the portal to identify the candidate uniquely at HB when accessing candidate information via the portal.
If the candidate has already been created previously, based on matching email addresses, then the response should be HTTP 202 Accepted2 , and the message body should be the same as in case of HTTP 201 Created. The candidate details will not be updated in this case. The alternative candidate edit method should be used
instead.

First name 1

\n","disabled":true},{"key":"last_name","value":"Last Name","description":"

Last Name 2

\n","type":"text","disabled":true},{"key":"email","value":"email11@domain.co.uk","description":"

E-mail address

\n","type":"text"},{"key":"client_record_ref","value":"Text","description":"

Foreign candidate identifier (at client)

\n","type":"text"},{"key":"consultant_name","value":"Text","description":"

Name of the consultant (at client)

\n","type":"text"},{"key":"activate_candidate","value":"1","description":"

Flag to activate the candidate at creation { 0 | 1 } default 0

\n","type":"text"},{"key":"archived","value":"1","description":"

Flag to show the archived state of the candidate { 0 | 1 } default 0

\n","type":"text"},{"key":"form_set","value":"","description":"

Comma-separated list of currently assigned form refs

\n","type":"text"},{"key":"return_email","value":"","description":"

Result e-mail address

\n","type":"text"},{"key":"send_activation_mail","value":"","description":"

Flag to ask HB backend to send the activation mail { 0 | 1 } default 1

\n","type":"text"},{"key":"clearance_type","value":"","description":"

Clearance Type { epp | non_epp }

\n","type":"text"},{"key":"job_role","value":"","description":"

Job Role

\n","type":"text"},{"key":"documents_required","value":"","description":"

Flag to indicate if candidate is required to submit documents with next the submission { 0 | 1 } default 0

\n","type":"text"},{"key":"document_list","value":"","description":"

List of documents required from the candidate in current submission; displayed to candidate in the portal; require

\n","type":"text"}]},"url":"https://portal.hbcompliance.co.uk/api/candidates/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","description":"

The request is HTTP PATCH (RFC 5789), application/x-www-form-urlencoded or multipart/form-data (RFC7578) and holds the updated details of the candidate. This is a partial update call, which does not update every detail every time, only the modified ones. The available data fields are listed in Appendix 4.2.
If the operation was successful, the response message is HTTP 200 OK. If the request but the data was unchanged, the response message is HTTP 304 Unchanged. If the request cannot be processed due to misformatted or untranslatable data, the API should response with HTTP 400 Bad Request error.
If the candidate_ref is not valid then the API should response with HTTP 404 Not Found error.
If the request cannot be processed due to data validation errors, the API should respond with HTTP 403 Forbidden and an appropriate error response. (See section 3.6 Error responses).

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"API-Key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"b37733f7-e242-46c4-81d9-91643c7d4805","id":"b37733f7-e242-46c4-81d9-91643c7d4805","name":"Healthier Business Portal API V1","type":"collection"}},"urlObject":{"path":["candidates","XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"],"host":["https://portal.hbcompliance.co.uk/api"],"query":[],"variable":[]}},"response":[{"id":"4d3cfc29-3daa-419c-95cf-19166b827982","name":"Update Candidate Details","originalRequest":{"method":"PATCH","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"API-Version","value":"1.0","type":"text"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"first_name","value":"First Name","type":"text","description":"First name 1","disabled":true},{"key":"last_name","value":"Last Name","description":"Last Name 2","type":"text","disabled":true},{"key":"email","value":"email11@domain.co.uk","description":"E-mail address","type":"text"},{"key":"client_record_ref","value":"Text","description":"Foreign candidate identifier (at client) ","type":"text"},{"key":"consultant_name","value":"Text","description":"Name of the consultant (at client) ","type":"text"},{"key":"activate_candidate","value":"1","description":"Flag to activate the candidate at creation { 0 | 1 } default 0","type":"text"},{"key":"archived","value":"1","description":"Flag to show the archived state of the candidate { 0 | 1 } default 0","type":"text"},{"key":"form_set","value":"","description":"Comma-separated list of currently assigned form refs","type":"text"},{"key":"return_email","value":"","description":"Result e-mail address","type":"text"},{"key":"send_activation_mail","value":"","description":"Flag to ask HB backend to send the activation mail { 0 | 1 } default 1","type":"text"},{"key":"clearance_type","value":"","description":"Clearance Type { epp | non_epp }","type":"text"},{"key":"job_role","value":"","description":"Job Role","type":"text"},{"key":"documents_required","value":"","description":"Flag to indicate if candidate is required to submit documents with next the submission { 0 | 1 } default 0","type":"text"},{"key":"document_list","value":"","description":"List of documents required from the candidate in current submission; displayed to candidate in the portal; require","type":"text"}]},"url":"https://portal.hbcompliance.co.uk/api/candidates/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 19 May 2023 11:32:36 GMT"},{"key":"Server","value":"Apache"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Expires","value":"Sat, 26 Jul 1997 05:00:00 GMT"},{"key":"Cache-Control","value":"no-cache, no-store, must-revalidate, max-age=0, post-check=0, pre-check=0"},{"key":"Pragma","value":"no-cache"},{"key":"Set-Cookie","value":"hbc_csrf_cookie=7c7f6ef5ebedca58e77e5b7c52908071; expires=Fri, 19-May-2023 13:32:36 GMT; Max-Age=7200; path=/"},{"key":"Upgrade","value":"h2,h2c"},{"key":"Connection","value":"Upgrade, Keep-Alive"},{"key":"Last-Modified","value":"Fri, 19 May 2023 11:32:36 GMT"},{"key":"x-frame-options","value":"SAMEORIGIN"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"[\n \"\"\n]"}],"_postman_id":"3c7cf6d1-4aae-46b5-972d-cef9673be446"}],"id":"845abd7d-9518-4264-8e1d-912bad44d2ae","event":[{"listen":"prerequest","script":{"id":"dd17ff32-1330-4d42-82ca-09e23a6d5a78","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d11e3ec9-da5b-4518-80c5-f5192bf748ce","type":"text/javascript","exec":[""]}}],"_postman_id":"845abd7d-9518-4264-8e1d-912bad44d2ae","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"API-Key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"b37733f7-e242-46c4-81d9-91643c7d4805","id":"b37733f7-e242-46c4-81d9-91643c7d4805","name":"Healthier Business Portal API V1","type":"collection"}}},{"name":"Training Requests","item":[{"name":"Get Available Trainings","id":"c087fdaf-143f-482b-be4a-878ab9c84768","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"API-Version","value":"1.0","type":"text"}],"url":"https://portal.hbcompliance.co.uk/api/training-list/","description":"

The endpoint provides a method to retrieve the list of trainings provided by the authenticated client. The requests are HTTP GET (RFC2616) and uses api key as a resource identifier identifying the client uniquely at HB.

If there’s no trainings assigned to your account, the API should send an HTTP 204 No Content response.

The endpoint provides a method to retrieve the status of an individual course whether currently assigned or not. The requests are HTTP GET (RFC2616) and uses candidate_ref as a resource identifier identifying the candidate uniquely at HB and the course_id to identify the course for which the status is requested.

If the candidate_ref is unknown the response should be HTTP 404 Not Found.
If there’s no historical data from a previous assignment, the API should send an HTTP 204 No Content response.

NOTE: API will return all dates in GMT (UTC+0) timezone only.

The endpoint provides a method to retrieve status results for each course currently assigned to the candidate.

The requests are HTTP GET (RFC2616) and use candidate_ref as resource identifier, which is a UUID string, identifying the candidate uniquely at HB.

This endpoint is available to retrieve historical results for courses that are no longer assigned to the candidate.

The requests are HTTP GET (RFC2616) and use candidate_ref as resource identifier, which is a UUID string, identifying the candidate uniquely at HB.

The endpoint provides a method to retrieve the list of forms provided by the authenticated client. The requests are HTTP GET (RFC2616) and uses api key as a resource identifier identifying the
client uniquely at HB.

If there’s no forms assigned to your account, the API should send an HTTP 204 No Content response.

The endpoint provides a method to retrieve the list of forms fields for the perticular form_type provided by the authenticated client. The requests are HTTP GET (RFC2616) and uses api key as a resource identifier identifying the client uniquely at HB.

If there’s no forms assigned to your account, the API should send an HTTP 204 No Content response.

This endpoint can return a JSON response with the following data:

count: the total number of fields in this form
fields: a JSON body of fields which can contain the following data:
- field_id: This is the field ID, indicating the unique ID of that field.
- field_type: This is the field type, such as text, date, radio, checkbox, etc.
- field_name: This indicates the unique field name which the user needs to pass as form_data with a POST request for creating a new submission.
- field_label: This indicates the label of this field.
- validations: This is provided for your reference; you can validate the data on your side before posting it to the HB API.
- maxlength: The maximum number of characters allowed for this field.
- options: If your field type is radio, checkbox, or selectbox, you can find the options here in serialized format.
- sort_order: The sort order of this field (in ascending order).
- required: A boolean value indicating if the field is required or not.
- field_group: The group name to which this field belongs.
- fieldset: The label of that group name.
\n

Form type selected from list of available form_types

\n","type":"text"},{"key":"title","value":"","description":"

Title

\n","type":"text"},{"key":"first_name","value":"","description":"

First name

\n","type":"text"},{"key":"last_name","value":"","description":"

Last name

\n","type":"text"},{"key":"home_tel","value":"","description":"

Home telephone

\n","type":"text"},{"key":"work_tel","value":"","description":"

Work telephone

\n","type":"text"},{"key":"mobile_tel","value":"","description":"

Mobile telephone

\n","type":"text"},{"key":"dob","value":"","description":"

Date of birth

\n","type":"text"},{"key":"home_address_line_1","value":"","description":"

Address line 1

\n","type":"text"},{"key":"home_address_line_2","value":"","description":"

Address line 2

\n","type":"text"},{"key":"home_address_line_3","value":"","description":"

Address line 3

\n","type":"text"},{"key":"home_address_town","value":"","description":"

Town

\n","type":"text"},{"key":"home_address_county","value":"","description":"

County

\n","type":"text"},{"key":"home_address_postcode","value":"","description":"

Postcode

\n","type":"text"},{"key":"home_address_country","value":"","description":"

Country

\n","type":"text"},{"key":"gp_address_line_1","value":"","description":"

GP address line 1

\n","type":"text"},{"key":"gp_address_line_2","value":"","description":"

GP address line 2

\n","type":"text"},{"key":"gp_address_line_3","value":"","description":"

GP address line 3

\n","type":"text"},{"key":"gp_address_town","value":"","description":"

GP Town

\n","type":"text"},{"key":"gp_address_county","value":"","description":"

GP County

\n","type":"text"},{"key":"gp_address_postcode","value":"","description":"

GP Postcode

\n","type":"text"},{"key":"gp_address_country","value":"","description":"

GP Country

\n","type":"text"},{"key":"curr_illness_2","value":"","description":"

Candidate has illness / impairment / disability that may affect its work

\n","type":"text"},{"key":"prev_illness","value":"","description":"

Candidate had illness / impairment / disability that affect its work

\n","type":"text"},{"key":"treatment","value":"","description":"

Candidate has or waits for treatment or investigation at present

\n","type":"text"},{"key":"adjustments","value":"","description":"

Candidate needs help to do the job

\n","type":"text"},{"key":"mrsa","value":"","description":"

Candidate has/had Meticillin Resistant Staphylococcus Aureus (MRSA)

\n","type":"text"},{"key":"mrsa_date","value":"","description":"

Date of MRSA

\n","type":"text"},{"key":"cdiff","value":"","description":"

Candidate has/had Clostridium Difficile (C-Diff)

\n","type":"text"},{"key":"cdiff_date","value":"","description":"

Date of C-Diff

\n","type":"text"},{"key":"additional_information_6","value":"","description":"

Additional information for Medical Screening

\n","type":"text"},{"key":"chicken_pox","value":"","description":"

Candidate has/had Chicken Pox

\n","type":"text"},{"key":"chicken_pox_date","value":"","description":"

Date of Chicken Pox

\n","type":"text"},{"key":"bbv","value":"","description":"

Candidate comes into contact with any BVV

\n","type":"text"},{"key":"lived_outside_country","value":"","description":"

Candidate lived outside the UK in the last year

\n","type":"text"},{"key":"countries","value":"","description":"

Countries visited

\n","type":"text"},{"key":"bcg","value":"","description":"

Candidate had BCG vaccination

\n","type":"text"},{"key":"bcg_date","value":"","description":"

Date of BCG

\n","type":"text"},{"key":"cough","value":"","description":"

Candidate has cough that lasted for 3 weeks

\n","type":"text"},{"key":"weight_loss","value":"","description":"

Candidate has unexplained weight loss

\n","type":"text"},{"key":"fever","value":"","description":"

Candidate has unexplained fever

\n","type":"text"},{"key":"tuberculosis_2","value":"","description":"

Candidate had tuberculosis or been in recent contact with

\n","type":"text"},{"key":"additional_information_3","value":"","description":"

Additional information for Tuberculosis

\n","type":"text"},{"key":"Epp","value":"","description":"

Candidate’s role involves Exposure Prone Procedures

\n","type":"text"},{"key":"other_information","value":"","description":"

Other information

\n","type":"text"},{"key":"declaration","value":"","description":"

Declaration

\n","type":"text"},{"key":"declaration_name","value":"","description":"

Name – Auto generate from candidate name fields

\n","type":"text"},{"key":"declaration_date","value":"","description":"

Date – Auto generated timestamp

\n","type":"text"},{"key":"job_role","value":"","description":"

Job Role

\n","type":"text"},{"key":"clearance_type","value":"","description":"

Clearance Type

\n","type":"text"}]},"url":"https://portal.hbcompliance.co.uk/api/submission/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","description":"

This endpoint creates a new submission for a candidate at HB and initiates the screening process. The URI format is: https://hb-host.tld/api/submissions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX

If the request cannot be processed due to misformatted or untranslatable data, the API should response with HTTP 400 Bad Request error

If the candidate_ref is not valid then the API should response with HTTP 404 Not Found error.

If the request cannot be processed due to data validation errors, the API should respond with HTTP 403 Forbidden and an appropriate error response.

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"API-Key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"b37733f7-e242-46c4-81d9-91643c7d4805","id":"b37733f7-e242-46c4-81d9-91643c7d4805","name":"Healthier Business Portal API V1","type":"collection"}},"urlObject":{"path":["submission","XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"],"host":["https://portal.hbcompliance.co.uk/api"],"query":[],"variable":[]}},"response":[{"id":"a80ddd44-3aea-427f-8cd9-fb5a34a242b9","name":"Creating a new submission","originalRequest":{"method":"POST","header":[{"key":"API-Version","value":"1.0","type":"text"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"form_type","value":"","description":"Form type selected from list of available form_types","type":"text"},{"key":"title","value":"","description":"Title","type":"text"},{"key":"first_name","value":"","description":"First name","type":"text"},{"key":"last_name","value":"","description":"Last name","type":"text"},{"key":"home_tel","value":"","description":"Home telephone","type":"text"},{"key":"work_tel","value":"","description":"Work telephone","type":"text"},{"key":"mobile_tel","value":"","description":"Mobile telephone","type":"text"},{"key":"dob","value":"","description":"Date of birth","type":"text"},{"key":"home_address_line_1","value":"","description":"Address line 1","type":"text"},{"key":"home_address_line_2","value":"","description":"Address line 2","type":"text"},{"key":"home_address_line_3","value":"","description":"Address line 3","type":"text"},{"key":"home_address_town","value":"","description":"Town","type":"text"},{"key":"home_address_county","value":"","description":"County","type":"text"},{"key":"home_address_postcode","value":"","description":"Postcode","type":"text"},{"key":"home_address_country","value":"","description":"Country","type":"text"},{"key":"gp_address_line_1","value":"","description":"GP address line 1","type":"text"},{"key":"gp_address_line_2","value":"","description":"GP address line 2","type":"text"},{"key":"gp_address_line_3","value":"","description":"GP address line 3","type":"text"},{"key":"gp_address_town","value":"","description":"GP Town","type":"text"},{"key":"gp_address_county","value":"","description":"GP County","type":"text"},{"key":"gp_address_postcode","value":"","description":"GP Postcode","type":"text"},{"key":"gp_address_country","value":"","description":"GP Country","type":"text"},{"key":"curr_illness_2","value":"","description":"Candidate has illness / impairment / disability that may affect its work","type":"text"},{"key":"prev_illness","value":"","description":"Candidate had illness / impairment / disability that affect its work","type":"text"},{"key":"treatment","value":"","description":"Candidate has or waits for treatment or investigation at present","type":"text"},{"key":"adjustments","value":"","description":"Candidate needs help to do the job","type":"text"},{"key":"mrsa","value":"","description":"Candidate has/had Meticillin Resistant Staphylococcus Aureus (MRSA)","type":"text"},{"key":"mrsa_date","value":"","description":"Date of MRSA","type":"text"},{"key":"cdiff","value":"","description":"Candidate has/had Clostridium Difficile (C-Diff)","type":"text"},{"key":"cdiff_date","value":"","description":"Date of C-Diff","type":"text"},{"key":"additional_information_6","value":"","description":"Additional information for Medical Screening","type":"text"},{"key":"chicken_pox","value":"","description":"Candidate has/had Chicken Pox","type":"text"},{"key":"chicken_pox_date","value":"","description":"Date of Chicken Pox","type":"text"},{"key":"bbv","value":"","description":"Candidate comes into contact with any BVV","type":"text"},{"key":"lived_outside_country","value":"","description":"Candidate lived outside the UK in the last year","type":"text"},{"key":"countries","value":"","description":"Countries visited","type":"text"},{"key":"bcg","value":"","description":"Candidate had BCG vaccination","type":"text"},{"key":"bcg_date","value":"","description":"Date of BCG","type":"text"},{"key":"cough","value":"","description":"Candidate has cough that lasted for 3 weeks","type":"text"},{"key":"weight_loss","value":"","description":"Candidate has unexplained weight loss","type":"text"},{"key":"fever","value":"","description":"Candidate has unexplained fever","type":"text"},{"key":"tuberculosis_2","value":"","description":"Candidate had tuberculosis or been in recent contact with","type":"text"},{"key":"additional_information_3","value":"","description":"Additional information for Tuberculosis","type":"text"},{"key":"Epp","value":"","description":"Candidate’s role involves Exposure Prone Procedures","type":"text"},{"key":"other_information","value":"","description":"Other information","type":"text"},{"key":"declaration","value":"","description":"Declaration","type":"text"},{"key":"declaration_name","value":"","description":"Name – Auto generate from candidate name fields","type":"text"},{"key":"declaration_date","value":"","description":"Date – Auto generated timestamp","type":"text"},{"key":"job_role","value":"","description":"Job Role","type":"text"},{"key":"clearance_type","value":"","description":"Clearance Type","type":"text"}]},"url":"https://portal.hbcompliance.co.uk/api/submission/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\r\n \"response\": {\r\n \"submission_ref\":\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\"\r\n }\r\n}"}],"_postman_id":"e23998e4-a395-4585-ba2d-25b37f6841ad"},{"name":"Modifying the details of an existing submission (Upload Documents)","id":"666a8cdf-a6a3-4233-b41d-ddbbc8a3008d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[{"key":"API-Version","value":"1.0","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"file","value":"","type":"text"}]},"url":"https://portal.hbcompliance.co.uk/api/submissions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","description":"

This end point allows additional information to be added to a previously submitted submission. This is a partial update call, which does not update every detail every\ntime, only the modified ones. It will usually be in response to a request for additional\ninformation during the screening process.

The request is HTTP PATCH (RFC 5789), multipart/form-data (RFC7578) and holds the updated details of the submission and/or the files that serve as Proof of Immunity

If the operation was successful, the response message is HTTP 200 OK. If the request cannot be processed due to misformatted or untranslatable data, the API should response with HTTP 400 Bad Request error.

If the submission_ref is not valid then the API should response with HTTP 404 Not Found error.\nIf the request cannot be processed due to data validation errors, the API should respond with HTTP 403 Forbidden and an appropriate error response.

This end point allows to submit the form after uploading required documents.

The request is HTTP POST (RFC 2616), multipart/form-data (RFC7578) following with the submission reference.

If the submission_ref is not valid then the API should response with HTTP 404 Not Found error.
If the request cannot be processed due to data validation errors, the API should respond with HTTP 403 Forbidden and an appropriate error response.

The endpoint provides a method to retrieve a list of candidate form submissions in the last 90 days.
If the request is successful, the response message is HTTP 200 OK, If there are no submissions to report the API should send an HTTP 204 No Content response.

This endpoint retrieves the details of the finished screening operation.\nIf the request is successful, the response message is HTTP 200 OK, application/json, holding a JSON string in the following format:\nwhere,

status is a string, holding one of the following values to describe the status of the result:
\n
“pass” – certificate issued;
\n
“pass with restrictions” – certificate issued, though candidate restricted from working in certain roles/areas;
\n
“pass with recommendations” – certificate issued with recommended risk assessment/workstation etc.;
\n
“pass with advisory letters” – certificate issued with Hep B/TB advisory letters, etc.;
\n
“temporary clearance” – certificate issued, though cleared for a short time only;
\n
“fail” – candidate did not provide evidence of sufficient immunity;
\n
“other” – submission failed; HB screening process returns with optional information.
\n
information is a string, that holds additional information regarding the result of the submission. Typically, HB uses this to provide explanation or further details about the outcome of the screening process, like if the candidate is not contactable, or candidate requires further blood tests, etc.
\n
documents holds details of the status of each of the documents that are required in relation to the current submission. If documents are not required for the submission this tag is not populated:
\n
document_id is the document reference,
\n
document_status is the status of the document with values of either accepted or rejected
\n
document_information is additional information relating to the document in the case of status rejected indicating the reason the reason for rejection.
\n
result is holding details of the certificate (if certificate is available, otherwise this\ntag is not populated):
\n
clearance_level is the level of clearance of candidate,
\n
certificate_expire is the expiration date of the certificate.\nIf the screening process finished successfully the response is HTTP 200 OK. If the submission_ref is not valid then the API should respond with HTTP 404 Not Found error. If the screening process has not finished yet the response should be HTTP 202 Accepted without any other data.
\n

This endpoint retrieves the result document in PDF format that should be forwarded to the employer.

If the screening process finished successfully and the document is available, the response is an HTTP 200 OK, application/pdf or application/octet-stream and it wraps a binary data stream for the file content.
If the submission_ref is not valid then the API should response with HTTP 404 Not Found error.
If the screening process has not finished yet the response should be HTTP 202 Accepted without any other data.
If the candidate screening process did not result a downloadable certification, most likely because further information is required before the process can be completed, the API should send an HTTP 204 No Content response.

Assigned courses that have not expired [default]

Assigned courses including expired.

All courses including non-assigned courses, but excluding expired results.

All available results regardless of whether they’re assigned or expired.

The endpoint provides a method to retrieve a PDF training certificate for a candidate for an individual course.

The URI format is: https://hb-host.tld/api/training-results/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/certificate/course/{{course_id}}

The requests are HTTP GET (RFC2616) and use candidate_ref as resource identifier, which is a UUID string, identifying the candidate uniquely at HB.
If the candidate_ref is not valid then the API should response with HTTP 404 Not Found error.
If there is no certificate available for the course, the API should send an HTTP 204 No Content response.

The default certificate incudes entries for all assigned courses that have not expired.
If the candidate has completed at least one course that meets the selection criteria, the response is an HTTP 200 OK, application/pdf or application/octet-stream and it wraps a binary data stream for the file content.
If the candidate_ref is not valid then the API should response with HTTP 404 Not Found error.
If there are no results that meet the selected criteria for the certificate and as a result there’s no data to include on the certificate, the API should send an HTTP 204 No Content response.

\n","_postman_id":"fa9cb708-90db-4c72-bf58-af9e741cdab0","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"API-Key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"b37733f7-e242-46c4-81d9-91643c7d4805","id":"b37733f7-e242-46c4-81d9-91643c7d4805","name":"Healthier Business Portal API V1","type":"collection"}}},{"name":"Candidate FTW & Interview","item":[{"name":"Get Candidate FTW","id":"486f35a0-5306-42e9-ac07-97417852271a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"API-Version","value":"1.0","type":"text"}],"url":"https://portal.hbcompliance.co.uk/api/candidate-ftw/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","description":"

This API endpoint returns Fit to Work (FTW) details for a candidate, including:

Candidate ID & Reference: Unique identifiers for the candidate.
\n
Client ID: Identifies the associated client.
\n
FTW Document URL: Link to the Fit to Work document.
\n
FTW Upload Time: Timestamp of when the document was uploaded.
\n

It allows authorized users to retrieve FTW records for compliance and verification purposes.

This API endpoint provides interview outcome details for a candidate, including:

Candidate ID & Reference: Unique identifiers for the candidate.
\n
Client ID: Identifies the associated client.
\n
Interview Outcome: Indicates whether the candidate Attended or was a No Show.
\n
Interview Document URL: Link to the interview outcome document.
\n
Interview Upload Time: Timestamp of when the outcome was recorded.
\n

This API enables authorized users to track candidate interview attendance and access relevant documentation for compliance and record-keeping.

Our Candidate FTW (Fit to Work) and Interview APIs allow authorized users to retrieve critical candidate assessment details, including FTW document URLs, interview outcomes, and related documents. These APIs are designed to provide seamless access to essential hiring and compliance information.

Key Features:

FTW API: Retrieve the Fit to Work document URL for a specific candidate.
\n
Interview API: Access interview outcomes along with the related document, ensuring a smooth hiring process.
\n

Limited Availability:

These APIs are exclusively available upon request and must be explicitly enabled for your account. To activate access, please contact your designated account manager.

For further details or activation, reach out to our support team or your account manager.

\n","_postman_id":"558243ec-e879-4103-8119-bf8eee2c6e58","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"API-Key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"b37733f7-e242-46c4-81d9-91643c7d4805","id":"b37733f7-e242-46c4-81d9-91643c7d4805","name":"Healthier Business Portal API V1","type":"collection"}}},{"name":"Webhooks","item":[{"name":"Training Completion","id":"8a637c60-feb2-4b26-9dba-1d57934af589","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"description":"

Training Completion Webhook call will be sent each time when any of your candidates completes any assigned module from their assigned trainings.
This webhook will send a POST/PATCH request (whichever available with OPTIONS) with api-key & api-version headers and following raw json data.

{\n    \"training\": {\n        \"candidate_id\": \"XXXXX\",\n        \"candidate_ref\": \"XXXXX-XXXXXX-XXXXXX-XXXXXX\",\n        \"date_completed\": \"2013-11-22 14:45:48\",\n        \"renewal_date\": \"2014-11-22 14:45:48\",\n        \"courses_assigned_count\": \"50\",\n        \"courses_completed_count\": \"2\",\n        \"courses_pending_count\": \"1\",\n        \"courses_expired_count\": \"27\",\n        \"training_status\": \"incomplete\"\n    }\n}\n\n

Client can chain the other HB Api calls with this webhook requests.
For more example on Training Requests please refer Training Requests Section.

{\n    \"course\": {\n        \"candidate_ref\": \"a35691f0-12a0-4f3d-9b24-da8c5492a258\",\n        \"candidate_id\": \"XXXXXX\",\n        \"course_id\": \"7\",\n        \"course_name\": \"Health, Safety and Welfare\",\n        \"date_assigned\": \"2021-11-18 09:57:43\",\n        \"date_completed\": \"2021-12-01 01:42:59\",\n        \"renewal_date\": \"2022-12-01 01:42:59\",\n        \"course_status\": \"pass\",\n        \"grade\": 0.8\n    }\n}\n\n

Client can chain the other HB Api calls with this webhook requests.
For more example on Training Requests please refer Training Requests Section.

Form Completion Webhook call will be sent each time when any of your candidates completes & submit any assigned form.
This webhook will send a POST/PATCH request (whichever available with OPTIONS) with api-key & api-version headers and following raw json data.

{\n  \"form\": {\n    \"candidate_ref\": \"XXXX-XXXX-XXXX-XXXX\",\n    \"candidate_id\": \"XXXXXX\",\n    \"submission_id\": \"00000000\",\n    \"submission_ref\": \"XXXXXXXXXXX\",\n    \"form_type\": \"form_type\"\n  }\n}\n\n

Client can chain the other HB Api calls with this webhook requests.
For more example on OH Requests please refer OH Requests Section.

An \"FTW Uploaded\" webhook call will be triggered each time an FTW document is uploaded for a specific Occupational Health submission.
This webhook will send a POST/PATCH request (whichever available with OPTIONS) with api-key & api-version headers and following raw json data.

{\n  \"form\": {\n    \"candidate_ref\": \"XXXX-XXXX-XXXX-XXXX\",\n    \"candidate_id\": \"XXXXXX\",\n    \"submission_id\": \"00000000\",\n    \"submission_ref\": \"XXXXXXXXXXX\",\n    \"form_type\": \"form_type\"\n  }\n}\n\n

Client can chain the other HB Api calls with this webhook requests.
For more example on OH Requests please refer OH Requests Section.

*Note: This webhook call has limited availability and must be enabled by contacting your designated account manager.

An \"FTW Uploaded per candidate\" webhook call will be triggered each time an FTW document is uploaded for a specific Candidate.
This webhook will send a POST/PATCH request (whichever available with OPTIONS) with api-key & api-version headers and following raw json data.

{\n    \"ftw\": {\n      \"candidate_id\": \"XXXXXXX\",\n      \"candidate_ref\": \"XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX\",\n      \"client_id\": \"XXXXX\",\n      \"ftw_doc\": \"ftw-doc-url\",\n      \"ftw_upload_time\": \"2025-01-29 12:23:07\"\n    }\n}\n\n

Client can chain the other HB Api calls with this webhook requests.
For more example on Candidate Requests please refer Candidate Requests Section.

*Note: This webhook call has limited availability and must be enabled by contacting your designated account manager.

An \"Interview Outcome Uploaded per candidate\" webhook call will be triggered each time an Interview Outcome is uploaded for a specific Candidate.
This webhook will send a POST/PATCH request (whichever available with OPTIONS) with api-key & api-version headers and following raw json data.

{\n    \"interview\": {\n      \"candidate_id\": \"XXXXXXX\",\n      \"candidate_ref\": \"XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX\",\n      \"client_id\": \"XXXXX\",\n      \"interview_outcome\": \"Attended\",\n      \"interview_doc\": \"interview-outcome-doc-url\",\n      \"interview_upload_time\": \"2025-01-29 13:03:31\"\n    }\n}\n\n

Client can chain the other HB Api calls with this webhook requests.
For more example on Candidate Requests please refer Candidate Requests Section.

*Note: This webhook call has limited availability and must be enabled by contacting your designated account manager.

Circumventing the issues with the scenario when the client needs to poll an endpoint for the status of a particular candidate, the API should send a notification to the client about the finished process. This should trigger the call to the relevant endpoint. In this way the number of calls will be kept to a minimum.
The client will provide the endpoint URL for the callback. The candidate_ref will be used to identify the candidate to whom the callback relates.
The request is HTTP POST, application/json, and uses the same message body as
the relevant endpoint. If the candidate_ref is unknown the response should be HTTP 404 Not Found.
The response is HTTP 202 Accepted, if the client system understood the message
and initiated the process to retrieve the details from the API in a separated call.
If HTTP 202 Accepted is not received the callback will attempted again up to a maximum of three times or until a direct call is made to the endpoint – whichever comes first.

The Webhook uses TLS protected communication over HTTP. Requests using non-secured communication should be refused with HTTP 403 Forbidden and an appropriate error response error.
The Webhook endpoints should identify whether the incoming request comes from trusted source. For this reason a whitelist of trusted IP addresses should be maintained. If the incoming request does not come from a trusted IP address, the endpoint should refuse the connection with HTTP 403 Forbidden and an appropriate error response error.
HB will provide a second unique API key to the consumers of the API to authenticate Wekhooks. This second key differs from the API-Key used for authentication by API endpoints. The key is a UUID string, represents the identifier in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters.

The API key will be sent in the header of the HTTP request:
API-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The webhook uses this key to authenticate the sender. Requests that do not hold a valid key should be refused with HTTP 401 Unauthorized error.

\n","_postman_id":"e5002f11-e730-4d99-9f5a-7673546996cb","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"API-Key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"b37733f7-e242-46c4-81d9-91643c7d4805","id":"b37733f7-e242-46c4-81d9-91643c7d4805","name":"Healthier Business Portal API V1","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"API-Key"},{"key":"value","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"cff5262b-95a0-4a5b-ab72-c3d4abeaf8cf","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"907a319d-210b-448a-8e70-cd15759b8142","type":"text/javascript","exec":[""]}}],"variable":[{"key":"url","value":"https://portal.hbcompliance.co.uk/api","type":"string"},{"key":"api_version","value":"1.0","type":"string"},{"key":"candidate_ref","value":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},{"key":"form_type","value":"XXXXXXXXXX","type":"string"},{"key":"submission_ref","value":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","type":"string"}]}