## Why use our Partner Data Collection API?

Our Data Collection API empowers third-party integrations within the Fountain platform, allowing you to build and configure seamless experiences using a simple JSON API. This means that you can create an integrated hiring journey for candidates without the hassle of redirection to external domains, email verifications, or creating accounts within the partner platforms.

## What is Partner Data Collection?

Partner Data Collection is a powerful feature that enhances candidate interactions by offering a straightforward and unified user interface. It's the key to attracting and retaining candidates. This feature enables external services like Background Check Providers and more to seamlessly integrate with the Fountain platform. When third-party services need specific data attributes (check out our supported data types), the Fountain platform collects the required information directly from candidates. The platform then submits this data to the third party, all while ensuring candidates remain within the Fountain ecosystem. These third-party companies communicate the service results back to Fountain, which in turn automatically updates candidate profiles based on rules set by the hiring company.

## How does it work?

Imagine a company called Background Validation Inc (BVI) that provides a background check service and a company called The Klean Team (TKT) that provides cleaning services. TKT uses Fountain for hiring and has configured their funnel to use BVI for background checks.

Assuming BVI has been setup as a Partner within Fountain they would update their `settings_webhook` to include a new key `account_option_configurations`. This is how we link the data collection configuration to the existing `account_options` key that is used in other/older Partner integrations. Under a given key of `account_options` there must be a matching key under `account_option_configurations` for Partner Data Collection. Under the corresponding `account_option_configurations` key is a single key, `attributes` which is an array of Data Collection fields.

BVI provides different types of background checks and each one of those types corresponds to a key under both `account_options` and `account_option_configurations`. In this example there will be 2 options provided by BVI.

## Example

JSON

```json
{
  "account_options": [
    {
      "package_basic": "Basic Background Check",
      "package_advanced": "Advanced Background Check"
    }
  ],
  "account_option_configurations": [
    {
      "package_basic": {
        "attributes": [
          {
            "name": "First name",
            "description": "The candidates first name",
            "type": "text_field",
            "key": "first_name",
            "required": true,
            "order": 1,
            "hint": "What is your name?"
          },
          {
            "name": "Date of Birth",
            "description": "The candidates date of birth",
            "type": "datepicker",
            "key": "string",
            "required": true,
            "order": 2,
            "hint": "What was the dates of your birth?"
          }
        ]
      },
      "package_advanced": {
        "attributes": [
          {
            "name": "First name",
            "description": "The candidates first name",
            "type": "text_field",
            "key": "first_name",
            "required": true,
            "order": 1,
            "hint": "What is your name?"
          },
          {
            "name": "Date of Birth",
            "description": "The candidates date of birth",
            "type": "datepicker",
            "key": "string",
            "required": true,
            "order": 2,
            "hint": "What was the dates of your birth?"
          },
          {
            "name": "Are you a citizen of the United States?",
            "description": "string",
            "type": "radio",
            "key": "is_us_citizen",
            "required": true,
            "order": 3,
            "hint": "Are you an American?",
            "options": [
              [
                "Yes",
                "yes"
              ],
              [
                "No",
                "no"
              ]
            ]
          },
          {
            "confirm": true,
            "depends_on": {
              "skip_value": "no",
              "key": "is_us_citizen"
            },
            "name": "Please mention SSN",
            "description": "if they are a US Citizen",
            "type": "text_field",
            "key": "ssn",
            "required": true,
            "order": 4,
            "hint": "This is a sample hint"
          },
          {
            "name": "Address History",
            "description": "The history of your addresses.",
            "type": "history_address",
            "key": "string",
            "required": true,
            "order": 5,
            "hint": "string",
            "scope": 5
          }
        ]
      }
    }
  ]
}
```

This payload defines two packages, `package_basic` and `package_advanced`. The keys are defined in two locations, once under the `account_options` and once again under the `account_option_configurations`. The `package_basic` has just 2 short question where the `package_advanced` has five questions, uses the optional `confirm`, `depends_on` and `scope` attributes.

## Optional flags

### `confirm`

Confirm can be added to the `text_field` type. The applicant will be required to type the answer to the question twice to complete the question.

### `depends_on`

Depends on can be added to any question _except_ the last question in the data collection stage. Adding `depends_on` with a body of `{ skip_value: string, key: string }` will force a question to be skipped if the value of a previous question equals a given value. The `key` value should match the previous question's `key` and the value should match the value. It is designed to be used with a `radio` input.

### `scope`

Scope is used with history questions (`history_address` and `history_employment`) and is used to define the number of years of history required to complete the question. If the `scope` was 5 then it would be all the history from today back five years. It is suggested to put that value in the hint to help the applicant understand the expectations.