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.

200: OK Superteam successfully retrieved

Response type

application/json

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

Example

application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "23554549-b086-4f74-94fe-ccf88e1c643b",
            "name": "Superteam Name"
        }
    ]
}

403: Forbidden Authentication failed

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

Name	Type	Description
superteam_id*	string	ID of the superteam

200: OK Superteam successfully retrieved

Response Type

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
}

Example

application/json

{
    "id": "aafa6f6b-e394-4514-b2b4-e5cfdabcffa1",
    "name": "Partner Superteam",
    "is_secure_sms_enabled": false,
    "is_report_id_enabled": true,
    "street_address": "123 4 Main Street",
    "city": "Victoria",
    "postal_code": "V8A1B2",
    "province_state": "BC",
    "other_province_state": null,
    "country": "CA"
}

403: Forbidden Authentication failed

Create a superteam

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

Create a new superteam.

Request Body

Name	Type	Description
name*	string	Superteam name
street_address*	string	Street address of Superteam's primary location
city*	string	City of Superteam's primary location
province_state*	string	ISO province or state code for Superteam's primary location
country*	string <enum>	Country Code for Superteam's primary location. Must be one of "CA", "US", "GB", or "AU".
postal_code*	string	Postal code of Superteam's primary location
other_province_state	string	If province_state is OT, provide the province or state of the Superteam's primary location
is_secure_sms_enabled*	boolean	SMS enabled or disabled for the team
is_report_id_enabled	boolean

201: Created Superteam successfully created

Response type

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"
}

Example

application/json

{
    "id": "aafa6f6b-e394-4514-b2b4-e5cfdabcffa1",
    "name": "Partner Superteam",
    "is_secure_sms_enabled": false,
    "street_address": "123 4 Main Street",
    "city": "Victoria",
    "postal_code": "V8A1B2",
    "province_state": "BC",
    "country": "CA"
}

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

You have missed a required field in your payload.

See #400-bad-request for more details.

403: Forbidden Authentication failed

Update a superteam

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

Path Parameters

Name	Type	Description
superteam_id*	string <uuid>	Superteam id

Request Body

Name	Type	Description
name*	string	Superteam name
is_secure_sms_enabled*	boolean	SMS enabled or disabled for the team
is_report_id_enabled*	boolean
street_address*	string	Street address of Superteam's primary location
city*	string	City of Superteam's primary location
postal_code*	string	Postal code of Superteam's primary location
province_state*	string	for Superteam's primary location
other_province_state	string	If province_state is OT, provide the province or state of the Superteam's primary location
country*	string	ISO Country Code for Superteam's primary location. Must be one of "CA", "US", "GB", or "AU".

200: OK Superteam successfully updated

Response type

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,
    }
]

Example

application/json

[
    {
        "id": "17f225cf-f547-437a-8bd9-36599416f7e9",
        "name": "Example Team",
        "business_number": 1234,
        "accounting_first_name": "Magnus",
        "accounting_last_name": "Certn",
        "accounting_email": "[e-mail]",
        "team_first_name": "M",
        "team_last_name": "C",
        "team_email": "[e-mail]",
        "team_phone_number": null,
        "street_address": "4412 King Alfred Court",
        "city": "Victoria",
        "province_state": "BC",
        "country": "CA",
        "postal_code": null,
        "website": "https://www.certn.co",
        "industry": "Background Checks",
        "active_user_count": 7,
        "internal_name": "Example Team",
        "team_type": "OT"
    }
]

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

You have missed a required field in your payload.

See #400-bad-request for more details.

403: Forbidden Authentication failed

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

Name	Type	Description
superteam*	string <uuid>	Superteam id
page	int	Page number to retrieve

200: OK Teams successfully retrieved

Response type

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,
        },
    ]
}

