# Working with Packages

Once your customer’s account is connected and has been credentialed, they may begin to order background checks from your application. A Package is a collection of Checkr Screenings, which may include criminal checks, motor vehicle records, or other background checks.

Packages may be selected for a candidate (select a Package for a candidate when ordering the background check), or for a job position (select a Package for a position, to be applied to all candidates placed against that position). Your use case will be dependent on workflows within your application.

For more information on screenings, see the [Screening Types](https://help.checkr.com/hc/en-us/sections/203637147-Screening-Types) section of the Checkr Help Center.

## Create Packages

Work with your Checkr Partner Manager to define the set of background check Packages and their pricing for your Partner account. Your connected customer accounts will inherit these Packages and prices by default. Your customers may also choose to configure their own packages in addition to these.

## Retrieve a customer’s Package list

In some cases a connected customer account may have additional Packages configured that differ from those defined at the Partner account level. There may be accounts that already exist and are connected through the Sign In flow, or your customers may contact Checkr to add additional screening types required for their business. Because of this, we recommend using the customers' `access_token` to retrieve the Package list that will populate your Package selection interface, instead of relying on your partner account's Package list.

To order background checks for your customers using the `POST /invitations` call, you must know whether they are using account hierarchy to structure their account, and whether they are associating nodes within that hierarchy to their packages.

Use `GET /nodes` to determine whether your customer is using Account Hierarchy nodes and whether they have associated any packages to those nodes.

##### Retrieve a customer's Account Hierarchy nodes (if enabled) and any Package associations to those nodes

```sh
$ curl -X GET https://api.checkr.com/v1/nodes?include=packages -u {access_token}:
```

##### Example response

```json
{
   "data": [
       {
           "custom_id": "ROOT_74407af0533e",
           "name": "Root",
	   "packages": [
                "tasker_standard"
            ],
           "tier": "Company",
           "parent_custom_id": null
       },
       {
           "custom_id": "CHLD_e7c3ab7bf4ad",
           "name": "Child 1",
           "tier": "Department",
           "parent_custom_id": "ROOT_74407af0533e",
       },
       {
           "custom_id": "CHLD_a106e1bfcfd2",
           "name": "Child 2",
           "tier": "Department",
           "parent_custom_id": "ROOT_74407af0533e",
       }
   ],
   "object": "list",
   "next_href": null,
   "previous_href": null,
   "count": 3
}
```

To display the packages returned from the `GET /nodes?include=packages` API call in your partner application, take the value(s) in the `packages` array, replace any underscores with spaces, and capitalize each word in the package name. (For example: Display "tasker_standard" as "Tasker Standard".)

The payload returned from the `GET /nodes?include=packages` call will determine what you need to do in your partner application:

* If the `GET /nodes?include=packages` API call returns any nodes, present a nodes drop-down and require the user to select the node they wish to associate to this background check invitation.
  * If the node selected by the customer has any packages associated to it, list ONLY those packages for selection
* In all other cases (if no nodes are returned, an error is returned, or nodes are returned but without any package associations), make a separate call to the `GET /packages` API endpoint call to retrieve all configured packages on the customer's account.


##### Retrieve a customer's package list

```sh
$ curl -X GET https://api.checkr.com/v1/packages -u {access_token}:
```

##### Example response

```json
{
  "data": [
    {
      "id": "c6759e59e807618f8bcbd37a",
      "object": "package",
      "price": 2500,
      "apply_url": "https://apply.checkr.com/apply/customer-services-inc/532c20ea819b",
      "created_at": "2019-08-07T22:17:50Z",
      "deleted_at": null,
      "name": "Tasker Standard",
      "screenings": [
        {
          "type": "county_criminal_search",
          "subtype": "current"
        },
        {
          "type": "national_criminal_search",
          "subtype": "standard"
        },
        {
          "type": "sex_offender_search",
          "subtype": null
        },
        {
          "type": "ssn_trace",
          "subtype": null
        },
        {
          "type": "global_watchlist_search",
          "subtype": null
        }
      ],
      "slug": "tasker_standard",   // used for subsequent API calls
      "uri": "/v1/packages/c6759e59e807618f8bcbd37a"
    }
  ],
  "object": "list",
  "next_href": null,
  "previous_href": null,
  "count": 1
}
```

The response is paginated and contains 25 objects at a time. If the account contains more than 25 Packages, you will need to iterate through the paginated list or specify the **per_page** limit as described in the [Pagination](https://docs.checkr.com/#section/Reference/Pagination) section of the API documentation. In this case, use the "name" field in the returned payload as the value to present for selection in your application.

You may also choose to cache the Package list and listen for each customer's `package.*` webhook events for updates. Checkr will transmit a webhook event for `package.created`, `package.updated`, and `package.deleted`. See the [Webhooks](/partners/webhooks) section for more information on consuming Checkr webhooks.