Certn API
Sign InCertnCertn Help

Settings and packages

How to organize general resources in Certn's API, such as Superteams, Teams, Users, and Packages .

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.

Team hierarchy

Organizations often need a structured team hierarchy for billing, user management, and package organization. Certn now supports a two-tiered hierarchy (Superteam and Team levels).

As a partner, you're required to have at least one Superteam, but you can create more Superteams and add Teams under them as needed.

This hierarchy is useful when you have end users who should only access background checks related to specific groups, rather than the entire organization's checks. If you're a reseller, using multiple Superteams can help you categorize background checks by customers and control the data visible in your end users' portal.

Superteams

A superteam serves as the higher of the two levels within your account hierarchy. It functions as an overarching entity under which other teams are organized.

Available to partners using API version >= 1.1.0.

Retrieve a list of your superteams

GET https://api.certn.co/api/v1/superteams/

View the list of your superteams.

application/json
{
    "count": int,
    "next": URL,
    "previous": URL,
    "results": [
        {
            "id": string <uuid>,
            "name": string
        }
    ]
}

Retrieve details of a specific superteam

GET https://api.certn.co/api/v1/superteams/{superteam_id}/

View the details of a specific superteam using the team id.

Path Parameters

application/json
{
    "id": string <uuid>,
    "name": string,
    "is_secure_sms_enabled": boolean,
    "is_report_id_enabled": boolean,
    "street_address": string,
    "city": string,
    "postal_code": string,
    "province_state": string,
    "other_province_state": string,
    "country": string
}

Create a superteam

POST https://api.certn.co/api/v1/superteams/

Create a new superteam.

Request Body

application/json
{
    "id": "string <uuid>",
    "name": "string",
    "is_secure_sms_enabled": boolean,
    "street_address": "string",
    "city": "string",
    "postal_code": "string",
    "province_state": "string",
    "country": "string"
}

Update a superteam

PUT https://api.certn.co/api/v1/superteams/{superteam_id}/

Path Parameters

Request Body

application/json
[
    {
        "id": string <uuid>,
        "name": string,
        "business_number": integer,
        "accounting_first_name": string,
        "accounting_last_name": string,
        "accounting_email": string,
        "team_first_name": string,
        "team_last_name": string,
        "team_email": string,
        "team_phone_number": string,
        "street_address": string,
        "city": string,
        "province_state": string <two letter code>,
        "country": string <ISO Country Code>,        
        "postal_code": string,
        "website": string,
        "industry": string,
        "active_user_count": integer,
        "internal_name": string,        
        "team_type": string,
    }
]

Teams

A team serves as the lower of the two levels within your account hierarchy. It functions as an entity under a superteam. A superteam can have many teams. If pre_pay is set to false, Certn will invoice a team each month according to the checks ordered during that billing cycle. If pre_pay is set to true, the applicant's background check process will require them to pay online.

Only available to partners using API version >= 1.1.0.

Retrieve a list of your teams

GET https://api.certn.co/api/v1/teams/

View a list of all your teams.

The results are sent via paginated response. 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/api/v1/teams/?page=<pgNum>

You can also filter the list by a superteam by providing the superteam id as a query parameter.

Query Parameters

application/json
{
    "count": int,
    "next": URL,
    "previous": URL,
    "results": [
        {
            "id": string <uuid>,
            "name": string,
            "superteam": string <uuid>,
            "pre_pay": boolean
            "street_address": string,
            "city": string,
            "postal_code": string,
            "province_state": string,
            "other_province_state": string,
            "country": string,
            "accounting_first_name": string,
            "accounting_last_name": string,
            "accounting_email": string,
            "accounting_email_cc": string,
        },
    ]
}

Retrieve team details

GET https://api.certn.co/api/v1/teams/{team_id}/

View the details of a team.

Path Parameters

application/json
{
    "id": string <uuid>,
    "name": string,
    "superteam": string <uuid>,
    "type": string <Enum>,
    "pre_pay": boolean,
    "street_address": string,
    "city": string,
    "postal_code": string,
    "province_state": string,
    "other_province_state": string,
    "country": string,
    "accounting_first_name": string,
    "accounting_last_name": string,
    "accounting_email": string,
    "accounting_email_cc": string
}

Create a team

POST https://api.certn.co/api/v1/teams/