Example

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "9624967f-993a-46b3-9dc0-4c9f71818f4e",
            "name": "Team Name 2",
            "superteam": "111cec04-a23c-4eda-81d8-9d32bb369c27",
            "pre_pay": false,
            "street_address": "123 4 Main Street",
            "city": "Victoria",
            "postal_code": "V2K9L0",
            "province_state": "SK",
            "other_province_state": null,
            "country": "CA",
            "accounting_first_name": "Accounting",
            "accounting_last_name": "Name",
            "accounting_email": "[e-mail]",
            "accounting_email_cc": null
        },
        {
            "id": "4c149bff-79b3-48d2-87fc-6212871a9ea4",
            "name": "Team Name",
            "superteam": "111cec04-a23c-4eda-81d8-9d32bb369c27",
            "pre_pay": true,
            "street_address": "18 Main Street",
            "city": "Saskatoon",
            "postal_code": "M2K 0G4",
            "province_state": "SK",
            "other_province_state": null,
            "country": "CA",
            "accounting_first_name": "Accounting",
            "accounting_last_name": "Name",
            "accounting_email": "[e-mail]",
            "accounting_email_cc": null
        }
    ]
}

403: Forbidden Authentication failed

Retrieve team details

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

View the details of a team.

Path Parameters

Name	Type	Description
team_id*	string <uuid>	Team id

200: OK Team successfully retrieved

Response Type

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
}

Example

application/json

{
    "id": "9624967f-993a-46b3-9dc0-4c9f71818f4e",
    "name": "Team Name 2",
    "superteam": "111cec04-a23c-4eda-81d8-9d32bb369c27",
    "type": "HR",
    "pre_pay": false,
    "street_address": "123 4 Main Street",
    "city": "Victoria",
    "postal_code": "V2K9L0",
    "province_state": "SK",
    "other_province_state": null,
    "country": "CA",
    "accounting_first_name": "Accounting",
    "accounting_last_name": "Name",
    "accounting_email": "[e-mail]",
    "accounting_email_cc": null
}

403: Forbidden Authentication failed

Create a team

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

Create a new team.

Request Body

Name	Type	Description
name*	string	Unique team name
type*	string <enum>	Team type, "HR" or "PM"
country*	string <enum>	ISO country code for team's primary location. Must be one of "CA", "US", "GB", or "AU".
pre_pay	boolean	Billing to be pre-paid. Default false.
superteam*	string <uuid>	Superteam
province_state*	string	ISO province or state code for Team's primary location
street_address	string	Street address of Team's primary location
city	string	City of Team's primary location
postal_code	string	Postal code of Team's primary location
other_province_state	string	If province_state is OT, provide the province or state of the Team's primary location
accounting_email_cc	string	Email addresses to CC invoice emails to
accounting_email	string	Email address to send invoices to
accounting_last_name	string	Last name of accountant responsible for handling team billing
accounting_first_name	string	First name of accountant responsible for handling team billing

201: Created Team successfully created

Response type

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
}

Example

application/json

{
    "id": "4c149bff-79b3-48d2-87fc-6212871a9ea4",
    "name": "Team Name",
    "superteam": "111cec04-a23c-4eda-81d8-9d32bb369c27",
    "type": "HR",
    "pre_pay": true,
    "street_address": "18 Main Street",
    "city": "Saskatoon",
    "postal_code": "M2K 0G4",
    "province_state": "SK",
    "other_province_state": null,
    "country": "CA",
    "accounting_first_name": "Accountant",
    "accounting_last_name": "Name",
    "accounting_email": "[e-mail]",
    "accounting_email_cc": ""
}

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

No name, superteam, type, province_state, and/or country provided in the request.

Ensure your request includes the name, superteam, type, province_state, and country.

See #400-bad-request for more details.

400: Bad Request Invalid superteam id

This may be happening because:

The incorrect superteam id was provided.

Enter the correct superteam id in your request.

See #400-bad-request for more details.

400: Bad Request Country or type \"LM\" is not a valid choice

This may be happening because:

The country or type field values are not valid.

Ensure you are using the following values for the country and type fields:

Country: "US", "CA", "GB", or "AU" Type: "HR" or "PM"

See #400-bad-request for more details.

403: Forbidden Authentication failed

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

Name	Type	Description
team_id*	string <uuid>	Team id

Request Body

