Human Resources

How to make requests and generate reports as a human resources client in the Certn API.

Demo Environment

When sending test data to the following endpoints, change the domain to https://demo-api.certn.co.

To view a list of all application parameters, visit Application parameters.

Applications

An application is a single request containing a variety of checks for one applicant. These endpoints allow you to create, upgrade, and retrieve the applications associated with your team.

Invite an applicant

POST https://api.certn.co/api/v1/hr/applications/invite/

Invite an applicant to complete a screen via email.

Provide information in the body of the request to pre-fill the application forms.

Request Body

application/json
{
  "id": string <uuid>,
  "created": string <date-time>,
  "modified": string <date-time>,
  "applicant": {
    "id": string <uuid>,
    "status": string <Enum>,
    "first_name": string,
    "last_name": string,
    "email": string,
    "phone_number": {
      "phone_type": string <Enum>,
      "number": string,
      "country": string <ISO Country Code>
    }
  }
}

Screen an applicant instantly

POST https://api.certn.co/api/v1/hr/applications/quick/

Screen an applicant using only the information in the body of your request.

Get the applicant's consent before running the screen.

Request Body

application/json
{
  "id": string <uuid>,
  "created": string <date-time>,
  "modified": string <date-time>,
  "tag": string,
  "(request_flags)": boolean 
  "last_updated": string <date-time>,
  "submitted_time": string <date-time>,
  "is_submitted": boolean,
  "applicant_type": string <Enum>,
  "report_status": string <Enum>,
  "status": string <Enum>,
  "status_label": string <Enum>,
  "result": string <Enum>,
  "result_label": string <Enum>,
  "certn_score": number,
  "certn_score_label": string <Enum>,
  "applicant_account": {
    "id": string,
    "email": string
  },
  "application": {
    object (Application) 
  },
  "country": "CA",
  "information": {
    object (Information)
  },
  "employment_verification": string <VerificationEnum>,
  "education_verification": string <VerificationEnum>,
  "credential_verification": string <VerificationEnum>,
  "reference_result": {
    object (BasePackageResult)
  },
  "information_result": {
    object (BasePackageResult)
  },
  "risk_result": {
    object (RiskResult)
  },
  "equifax_result": {
    object (EquifaxResult)
  },
  "identity_verified": boolean,
  "employment_verified": boolean,
  "identity_verification": {
    object (Identity Verification)
  },
  "enhanced_identity_verification": {
    object (EnhancedIdentityVerification)
  },
  "manual_id_verification": {
    object (ManualIDVerification)
  },
  "rcmp_result": {
    object (BasePackageResult)
  },
  "us_criminal_record_check_result": {
    object (USCriminalRecordCheckResult)
  },
  "verification_result": {
    object (VerificationResult)
  },
  "international_criminal_record_check_result": {
    object (BasePackageResult)
  },
  "motor_vehicle_record_result": {
    object (BasePackageResult)
  },
  "salary": number,
  "sufficient_salary": boolean,
  "high_risk_vulnerable_sector": boolean,
  "job_safety_undue_risk": boolean,
  "early_termination": number,
  "early_termination_label": string <Enum>,
  "reliability_risk": number,
  "reliability_risk_label": string <Enum>,
  "workplace_misconduct": number,
  "workplace_misconduct_label": string <Enum>
}

Upgrade an application

PUT https://api.certn.co/api/v1/hr/applicants/{applicant_id}/packages/

Add a screening request to an existing application.

To add screening requests to your application, wait for the report's status field to show Returned.

Path Parameters

Request Body

