1. Data Collection

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

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