Name	Type	Description
name*	string	Unique team name
type*	string <enum>	Team type, "HR" or "PM"
country*	string <enum>	ISO country code for Team's primary location. Must be one of "CA", "US", "GB", or "AU".
pre_pay*	boolean	Billing type. Default false.
superteam*	string <uuid>	Superteam id
postal_code*	string	Postal code of Team's primary location
city*	string	City of Team's primary location
street_address*	string	Street address of Team's primary location
province_state*	string	ISO province or state code for Team's primary location
accounting_first_name*	string	First name of accountant responsible for handling team billing
accounting_last_name*	string	Last name of accountant responsible for handling team billing
accounting_email*	string	Email address to send invoices to
accounting_email_cc*	string	Email addresses to CC invoice emails to
other_province_state	string	If province_state is OT, provide the province or state of the Superteam's primary location

200: OK Team successfully updated

Response type

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
}

Example

application/json

{
    "id": "4c149bff-79b3-48d2-87fc-6212871a9ea4",
    "name": "Team Name",
    "superteam": "111cec04-a23c-4eda-81d8-9d32bb369c27",
    "type": "HR"
    "pre_pay": true,
    "street_address": "18 Main Street",
    "city": "Saskatoon",
    "postal_code": "M2K 0G4",
    "province_state": "SK",
    "other_province_state": null,
    "country": "CA",
    "accounting_first_name": "Accountant",
    "accounting_last_name": "Name",
    "accounting_email": "[e-mail]",
    "accounting_email_cc": ""
}

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

No id, name, type, superteam name, and/or country provided in the request.

Ensure your request includes the id, name, type, superteam name, and country.

See #400-bad-request for more details.

400: Bad Request <field> cannot be updated

Once a team type, superteam, and country have been set, they cannot be changed. It is recommended you create a new team with applicable fields.

403: Forbidden Authentication failed

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

Name	Type	Description
team_id*	string	ID of the team

200: OK Questionnaires successfully retrieved

Response type

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
            }
        ]
    }
]

Example

application/json

[
    {
        "id": "ae3087ac-bccc-4cf1-b149-30b2a854d210",
        "name": "Default",
        "version": "0.0.0",
        "description": "Default Address Reference Questionnaire",
        "type": "ADDRESS",
        "questions": [{
                "id": "80f2d05c-8ee0-4c8e-a8fe-030403bd3378",
                "index": 0,
                "question": "Did {{ first_name }} {{ last_name }} rent from {{ start_date }}{% if end_date %} to {{ end_date }}{% endif %}?",
                "type": "TRUE_FALSE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": true,
                "is_required": true
            }, {
                "id": "ae95f70b-24b8-4cc5-97ae-19aeefe732bd",
                "index": 1,
                "question": "What was the address {{ first_name }} {{ last_name }} lived at?",
                "type": "MULTIPLE_CHOICE",
                "multiple_choice_options": [
                    "11012 Main St. Vancouver BC V6T 1X1",
                    "2023 Alma Ave. Toronto ON M6H 3P2",
                    "4334 Connolly St. Halifax NS B3L 3M4",
                    "{{ address }}"
                ],
                "multiple_choice_correct_option": "{{ address }}",
                "is_verifiable": true,
                "is_required": false
            }, {
                "id": "be755532-f4a2-4372-bb80-8dca8e9fe4f4",
                "index": 2,
                "question": "Was {{ first_name }} {{ last_name }} generally a clean and/or organized tenant (1 not clean, 10 very clean)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "b5b7383e-a165-4722-b09c-082643bb3cfc",
                "index": 3,
                "question": "How well did {{ first_name }} {{ last_name }} generally get along with property managers and/or fellow residents (1 not well at all, 10 very well)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "a85394ae-2e49-47a7-a94a-a8b6f6200103",
                "index": 4,
                "question": "How likely would you be to rent to {{ first_name }} {{ last_name }} again? Are you comfortable recommending {{ first_name }} {{ last_name }} as a tenant (1 not likely, 10 very likely)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "21c8810b-bb58-4f5b-8445-17526757da73",
                "index": 5,
                "question": "Did you receive complaints from neighbours with regards to {{ first_name }} {{ last_name }}'s behaviour (1 frequently, 10 never)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "05b96f0f-fbf0-4378-907f-177c6682a034",
                "index": 6,
                "question": "Do you have any additional comments you'd like to provide regarding {{ first_name }} {{ last_name }}?",
                "type": "LONG_ANSWER",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }
        ]
    }
]