application/json
{
    "id": string < uuid > ,
    "created": string < date - time > ,
    "modified": string < date - time > ,
    "tag": string,
    "(request_flags)": boolean
    "last_updated": string < date - time > ,
    "submitted_time": string < date - time > ,
    "is_submitted": boolean,
    "applicant_type": string < Enum > ,
    "report_status": string < Enum > ,
    "status": string < Enum > ,
    "status_label": string < Enum > ,
    "result": string < Enum > ,
    "result_label": string < Enum > ,
    "certn_score": number,
    "certn_score_label": string < Enum > ,
    "applicant_account": {
        "id": string,
        "email": string
    },
    "application": {
        object(Application)
    },
    "country": "CA",
    "information": {
        object(Information)
    },
    "employment_verification": string < VerificationEnum > ,
    "education_verification": string < VerificationEnum > ,
    "credential_verification": string < VerificationEnum > ,
    "reference_result": {
        object(BasePackageResult)
    },
    "information_result": {
        object(BasePackageResult)
    },
    "risk_result": {
        object(RiskResult)
    },
    "equifax_result": {
        object(EquifaxResult)
    },
    "identity_verified": boolean,
    "employment_verified": boolean,
    "identity_verification": {
        object(Identity Verification)
    },
    "enhanced_identity_verification": {
        object(EnhancedIdentityVerification)
    },
    "manual_id_verification": {
        object(ManualIDVerification)
    },
    "rcmp_result": {
        object(BasePackageResult)
    },
    "us_criminal_record_check_result": {
        object(USCriminalRecordCheckResult)
    },
    "verification_result": {
        object(VerificationResult)
    },
    "international_criminal_record_check_result": {
        object(BasePackageResult)
    },
    "motor_vehicle_record_result": {
        object(BasePackageResult)
    },
    "salary": number,
    "sufficient_salary": boolean,
    "high_risk_vulnerable_sector": boolean,
    "job_safety_undue_risk": boolean,
    "early_termination": number,
    "early_termination_label": string < Enum > ,
    "reliability_risk": number,
    "reliability_risk_label": string < Enum > ,
    "workplace_misconduct": number,
    "workplace_misconduct_label": string < Enum >
}

Retrieve all your applications

GET https://api.certn.co/api/v1/hr/applicants/

View the details of all your applications.

The results are sent via paginated response, in chronological order. To retrieve the next page, send a request to the URL under the field next, or add one to your page counter:

https://api.certn.co/hr/v1/applicants/?page=<pgNum>

You can retrieve the final report for an application when its report_status field is marked as COMPLETE.

Query Parameters

application/json
{
    "count": int,
    "next": URL,
    "previous": URL,
    "results": [
        {
            "(request_flags)": boolean,
            "last_updated": string <date-time>,
            "id": string <uuid>,
            "short_uid": string,
            "report_status": string <Enum>,
            "information": {
                object(Information)
            },
            "applicant_account": {
                "id": string <uuid>,
                "email": string,
                "email_verified": boolean,
                "phone_number": string
            },
            "application": {
                object(Application)
            },
            "adjudication_status": string <Enum>,
            "adjudication_status_label": string <Enum>,
            "report_summary": {
                "reference_result": object(BasePackageResult),
                "australian_criminal_intelligence_commission_check_result": object(certificate_url),
                "rcmp_result": object(RCMPResult),
                "equifax_result": object(EquifaxResult),
                "information_result": object(BasePackageResult),
                "instant_verify_result": object(BasePackageResult),
                "international_criminal_record_check_result": object(InternationalCriminalRecordCheckResult),
                "motor_vehicle_record_result": object(MotorVehicleRecordResult),
                "social_media_check_result": object(SocialMediaCheckResult),
                "risk_result": object(RiskResult),
                "soquij_result": object(SoquijResult),
                "uk_basic_dbs_check_result": object(UKBasicDBSCheckResult),
                "uk_basic_ds_check_result": object(UKBasicDSCheckResult),
                "uk_right_to_work_check_result": object(UKRightToWorkResult),
                "us_criminal_record_check_result": object(USCriminalRecordCheckResult),
                "vaccination_check_result": object(BasePackageResult),
                "right_to_work_result": object(RightToWorkResult),
                "certn_verification": object(BasePackageResult),
                "report_result": string <Enum>,
                "report_result_label": string <Enum>,
                "dispute": boolean,
                "report_status": string <Enum>,
                "report_status_label": string <Enum>
            },
            "can_upgrade": boolean,
            "is_equifax_eligible": boolean,
            "can_resend_email": boolean,
            "resend_email_time": string <date-time>,
            "is_viewed": boolean,
            "onboarding_link": URL,
            "applicant_adjudication": null,
            "has_active_automated_reminders": boolean,
            "order_status": string <Enum>,
            "check_executions": [
                {
                    "id": "check_exec_ABcDefghIJKlmNOPQRsTUv",
                    "check_name": string,
                    "status": string <Enum>
                }
            ],
            "status": string <Enum>
        }
    ]
}