Create a new team.

Request Body

application/json
{
    "id": string <uuid>,
    "name": string,
    "superteam": string <uuid>,
    "type": string <Enum>,
    "pre_pay": boolean,
    "street_address": string,
    "city": string,
    "postal_code": string,
    "province_state": string,
    "other_province_state": string,
    "country": string,
    "accounting_first_name": string,
    "accounting_last_name": string,
    "accounting_email": string,
    "accounting_email_cc": string
}

Update a team

PUT https://api.certn.co/api/v1/teams/{team_id}/

Update the details of a team.

A PUT request is an entire resource replacement.

Path Parameters

Request Body

application/json
{
    "id": string <uuid>,
    "name": string,
    "superteam": string <uuid>,
    "type": string <Enum>
    "pre_pay": boolean,
    "street_address": string,
    "city": string,
    "postal_code": string,
    "province_state": string,
    "other_province_state": string,
    "country": string,
    "accounting_first_name": string,
    "accounting_last_name": string,
    "accounting_email": string,
    "accounting_email_cc": string
}

Retrieve a team's address reference templates

GET https://api.certn.co/api/v1/teams/{team_id}/address/reference_templates/

View the details of all address reference templates for a team.

Path Parameters

application/json
[
    {
        "id": string,
        "name": string,
        "version": string,
        "description": string,
        "type": string < enum > ,
        "questions": [{
                "id": string,
                "index": int,
                "question": string,
                "type": string < enum > ,
                "multiple_choice_options": [
                    string,
                    string
                ],
                "multiple_choice_correct_option": string,
                "is_verifiable": boolean,
                "is_required": boolean
            }, {
                "id": string,
                "index": int,
                "question": string,
                "type": string < enum > ,
                "multiple_choice_options": [
                    string,
                    string
                ],
                "multiple_choice_correct_option": string,
                "is_verifiable": boolean,
                "is_required": boolean
            }
        ]
    }
]

Retrieve a team's employer reference templates

GET https://api.certn.co/api/v1/teams/{team_id}/employer/reference_templates/

View the details of all employer references templates for a team.

Path Parameters

application/json
[
    {
        "id": string,
        "name": string,
        "version": string,
        "description": string,
        "type": string < enum > ,
        "questions": [{
                "id": string,
                "index": int,
                "question": string,
                "type": string < enum > ,
                "multiple_choice_options": [
                    string,
                    string,
                    string
                ],
                "multiple_choice_correct_option": string,
                "is_verifiable": boolean,
                "is_required": boolean
            }, {
                "id": string,
                "index": int,
                "question": string,
                "type": string < enum > ,
                "multiple_choice_options": [
                    string,
                    string,
                    string
                ],
                "multiple_choice_correct_option": string,
                "is_verifiable": boolean,
                "is_required": boolean
            }
        ]
    }
]

Users

A user is the individual that orders background checks via your platform. They can be assigned as the Owner of a background check to track activity as well. To grant your users access to the Certn platform for viewing reports or managing settings, they must have a login created using this method.

By default, users will not receive a Welcome email from Certn when they are created. However, they can receive a temporary password by following Forgot my password? link.

Only available to partners using API version >= 1.1.0

Retrieve a list of users

GET https://api.certn.co/api/v1/users/

View a list of users.

Query Parameters

application/json
{
    "count": int,
    "next": URL,
    "previous": URL,
    "results": [
        {
            "id": string <uuid>,
            "first_name": string,
            "last_name": string,
            "is_active": boolean,
            "superteam": string <uuid>,
            "team": string <uuid>
        }
    ]
}

Retrieve a user's details

GET https://api.certn.co/api/v1/users/{user_id}/

View a user's details.

Path Parameters

application/json
{
    "id": string <uuid>,
    "first_name": string,
    "last_name": string,
    "email": string,
    "language": string <Enum>,
    "is_active": boolean,
    "superteam": string <uuid>,
    "team": string <uuid>
}

Create a user

POST https://api.certn.co/api/v1/users/

Create a new user.

Request Body

application/json
{
    "id": string <uuid>,
    "first_name": string,
    "last_name": string,
    "email": string,
    "language": string <Enum>,
    "is_active": boolean,
    "team": string <uuid>
}

Update a user

PUT https://api.certn.co/api/v1/users/{user_id}/