404: Not Found Team not found

This may be happening because:

The ID you provided couldn't be found

Add your team ID to the URL and make sure it's in the proper format.

See #404-not-found for more details.

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

Name	Type	Description
team_id	string	ID of the team

200: OK Questionnaires successfully retrieved

Response type

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
            }
        ]
    }
]

Example

application/json

[
    {
        "id": "9550b49d-4069-4b41-8672-b9dc02661db2",
        "name": "Default",
        "version": "0.0.0",
        "description": "Default Employer Reference Questionnaire",
        "type": "EMPLOYER",
        "questions": [{
                "id": "c598a517-b89d-4372-873b-b0f27c8afd27",
                "index": 0,
                "question": "What was {{ first_name }} {{ last_name }}'s most recent position at {{ company_name }}?",
                "type": "MULTIPLE_CHOICE",
                "multiple_choice_options": [
                    "Financial Analyst",
                    "Receptionist",
                    "Contractor",
                    "{{ position }}"
                ],
                "multiple_choice_correct_option": "{{ position }}",
                "is_verifiable": true,
                "is_required": false
            }, {
                "id": "0f1aebd6-2286-435f-bd81-f9d8e9a0645d",
                "index": 1,
                "question": "Did {{ first_name }} {{ last_name }} work at {{ company_name }} from {{ start_date }}{% if end_date %} to {{ end_date }}{% endif %}?",
                "type": "TRUE_FALSE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": true,
                "is_required": false
            }, {
                "id": "4c1d943d-b595-4b7f-9983-be13a72e0003",
                "index": 2,
                "question": "If given the opportunity, would you hire {{ first_name }} {{ last_name }} again?",
                "type": "TRUE_FALSE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "1fedf7c4-0f7f-4546-841f-c6eb226da2b8",
                "index": 3,
                "question": "In general, how well did {{ first_name }} {{ last_name }} get along with customers, peers and/or managers (1 not at all, 10 very much so)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "f408d503-da54-42a4-b29e-d235bf9c890c",
                "index": 4,
                "question": "In general, did {{ first_name }} {{ last_name }} arrive on time to work (1 not at all, 10 very much so)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "e6c11a10-b4b8-4f47-a304-edf498e1e50f",
                "index": 5,
                "question": "How well did {{ first_name }} {{ last_name }} satisfy the requirements of the position (1 not satisfactory, 10 very satisfactory)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "aea311f1-a98d-42a5-b23b-a092affd275c",
                "index": 6,
                "question": "Did {{ first_name }} {{ last_name }} go above and beyond what was required without being asked (1 not at all, 10 very much so)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "cd1d12c0-002b-4090-a758-6904ad7c2bf1",
                "index": 7,
                "question": "How would you rate {{ first_name }} {{ last_name }}'s ability to handle high pressure or stressful situations (1 not good at all, 10 very good)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "3dc846b6-773e-4cfe-852d-5eec405c5f5c",
                "index": 8,
                "question": "Do you have any additional comments you'd like to provide regarding {{ first_name }} {{ last_name }}?",
                "type": "LONG_ANSWER",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }
        ]
    }
][
    {
        "id": "9550b49d-4069-4b41-8672-b9dc02661db2",
        "name": "Default",
        "version": "0.0.0",
        "description": "Default Employer Reference Questionnaire",
        "type": "EMPLOYER",
        "questions": [{
                "id": "c598a517-b89d-4372-873b-b0f27c8afd27",
                "index": 0,
                "question": "What was {{ first_name }} {{ last_name }}'s most recent position at {{ company_name }}?",
                "type": "MULTIPLE_CHOICE",
                "multiple_choice_options": [
                    "Financial Analyst",
                    "Receptionist",
                    "Contractor",
                    "{{ position }}"
                ],
                "multiple_choice_correct_option": "{{ position }}",
                "is_verifiable": true,
                "is_required": false
            }, {
                "id": "0f1aebd6-2286-435f-bd81-f9d8e9a0645d",
                "index": 1,
                "question": "Did {{ first_name }} {{ last_name }} work at {{ company_name }} from {{ start_date }}{% if end_date %} to {{ end_date }}{% endif %}?",
                "type": "TRUE_FALSE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": true,
                "is_required": false
            }, {
                "id": "4c1d943d-b595-4b7f-9983-be13a72e0003",
                "index": 2,
                "question": "If given the opportunity, would you hire {{ first_name }} {{ last_name }} again?",
                "type": "TRUE_FALSE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "1fedf7c4-0f7f-4546-841f-c6eb226da2b8",
                "index": 3,
                "question": "In general, how well did {{ first_name }} {{ last_name }} get along with customers, peers and/or managers (1 not at all, 10 very much so)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "f408d503-da54-42a4-b29e-d235bf9c890c",
                "index": 4,
                "question": "In general, did {{ first_name }} {{ last_name }} arrive on time to work (1 not at all, 10 very much so)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "e6c11a10-b4b8-4f47-a304-edf498e1e50f",
                "index": 5,
                "question": "How well did {{ first_name }} {{ last_name }} satisfy the requirements of the position (1 not satisfactory, 10 very satisfactory)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "aea311f1-a98d-42a5-b23b-a092affd275c",
                "index": 6,
                "question": "Did {{ first_name }} {{ last_name }} go above and beyond what was required without being asked (1 not at all, 10 very much so)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "cd1d12c0-002b-4090-a758-6904ad7c2bf1",
                "index": 7,
                "question": "How would you rate {{ first_name }} {{ last_name }}'s ability to handle high pressure or stressful situations (1 not good at all, 10 very good)?",
                "type": "NUMERIC_RANGE",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }, {
                "id": "3dc846b6-773e-4cfe-852d-5eec405c5f5c",
                "index": 8,
                "question": "Do you have any additional comments you'd like to provide regarding {{ first_name }} {{ last_name }}?",
                "type": "LONG_ANSWER",
                "multiple_choice_options": null,
                "multiple_choice_correct_option": null,
                "is_verifiable": false,
                "is_required": false
            }
        ]
    }
]

