Overview
How to screen with the Certn API:
1) Obtain a Session Token to use with future requests (See: Authentication)
2) POST your screen request to one of the screening endpoints (See: One-Call Screening)
3) Review your results in web, pdf, or json format (See: Viewing Your Results)
Authentication
All API calls require a token authorization header with the following format:
Authorization : Token {{ session_token }}
Obtaining a session token is done by calling the following endpoint with your username and password as Basic Authentication:
POST {{ base_url }}/api/v1/authenticate/
Sample Request (JSON):

{
    "expires": 8
}
Response (JSON):

{
    "user_id": "asdf-1234-asdf-1234",
    "token": "asdf1234asdf1234asdf1234asdf1234"
}
The session token is valid for the number of hours specified in the "expires" field. Passing a null value to the expires field will return a token that will never expire.
Other Authentication Endpoints
List all active tokens for the provided Basic Auth.
GET {{ base_url }}/api/v1/authenticate/
Log out the provided session token.
POST {{ base_url }}/api/v1/logout/
Log out all session tokens.
POST {{ base_url }}/api/v1/logoutall/
Trailing Slashes
The Certn API requires that all unsafe actions [POST, PUT, PATCH, DELETE] include trailing slashes on the URL they are accessing. If this trailing slash is omitted, the request will default to a GET request.
Rate Limits
The Certn API imposes a burst rate limit of 120 rolling requests per minute, and a sustained limit of 14400 requests per 24 hours. If you require a limit increase, please contact support@certn.co.
Errors
Success
Successful calls will result in an HTTP status code of:
200 - OK 201 - Created 204 - No Content
Client Error
Client errors return with a status code of 400, and an explanation of what is wrong with the request.
Examples:

{
    "first_name": ["This field is required."]
}