Path Parameters

application/json
{
    "id": string <uuid>,
    "first_name": string,
    "last_name": string,
    "email": string,
    "language": string <Enum>,
    "is_active": boolean,
    "team": string <uuid>
}

Packages

A collection of varied background check searches is known as a package. Retrieve these packages to enable your end users to choose from them on your platform.

Retrieving specific packages allows you to identify the correct Request Flags to include when users invite or instantly screen an applicant via Human Resources.

Or when users invite or instantly screen an applicant via Property Management.

Available to all partners

Retrieve your packages

GET https://api.certn.co/api/v1/packages/

Query Parameters

Retrieve details for a specific package by id

GET https://api.certn.co/api/v1/packages/{package_id}/

Path Parameters

application/json
{
    "id": string <uuid>,
    "name": "Package Name",
    "superteam": string <uuid>,
    "team": string <uuid>,
    "request_flags": [
        "request_enhanced_identity_verification",
        "request_social_media_check",
        "request_us_criminal_record_check_tier_1"
    ],
    "settings": {
        "requested_countries": [string],
        "us_criminal_record_check_years": 7,
        "employer_questionaire_id": string <uuid>,
        "address_questionaire_id": string <uuid>,
        "employer_references_max": int,
        "employer_references_min": int,
        "address_references_max": int,
        "address_references_min": int,
        "employment_verification_min": int,
        "employment_verification_max": int,
        "education_verification_min": int,
        "education_verification_max": int,
        "credential_verification_min": int,
        "credential_verification_max": int,
        "credential_verification_level": string <Enum>,
        "education_verification_level": string <Enum>,
        "employer_references_years": int,
        "address_references_years": int,
        "employment_verification_years": int,
        "address_references_years_or_individually": string <Enum>,
        "employer_references_years_or_individually": string <Enum>,
        "employment_verification_years_or_individually": string <Enum>,
        "purpose_of_check": string <Enum>,
        "position_title": string,
        "place_of_work": string,
        "license_type": string,
        "issuing_authority": string,
        "reason_for_check": string,
        "state_or_territory": string,
        "location_of_work": string,
        "volunteer_role": string,
        "volunteer_organization": string,
        "role_or_position_title": string,
        "employment_sector": string <Enum>
    }
}

Create a package

POST https://api.certn.co/api/v1/packages/

Request Body

application/json
{
    "id": string <uuid>,
    "name": string,
    "team": string <uuid>,
    "request_flags": [
        string
    ]
    "settings": {
        object (Package settings)
    }
}

Update a package

PUT https://api.certn.co/api/v1/packages/{package_id}/

Path Parameters

Request Body

{
    "id": string <uuid>,
    "name": "Package Name",
    "superteam": string <uuid>,
    "team": string <uuid>,
    "request_flags": [
        "request_enhanced_identity_verification",
        "request_social_media_check",
        "request_us_criminal_record_check_tier_1"
    ],
    "settings": {
        "requested_countries": [string],
        "us_criminal_record_check_years": 7,
        "employer_questionaire_id": string <uuid>,
        "address_questionaire_id": string <uuid>,
        "employer_references_max": int,
        "employer_references_min": int,
        "address_references_max": int,
        "address_references_min": int,
        "employment_verification_min": int,
        "employment_verification_max": int,
        "education_verification_min": int,
        "education_verification_max": int,
        "credential_verification_min": int,
        "credential_verification_max": int,
        "credential_verification_level": string <Enum>,
        "education_verification_level": string <Enum>,
        "employer_references_years": int,
        "address_references_years": int,
        "employment_verification_years": int,
        "address_references_years_or_individually": string <Enum>,
        "employer_references_years_or_individually": string <Enum>,
        "employment_verification_years_or_individually": string <Enum>,
        "purpose_of_check": string <Enum>,
        "position_title": string,
        "place_of_work": string,
        "license_type": string,
        "issuing_authority": string,
        "reason_for_check": string,
        "state_or_territory": string,
        "location_of_work": string,
        "volunteer_role": string,
        "volunteer_organization": string,
        "role_or_position_title": string,
        "employment_sector": string <Enum>
    }
}

Delete a package

DELETE https://api.certn.co/api/v1/packages/{package_id}/

Path Parameters

PreviousUnderstanding statuses and scoresNextHuman Resources

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.