404: Not Found Team not found

This may be happening because:

The ID you provided couldn't be found

Add your team ID to the URL and make sure it's in the proper format.

See #404-not-found for more details.

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

Name	Type	Description
superteam	string <uuid>	Superteam id
team	string <uuid>	Team id
is_active	boolean

200: OK Users successfully retrieved

Response type

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>
        }
    ]
}

Example

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "c1b0c944-551a-46b5-ab88-bdf22f6b06fd",
            "first_name": "Joe",
            "last_name": "Bidem",
            "is_active": false,
            "superteam": "aafa6f6b-e394-4514-b2b4-e5cfdabcffa1",
            "team": "10626a80-00f2-4e04-9b99-16693f76a6ed"
        },
        {
            "id": "0ec5b68e-890b-4a40-992d-a5cb080abd46",
            "first_name": "User Three",
            "last_name": "lastname",
            "is_active": true,
            "superteam": "23554549-b086-4f74-94fe-ccf88e1c643b",
            "team": "6aba518e-1d98-4f97-bc77-c5cee59e44cd"
        }
    ]
}    

403: Forbidden Authentication failed

Retrieve a user's details

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

View a user's details.

Path Parameters

Name	Type	Description
user_id*	string <uuid>	User id

200: OK Details successfully retrieved

Response Type

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>
}

Example

application/json

{
    "id": "d04a8ade-4cf1-4bab-9ba5-c82b16c6daca",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "language": "en",
    "is_active": true,
    "superteam": "c10f334c-0af8-4fb9-8e42-736f555bb400",
    "team": "0de5550b-f93f-4075-a022-52b907592198"
}

