### 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](https://docs.certn.co/api/api-reference/resources/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.

### Retrieve a list of your superteams

`GET https://api.certn.co/api/v1/superteams/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

View the list of your superteams.

200: OK Superteam successfully retrieved

403: Forbidden Authentication failed

Response type

```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}/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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

403: Forbidden Authentication failed

Response Type

```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/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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](https://docs.certn.co/api/api-reference/resources/region-codes#provinces-and-states) for Superteam's primary location |
| country*               | string | 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

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

403: Forbidden Authentication failed

Response type

```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}/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

#### Path Parameters

| Name           | Type   | Description                       |
|----------------|--------|-----------------------------------|
| superteam_id *| string | 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

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

403: Forbidden Authentication failed

Response type

```json
{
    "id": string <uuid>,
    "name": string,
    "is_secure_sms_enabled": boolean,
    "street_address": string,
    "city": string,
    "postal_code": string,
    "province_state": string,
    "other_province_state": string,
    "country": 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.

### Retrieve a list of your teams

`GET https://api.certn.co/api/v1/teams/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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

#### Query Parameters

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

200: OK Teams successfully retrieved

403: Forbidden Authentication failed

Response type

```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}/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

View the details of a team.

#### Path Parameters

| Name       | Type      | Description        |
|------------|-----------|----------------------|
| team_id    | string <uuid> | Team id        |

200: OK Team successfully retrieved

403: Forbidden Authentication failed

Response Type

```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/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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](https://docs.certn.co/api/api-reference/resources/region-codes#countries) 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](https://docs.certn.co/api/api-reference/resources/region-codes#provinces-and-states) 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

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

400: Bad Request Invalid superteam id

403: Forbidden Authentication failed

Response type

### Update a team

`PUT https://api.certn.co/api/v1/teams/{team_id}/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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](https://docs.certn.co/api/api-reference/resources/region-codes#countries) 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                                                                            |
| province_state*            | string | [ISO province or state code](https://docs.certn.co/api/api-reference/resources/region-codes#provinces-and-states) 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                                         |
| 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                                        |

200: OK Team successfully updated

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

400: Bad Request <field> cannot be updated

403: Forbidden Authentication failed

Response type

## Retrieve a team's address reference templates

`GET https://api.certn.co/api/v1/teams/{team_id}/address/reference_templates/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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

404: Not Found Team not found

Response type

```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/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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

404: Not Found Team not found

Response type

```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?**](https://app.certn.co/login) link.

### Retrieve a list of users

`GET https://api.certn.co/api/v1/users/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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

403: Forbidden Authentication failed

Response type

```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}/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

View a user's details.

#### Path Parameters

| Name       | Type      | Description        |
|------------|-----------|---------------------|
| user_id    | string <uuid> | User id            |

200: OK Details successfully retrieved

403: Forbidden Authentication failed

Response Type

```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/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

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 created.

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

400: Bad Request Invalid team id.

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

400: Bad Request Email is already in use

403: Forbidden Authentication failed

Response type

```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}/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

#### Path Parameters

| Name             | Type      | Description        |
|------------------|-----------|---------------------|
| user_id          | string <uuid> | User id            |

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

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

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

403: Forbidden

Response type

## 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.

### Retrieve your packages

`GET https://api.certn.co/api/v1/packages/` [`DEPRECATED`](https://docs.certn.co/api/deprecation)

#### Query Parameters

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

200: OK Packages successfully retrieved

403: Forbidden Authentication failed

Response Type

```json
// Example response object can be structured here.```