{
    "details": "Method 'DELETE' not allowed."
}
Server Error
Server errors return a status code of 500, and are the result of unexpected behaviour that is not gracefully handled by the server. If this happens, wait a minute then try again. If the issue persists, contact support@certn.co (if they haven't contacted you first).
One-Call Screening
Application Invitation
Invite the applicant to fill out their application with Certn. You can choose to provide the application_url to the applicant, or have Certn email them on your behalf.
POST {{ base_url }}/hr/v1/applications/invite/
Sample Request (JSON):

{
    "emails": ["curtis+1@certn.co"],
    "listing_id": "asdf-1234-asdf-1234",
    "email_applicants": false
}
emails - List of one or more emails to invite to apply with Certn
listing_id - Optional
email_applicants - Optional (defaults to True)
Sample Request (JSON):

        {
            "id": "asdf-1234-asdf-1234",
            "created": "2018-06-01T12:00:00.000000Z",
            "modified": "2018-06-01T12:00:00.000000Z",
            "owner": {
                "id": "asdf-1234-asdf-1234",
                "email": "curtis@certn.co"
            },
            "listing": null,
            "status": "Incomplete",
            "applicants": [
                {
                    "id": "asdf-1234-asdf-1234",
                    "status": "Pending",
                    "first_name": "",
                    "last_name": "",
                    "email": "curtis+1@certn.co",
                    "certn_score": null,
                    "share_of_rent": null,
                    "is_cosigner": false,
                    "application_url": "http://app.certn.co/...",
                    "report_url": "http://app.certn.co/..."
                }
            ],
            "is_active": true,
            "is_selected": false,
            "applicant_status": "N",
            "get_applicant_status_display": "None"
        }

Quick Screen
First name, last name, and one previous address required.
Scores the applicant based only on the information provided. Ignores "self-reported" sections and will typically produce a [PASS, WARN, FAIL] overall score instead of a numerical one.
Use this if you don't have complete information, and you want to pre-screen based on their basic information
POST {{ base_url }}/hr/v1/applications/quick/
Sample Request: (JSON)

        {
            "email": "elle@certn.co",
            "information": {
                "status": "Completed",
                "first_name": "Elle",
                "middle_name": null,
                "last_name": "Herron",
                "phone_number": "2501231234",
                "cover_letter": "Here is my cover letter, it should probably be a lot longer and more descriptive.",
                "conviction_explanation": null,
                "early_termination_explanation": null,
                "addresses": [
                    {
                        "id": "asdf-1234-asdf-1234-asdf1234asdf",
                        "created": "2018-06-01T12:00:00.000000Z",
                        "address": "1234 Sample Road",
                        "unit": null,
                        "city": "Victoria",
                        "province_state": "British Columbia",
                        "country": "CA",
                        "postal_code": "V1A2B3",
                        "auto_address": null,
                        "full_address": "3595 Richmond Road Victoria British Columbia CA V8P"
                    }
                ],
                "employers": [
                    {
                        "start_date": "2018-04-20",
                        "end_date": null,
                        "position": "Software Developer",
                        "part_time_full_time": "FT",
                        "employment_url": "microsoft.com",
                        "employer_reference": {
                        "email":{
                            "address": "test@certn.co",
                            "type": "Work"
                        },
                        "phone_number": {
                            "phone_type": "WORK",
                            "number": "18001231231"
                        },
                        "name": {
                            "first_name": "John",
                            "last_name": "Smith"
                        },
                        "position": "HR Head",
                        "contact": {
                            "type": "EMPLOYER",
                            "is_reference": true,
                            "can_contact": false
                        }
                        },
                        "company_name": "Microsoft",
                        "address": null,
                        "accomplishments": "Was awarded employee of the month 3 times."
                    }
                ],
                "educations": [
                    {
                        "start_date": "2014-09-01",
                        "end_date": "2018-04-20",
                        "degree": {
                            "id": "asfd-1234-asdf-1234-asdf1234asdf",
                            "degree": "Bachelor of Arts - BA"
                        },
                        "institution": "University of Victoria",
                        "education_reference": {
                        "email":{
                            "address": "test@certn.co",
                            "type": "Work"
                        },
                        "phone_number": {
                            "phone_type": "CELL",
                            "number": "18001231231"
                        },
                        "name": {
                            "first_name": "John",
                            "last_name": "Smith"
                        },
                        "position": "Supervisor",
                        "contact": {
                            "type": "EDUCATION",
                            "is_reference": true,
                            "can_contact": false
                        }
                        },
                        "activities_societies": "",
                        "description": "I bachelor'd in arts at UVic",
                        "current": null,
                        "specializations": [
                            {
                                "id": "asfd-1234-asdf-1234-asdf1234asdf",
                                "specialization": "Business/Commerce, General",
                                "specialization_type": "MAJOR"
                            }
                        ]
                    }
                ],
                "skills": [
                {
                    "id": "asfd-1234-asdf-1234-asdf1234asdf",
                    "skill": "Python 3.6"
                }
                ],
                "documents": []
            }
        }

Required fields:
first_name
last_name
at least one previous address with:
address
city
province_state
country
Special fields:
"application_id" - Associate this applicant with an existing application
"listing_id" - Associate this applicant with an existing listing
country:
ISO 2-Character Country Codes [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]
"CA" - Canada
"US" - United States of America
part_time_full_time - Choices:
"PT" - Part Time
"FT" - Full Time
contact - type Choices:
"EDUCATION" - Education
"EMPLOYER" - Employer
specialization_type Choices:
"MAJOR" - Major
"MINOR" - Minor
phone_type Choices:
"WORK" - Work
"HOME" - Home
"CELL" - Cell
"OTHER" - Other
"NONE" - None
Viewing your Results
Manual Retrieval
Applications typically take 2-10 seconds to process, but can occassionaly take up to 300 seconds if data providers are experiencing delays.
Polling the following URL until the status == "Returned" will ensure that you receive a completed report:
GET {{ base_url }}/hr/v1/applicants/{{ applicant_id }}/
Webhook Notifications
Optionally, a webhook URL can be configured to automatically POST the resulting applicant JSON once processing is complete.
While this will eventually be configurable in the dashboard, please contact support@certn.co to enable this feature for now.
Certn Report
You can retrieve a copy of your Certn report in html or pdf format by calling:
PDF
GET {{ base_url }}/hr/v1/reports/{{ applicant_id }}/pdf/
Web
GET {{ base_url }}/hr/v1/reports/{{ applicant_id }}/web/
PDF response: contains downloadable PDF report.
Web Response: (JSON)

{
    "html": "..."
}
Sample Applicant JSON

    {
        "id": "asdf-1234-asdf-1234-asdf1234asdf",
        "created": "2018-06-01T12:00:00.000000Z",
        "modified": "2018-06-01T12:00:00.000000Z",
        "submitted_time": "2018-06-01T12:00:00.000000Z",
        "last_updated": "2018-06-01T12:00:00.000000Z",
        "status": "Returned",
        "applicant_type": "Standard",
        "notes": null,
        "is_favourite": false,
        "is_submitted": true,
        "discounted": false,
        "email_references": false,
        "certn_score": "74.05",
        "reliability_risk": "50.02",
        "workplace_misconduct": "25.00",
        "early_termination": "50.02",
        "certn_score_label": "PASS",
        "reliability_risk_label": "WARN",
        "workplace_misconduct_label": "PASS",
        "early_termination_label": "WARN",
        "applicant_account": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "email": "sample@certn.co"
        },
        "application": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "created": "2018-06-01T12:00:00.000000Z",
            "modified": "2018-06-01T12:00:00.000000Z",
            "owner": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "email": "andrew@certn.co"
            },
            "listing": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "created": "2018-06-01T12:00:00.000000Z",
            "modified": "2018-06-01T12:00:00.000000Z",
            "last_updated": "2018-06-01T12:00:00.000000Z",
            "name": null,
            "is_active": true,
            "url_code": "certn-developer-postition",
            "is_placeholder": false,
            "owner": {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "email": "will@certn.co"
            },
            "notification_list": [],
            "start_date": null,
            "work_type": "FULL_TIME",
            "address": {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "created": "2018-06-01T12:00:00.000000Z",
                "modified": "2018-06-01T12:00:00.000000Z",
                "address": null,
                "city": "Victoria",
                "province_state": "BC",
                "country": "CA"
            },
            "position_name": "Software Developer",
            "required_years_relevant_experience": 0,
            "required_skills": [],
            "required_specializations": [],
            "required_education": {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "degree": "Bachelor of Engineering (BEng)"
            },
            "applicant_count": 4,
            "new_applicant_count": 1
            },
            "is_active": true,
            "is_selected": false,
            "applicant_status": "NONE"
        },
        "information": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "status": "Completed",
            "first_name": "Elle",
            "middle_name": null,
            "last_name": "Herron",
            "phone_number": "2501231234",
            "cover_letter": null,
            "conviction_explanation": null,
            "early_termination_explanation": null,
            "addresses": [
            {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "created": "2018-06-01T12:00:00.000000Z",
                "address": "1234 Sample Road",
                "unit": null,
                "city": "Victoria",
                "province_state": "British Columbia",
                "country": "CA",
                "postal_code": "V1A2B3",
                "auto_address": null,
                "full_address": "3595 Richmond Road Victoria British Columbia CA V8P",
                "verification": {
                "total_verification": "0.00",
                "total_coverage": "0.00",
                "verification_result": "UNVERIFIED",
                "get_verification_result_display": "Unverified",
                "verification_matches": []
                },
                "consistency": {
                "total_consistency": "0.00",
                "total_coverage": "0.00",
                "consistency_result": null,
                "get_consistency_result_display": null,
                "consistency_matches": []
                }
            }
            ],
            "employers": [
            {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "start_date": "2018-04-20",
                "end_date": null,
                "position": "Software Developer",
                "part_time_full_time": "FT",
                "employment_url": "microsoft.com",
                "company_name": "Microsoft",
                "employer_reference": {
                "email":{
                    "address": "test@certn.co",
                    "type": "Work"
                },
                "phone_number": {
                    "phone_type": "WORK",
                    "number": "18001231231"
                },
                "name": {
                    "first_name": "John",
                    "last_name": "Smith"
                },
                "position": "HR Head",
                "contact": {
                    "type": "EMPLOYER",
                    "is_reference": true,
                    "can_contact": false
                }
                },
                "address": null,
                "accomplishments": "Was awarded employee of the month 3 times.",
                "verification": {
                "total_verification": "0.00",
                "total_coverage": "0.00",
                "verification_result": "UNVERIFIED",
                "get_verification_result_display": "Unverified",
                "verification_matches": []
                },
                "consistency": {
                "total_consistency": "0.00",
                "total_coverage": "0.00",
                "consistency_result": null,
                "get_consistency_result_display": null,
                "consistency_matches": []
                }
            }
            ],
            "educations": [
            {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "created": "2018-06-01T12:00:00.000000Z",
                "start_date": "2014-09-01",
                "end_date": "2018-04-20",
                "degree": {
                "id": "asfd-1234-asdf-1234-asdf1234asdf",
                "degree": "Bachelor of Arts - BA"
                },
                "institution": "University of Victoria",
                "education_reference": null,
                "activities_societies": null,
                "description": null,
                "current": null,
                "specializations": [
                {
                    "id": "asfd-1234-asdf-1234-asdf1234asdf",
                    "specialization": "Business/Commerce, General",
                    "specialization_type": "MAJOR"
                }
                ],
                "verification": {
                "total_verification": "0.00",
                "total_coverage": "0.00",
                "verification_result": "UNVERIFIED",
                "get_verification_result_display": "Unverified",
                "verification_matches": []
                },
                "consistency": {
                "total_consistency": "0.00",
                "total_coverage": "0.00",
                "consistency_result": null,
                "get_consistency_result_display": null,
                "consistency_matches": []
                }
            }
            ],
            "skills": [],
            "documents": [
                {
                    "id": "asdf-1234-asdf-1234",
                    "created": "2018-05-24T22:13:50.903395Z",
                    "modified": "2018-05-24T22:13:50.903417Z",
                    "name": "resume_2018",
                    "file_type": "pdf",
                    "document_type": "RESUME",
                    "information_id": "asdf-1234-asdf-1234",
                    "url": "https://s3.ca-central-1.amazonaws.com/certn-document-uploads/..."
                }
            ],
            "verification": {
            "total_verification": "0.00",
            "total_coverage": "0.00",
            "verification_result": "UNVERIFIED",
            "get_verification_result_display": "Unverified",
            "verification_matches": []
            },
            "consistency": {
            "total_consistency": "0.00",
            "total_coverage": "0.00",
            "consistency_result": null,
            "get_consistency_result_display": null,
            "consistency_matches": []
            }
        },
        "linkedin": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "status": "None"
        },
        "information_result": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "overall_score": "WARN",
            "red_flags": [
            "Applicant does not report having required degree."
            ],
            "green_flags": [],
            "description": "The applicant score is based on self-provided information from the applicant and an analysis of the applicant's information available to Certn. This includes previous education history, reported skills, employment history, employment duration, employment references, as well as other important informational data points."
        },
        "behavioural_result": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "overall_score": "NONE",
            "hard_working_score": null,
            "critical_thinking_score": null,
            "organization_score": null,
            "culture_fit_score": null,
            "accountability_score": null,
            "accountability_score_label": "NONE",
            "critical_thinking_score_label": "NONE",
            "organization_score_label": "NONE",
            "culture_fit_score_label": "NONE",
            "hard_working_score_label": "NONE",
            "neutral_flags": null,
            "description": "The behavioural score is based on self-provided information from the applicant and an analysis of the applicant's information available to Certn. This includes social media analysis as well as other important informational data points."
        },
        "risk_result": {
            "id": "asdf-1234-asdf-1234-asdf1234asdf",
            "status": "RETURNED",
            "overall_score": "PASS",
            "risk_evaluations": [
            {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "overall_score": "PASS",
                "risk_information_result": {
                "id": "asdf-1234-asdf-1234-asdf1234asdf",
                "confidence": "1.00",
                "addresses": [
                    {
                    "id": "asdf-1234-asdf-1234-asdf1234asdf",
                    "unit": null,
                    "address": "3595 Richmond Road",
                    "city": "Victoria",
                    "province_state": "British Columbia",
                    "country": "CA",
                    "postal_code": "V8P",
                    "po_box": null,
                    "type": null
                    }
                ],
                "employers": [
                    {
                    "id": "asdf-1234-asdf-1234-asdf1234asdf",
                    "position": "Customer Success",
                    "company_name": "Certn",
                    "start_date": "2018-04-20",
                    "end_date": null
                    }
                ],
                "urls": [],
                "names": [],
                "educations": [
                    {
                    "id": "asdf-1234-asdf-1234-asdf1234asdf",
                    "degree": "Bachelor of Arts - BA",
                    "institution": "University of Victoria",
                    "start_date": "2014-09-01",
                    "end_date": "2018-04-20",
                    "description": null,
                    "activities_societies": null
                    }
                ],
                "emails": [],
                "phone_numbers": [],
                "sources": []
                },
                "criminal_results": []
            }
            ],
            "red_flags": [],
            "green_flags": [
            "No criminal alerts found."
            ],
            "description": "The social score is based on self-provided information from the applicant and an analysis of the applicant's information available to Certn. This includes a criminal identity scan, social profile scan, as well as other important informational data points. *Note that when criminal identities are discovered the overall Certn score is not impacted by the results found unless the match similarity is above our confidence threshold of 95%.",
            "risk_description": "The criminal identity risk is an assessment of the risk posed to assets given the results of the criminal identity scan. Please review any risk relevant information from our negative news and criminal database analysis below.",
            "similarity_description": "The criminal identity similarity percentage is a comparison between the applicant's self-provided information and the corresponding information we find in our databases. As a general guideline, if the results of our criminal identity scan has a similarity percentage of above 95%, Certn can confidently predict that the information presented below corresponds correctly to the applicant being screened. However, if the criminal identity scan returns results with a similarity percentage of below 95%, the onus falls to the client to accurately verify the results."
        },
        "reliability_risk_description": "Reliability risk if assessed using an analysis of an applicant's personal history and / or behavioural organization characteristics that predicts the likelihood of being a reliable employee.",
        "workplace_misconduct_description": "Workplace misconduct risk is assessed using an analysis of an applicant's personal history and / or behavioural accountability characteristics that predicts the likelihood of workplace misconduct.",
        "early_termination_description": "Early termination risk is assessed using an analysis of an applicant's employment history and / or behavioural culture fit and hardworking characteristics that predicts the likelihood of early termination.",
        "applicant_result_description": "Certn has analysed Elle Herron's application and would like you to please carefully review each section of this report to determine if this specific applicant meets your requirements. Be sure to also review the Risk Factors associated with this report as well as the 'Potential Postives' and 'Potential Negatives' associated with each section as well. As always, contact support@certn.co if you have any questions.",
        "applicant_result_summary": "The Applicant score is determined by analysing education history, employment history, and more.",
        "social_result_summary": "The Social score is determined by analysing criminal identity, negative news, social profile scans, and more.",
        "behavioural_result_summary": "The Behavioural score is determined by social media analysis, and more.",
        "identity_verified": null,
        "identity_verified_summary": "Digital identity verification incomplete.",
        "is_viewed": true
        }