403: Forbidden Authentication failed

Create a user

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

Create a new user.

Request Body

Name	Type	Description
first_name*	string	User's first name
last_name*	string	User's last name
email*	string	User's email, unique
language*	string <enum>	User's language. Must be either "en" or "fr"
team*	string <uuid>	Team id
is_active*	boolean	Default true

201: Created User successfully retrieved.

Response type

application/json

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

Example

application/json

{
    "id": "1ee80af9-e047-438d-a6d3-a14bbf179cfd",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "language": "en",
    "is_active": true,
    "team": "0de5550b-f93f-4075-a022-52b907592198"
}

400: Bad Request Missing required field(s) or invalid data

This is happening because:

You have missed one of the required parameters in the request body (see parameters above)

See #400-bad-request for more details.

400: Bad Request Invalid team id.

This may be happening because:

The incorrect team id was provided.

Enter the correct team id in your request.

See #400-bad-request for more details.

400: Bad Request <field name> is not a valid choice.

This may be happening because:

Field values are not in the pre-defined list.

Ensure you are using valid values for each field.

See #400-bad-request for more details.

400: Bad Request Email is already in use

This is happening because there is already a user registered by this email in our system. Emails must be unique.

403: Forbidden Authentication failed

Update a user

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

Path Parameters

Name	Type	Description
first_name*	string	User's first name
last_name*	string	User's last name
email*	string	User's email, unique
language*	string <enum>	Language for user details. Must be either "en" or "fr"
team*	string <uuid>	Team id
is_active*	boolean	Default true

200: OK User successfully updated

Response type

application/json

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

Example

application/json

{
    "id": "1ee80af9-e047-438d-a6d3-a14bbf179cfd",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "language": "en",
    "is_active": true,
    "team": "0de5550b-f93f-4075-a022-52b907592198"
}

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

You are missing required fields

Add all the required fields to the body of your request.

See #400-bad-request for more details.

400: Bad Request Invalid team id

This may be happening because:

The incorrect team id was provided.

Enter the correct team id in your request.

See #400-bad-request for more details.

400: Bad Request <field name> is not a valid choice

This may be happening because:

Field values are not in the pre-defined list.

Ensure you are using valid values for each field.

See #400-bad-request for more details.

403: Forbidden

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

Name	Type	Description
superteam	string <uuid>	Superteam id
team	string <uuid>	Team id

200: OK Packages successfully retrieved

Response Type

Example

403: Forbidden Authentication failed

Retrieve details for a specific package by id

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

Path Parameters

Name	Type	Description
package_id	string <uuid>	ID of the package

200: OK Package successfully retrieved

Response Type

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>
    }
}

Example

application/json

{
    "id": "35e95c65-ed02-4a34-948d-2267568fe69f",
    "name": "Package Name",
    "superteam": "c10f334c-0af8-4fb9-8e42-736f555bb400",
    "team": "0de5550b-f93f-4075-a022-52b907592198",
    "request_flags": [
        "request_enhanced_identity_verification",
        "request_social_media_check",
        "request_us_criminal_record_check_tier_1"
    ],
    "settings": {
        "requested_countries": [],
        "us_criminal_record_check_years": 7,
        "employer_questionaire_id": null,
        "address_questionaire_id": null,
        "employer_references_max": 1,
        "employer_references_min": 1,
        "address_references_max": 1,
        "address_references_min": 1,
        "employment_verification_min": 1,
        "employment_verification_max": 1,
        "education_verification_min": 1,
        "education_verification_max": 1,
        "credential_verification_min": 1,
        "credential_verification_max": 1,
        "credential_verification_level": "ALL",
        "education_verification_level": "ALL",
        "employer_references_years": 3,
        "address_references_years": 3,
        "employment_verification_years": 3,
        "address_references_years_or_individually": "INDIVIDUALLY",
        "employer_references_years_or_individually": "INDIVIDUALLY",
        "employment_verification_years_or_individually": "INDIVIDUALLY",
        "purpose_of_check": null,
        "position_title": "",
        "place_of_work": "",
        "license_type": "",
        "issuing_authority": "",
        "reason_for_check": "",
        "state_or_territory": "",
        "location_of_work": "",
        "volunteer_role": "",
        "volunteer_organization": "",
        "role_or_position_title": "",
        "employment_sector": ""
    }
}