Retrieve an application

GET https://api.certn.co/api/v1/hr/applicants/{applicant_id}/

View the details of an application.

Check the status field to see if the application is done processing.

You can retrieve the final report when the report_status field is marked as COMPLETE.

Path Parameters

application/json
{
  "id": string <uuid>,
  "created": string <date-time>,
  "modified": string <date-time>,
  "tag": string,
  "(request_flags)": boolean 
  "last_updated": string <date-time>,
  "submitted_time": string <date-time>,
  "is_submitted": boolean,
  "applicant_type": string <Enum>,
  "report_status": string <Enum>,
  "status": string <Enum>,
  "status_label": string <Enum>,
  "result": string <Enum>,
  "result_label": string <Enum>,
  "certn_score": number,
  "certn_score_label": string <Enum>,
  "applicant_account": {
    "id": string,
    "email": string
  },
  "application": {
    object (Application) 
  },
  "country": "CA",
  "information": {
    object (Information)
  },
  "employment_verification": string <VerificationEnum>,
  "education_verification": string <VerificationEnum>,
  "credential_verification": string <VerificationEnum>,
  "reference_result": {
    object (BasePackageResult)
  },
  "information_result": {
    object (BasePackageResult)
  },
  "risk_result": {
    object (RiskResult)
  },
  "equifax_result": {
    object (EquifaxResult)
  },
  "identity_verified": boolean,
  "employment_verified": boolean,
  "identity_verification": {
    object (Identity Verification)
  },
  "enhanced_identity_verification": {
    object (EnhancedIdentityVerification)
  },
  "manual_id_verification": {
    object (ManualIDVerification)
  },
  "rcmp_result": {
    object (BasePackageResult)
  },
  "us_criminal_record_check_result": {
    object (USCriminalRecordCheckResult)
  },
  "verification_result": {
    object (VerificationResult)
  },
  "international_criminal_record_check_result": {
    object (BasePackageResult)
  },
  "motor_vehicle_record_result": {
    object (BasePackageResult)
  },
  "salary": number,
  "sufficient_salary": boolean,
  "high_risk_vulnerable_sector": boolean,
  "job_safety_undue_risk": boolean,
  "early_termination": number,
  "early_termination_label": string <Enum>,
  "reliability_risk": number,
  "reliability_risk_label": string <Enum>,
  "workplace_misconduct": number,
  "workplace_misconduct_label": string <Enum>
}

Reports

A report shows the final results of the requested checks. These endpoints allow you to retrieve your reports in the format of your choice.

Download a PDF report

GET https://api.certn.co/api/v1/hr/reports/{applicant_id}/pdf/

Download an application's report as a PDF file.

To download the report, wait for the application's status field to show Returned.

Path Parameters

application/pdf
string <binary>

Create a hosted PDF report

GET https://api.certn.co/api/v1/hr/reports/{applicant_id}/link/

Create a PDF report hosted on Certn's servers. The URL returned can be used to view the report without downloading it. This link is valid for 1 hour only.

To create the hosted PDF report, wait for the application's status field to show Returned.

Path Parameters

application/json
{
  "report_url": string
}

Download an HTML report

GET https://api-certn.co/api/v1/hr/reports/{applicant_id}/web/

Download an application's report as an HTML file.

To download the report, wait for the application's status field to show Returned.

Path Parameters

application/json
{
  "html": string
}

Last updated

The Certn Group of companies includes Certn, Credence & InterCheck. For educational purposes, these companies are referred to as “Certn” in this website. For questions about any of the aforementioned companies, contact support@certn.co. ©2023 Certn.