404: Not Found Package not found

This may be happening because:

The pacakge_id you used doesn't exist.

Ensure you are using a valid id.

See #404-not-found for more details.

400: Bad Request Missing required field(s) or invalid data

403: Forbidden Authentication failed

Create a package

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

Request Body

Name	Type	Description
team	string <uuid>	Team id. Defaults to api user's team if not provided.
name*	string	Name of package
request_flags	list[string]	List of Request flags strings
settings	object	Package settings

201: Created Package successfully created

Response Type

application/json

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

Example

application/json

{
    "id": "2ffb4c49-96cf-4b31-8ec3-63ba2dfd3b3b",
    "name": "Package Name",
    "team": "0de5550b-f93f-4075-a022-52b907592198",
    "request_flags": [
        "request_enhanced_identity_verification"
    ]
}

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

You have missed a required field in your payload.

See #400-bad-request for more details.

403: Forbidden Authentication failed

Update a package

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

Path Parameters

Name	Type	Description
package_id*	string <uuid>	ID of package

Request Body

Name	Type	Description
name*	string	Name of package
team*	string <uuid>	Team id
request_flags*	list[string]	List of Request flags strings
settings*	object	Package settings

200: OK Package successfully updated

Response Type

{
    "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>
    }
}

Example

application/json

{
    "id": "35e95c65-ed02-4a34-948d-2267568fe69f",
    "name": "Package Name",
    "superteam": "c10f334c-0af8-4fb9-8e42-736f555bb400",
    "team": "0de5550b-f93f-4075-a022-52b907592198",
    "request_flags": [
        "request_enhanced_identity_verification",
        "request_social_media_check",
        "request_us_criminal_record_check_tier_1"
    ],
    "settings": {
        "requested_countries": [],
        "us_criminal_record_check_years": 7,
        "employer_questionaire_id": null,
        "address_questionaire_id": null,
        "employer_references_max": 1,
        "employer_references_min": 1,
        "address_references_max": 1,
        "address_references_min": 1,
        "employment_verification_min": 1,
        "employment_verification_max": 1,
        "education_verification_min": 1,
        "education_verification_max": 1,
        "credential_verification_min": 1,
        "credential_verification_max": 1,
        "credential_verification_level": "ALL",
        "education_verification_level": "ALL",
        "employer_references_years": 3,
        "address_references_years": 3,
        "employment_verification_years": 3,
        "address_references_years_or_individually": "INDIVIDUALLY",
        "employer_references_years_or_individually": "INDIVIDUALLY",
        "employment_verification_years_or_individually": "INDIVIDUALLY",
        "purpose_of_check": null,
        "position_title": "",
        "place_of_work": "",
        "license_type": "",
        "issuing_authority": "",
        "reason_for_check": "",
        "state_or_territory": "",
        "location_of_work": "",
        "volunteer_role": "",
        "volunteer_organization": "",
        "role_or_position_title": "",
        "employment_sector": ""
    }
}

404: Not Found Package not found

This may be happening because:

The pacakge_id you used doesn't exist.

Ensure you are using a valid id.

See #404-not-found for more details.

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

You have missed a required field in your payload.

See #400-bad-request for more details.

403: Forbidden Authentication failed

Delete a package

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

Path Parameters

Name	Type	Description
package_id*	string <uuid>	ID of package

200: OK Package successfully deleted

404: Not Found Package not found

This may be happening because:

The pacakge_id you used doesn't exist.

Ensure you are using a valid id.

See #404-not-found for more details.

400: Bad Request Missing required field(s) or invalid data

This may be happening because:

You have missed a required field in your payload.

See #400-bad-request for more details.

403: Forbidden Authentication failed