Creating Groups for Joint Business/Shareholder Accounts

Abby Benvenutti

Modified on: Fri, 17 Apr, 2020 at 5:11 PM

This process requires 2 separate workflows - one for the individual applicants to be decisioned on, and one "Group Evaluations" workflow which allows you set the outcome logic for decisioning on the Group as a whole, depending on the results of the individuals' evaluations.

Part 1: Decisioning on the Business & Individual Shareholder(s)

Step 1: The client creates a unique `Alloy-External-Group-ID` string which will be used to group the business and the entities related to the business in the group.

Step 2: Create a `POST` request for the Business to the `/evaluations` endpoint, which will be the primary entity in the group (https://docs.alloy.co/#Onboard-a-Person)

a. Add `Alloy-External-Group-ID` with the corresponding unique string as a header

b. Add a `meta` object in the body of the POST request with corresponding key-value pairs for the `applicant_role`. The Business itself should be the `primary` role in this group.

As a cURL Request, your POST should look something like this:

Note: Remember to switch the url from `sandbox` to `api` for live evaluations

Note: The application_token and application_secret should correspond to the Business Workflow Token & Business Workflow Secret (https://docs.alloy.co/#Authentication)

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Content-Type: application/json" \
  -H "Alloy-External-Group-ID":<your_unique_string_here> \
  -u application_token:application_secret \
  -d $'{
"business_name": "Test Business",
"business_address_line_1": "1 Business Street",
"business_address_city": "Brooklyn",
"business_address_state": "NY",
"business_address_postal_code": "11206",
"meta": {
  "applicant_role": "primary"
  }
}'

Response: If successful, you will receive a response similar to the response shown below.
Note: Alloy generates a `group_token` which will be used to evaluate the Group as a whole after each entity within the group has been evaluated.

{
    "status_code": 201,
    "error": null,
    "timestamp": 1585321707350,
    "evaluation_token": "S-OiH1f0TbsVxBf8mioizL",
    "entity_token": "B-V9qCPWeRoIdmSYCrlDwn",
    "parent_entity_token": null,
    "group_token": "G-VnOpPeJV1bOLh8FIcaOI",
    "application_token": "3Xa0MoSY8HOGT1FoP1TOKYJTq9xbImMM",
    "application_version_id": 1,
    "champion_challenger_id": null,
    "summary": {
        "result": "success",
        "score": 0.95,
        "tags": [
            "FEIN Found",
            "Company Name Verified",
            "Phone Matched",
            "Representative Match",
            "Address Matched"
],
        "outcome_reasons": [],
        "outcome": "Approved",
    ...
}

Step 3: Similar to Step 2, you will now create a `POST` request for the UBO(s) tied to the business. Use the same `Alloy-External-Group-ID` in the header but change the application_token and application_secret to the Individual Workflow Token & Individual Workflow Secret. Additionally, in the meta object, the “applicant_role” should be “secondary” instead of “primary”.

Note: If you wish to evaluate several shareholders for the same business group, you will need to make a separate request for each individual.

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Content-Type: application/json" \
  -H "Alloy-External-Group-ID": <your_unique_string_here> \
-u application_token:application_secret \
-d $'{
"name_first": "Shareholder",
"address_line_1": "1 Test Street",
"address_city": "Brooklyn",
"address_state": "NY",
"address_postal_code": "11206",
"meta": {
    "applicant_role": "secondary"
}
}'

Response: If successful, you will receive a response similar to the response shown below.

Note: The `group_token` is the same in both evaluations

{
    "status_code": 201,
    "error": null,
    "timestamp": 1585322957330,
    "evaluation_token": "S-dzwMC8A0U7waQvAGwsws",
    "entity_token": "P-bep8fFk3FlDZPhkohh66",
    "parent_entity_token": null,
    "group_token": "G-VnOpPeJV1bOLh8FIcaOI",
    "application_token": "kZoKteXv758qHx6ZYv84Rekgl2NJQXDM",
    "application_version_id": 2,
    "champion_challenger_id": null,
    "summary": {
        "result": "success",
        "score": 0.99,
        "tags": [
            "KYC SSN Match",
            "KYC Name Match",
            "KYC DOB Match",
            "Phone Match",
            "KYC Address Match"
],
        "outcome_reasons": [],
        "outcome": "Approved",
    ...
}

Step 4: Once your evaluations have been run, you’ll be able to see the status of them from the Alloy dashboard. If either the Business or Individuals in the Group received a “Manual Review” outcome, you’ll need to decision on those before you can decision on the group itself.

Part 2: Decisioning on the Group

Groups should be decisioned on in a workflow specific to “group” types, shown below. The outcome logic may be configured to suit your particular needs, though our Best Practice is as follows:

If: All evaluations within the group are Denied, then Deny the Group

Else if: All evaluations within the group are Approved, then Approve the Group

Else: Manual Review

Note: At this point, the Group does not have a status:

To generate an outcome for the group (Approved, Denied, or Manual Review), run them through the "Group Evaluation" workflow, shown below.

Step 1: Once each entity in the group has been evaluated & decisioned on, the group itself may be evaluated. Create a POST request to:

POST https://sandbox.alloy.co/v1/groups/<External-Group-ID>or<Alloy-Group-Token>/evaluations

Note: The `Group-Token` generated by Alloy is not the same as the `External-Group-ID` used to create the group; either may be used to create the request.

As a cURL request:

curl -X POST https://sandbox.alloy.co/v1/groups/<External-Group-ID>or<Alloy-Group-Token>/evaluations \
  -H "Content-Type: application/json" \
  -u application_token:application_secret \
  -d $'{}'

If all of the entities within the group were `Approved`, then the Group would be Approved; if all of the entities were `Denied`, then the group would be Denied. If any of the entities within the group received a `Manual Review` outcome, the Group will move into the Review Queue.

Handling Groups Within the Review Queue:

If an entity in a group received a Manual Review outcome, that entity must be reviewed & decisioned on first. After each entity has an outcome of Approved or Denied, the group itself can be reviewed & decisioned on.

Step 1: To view a list of all Groups within the Review Queue, clients may filter for the `Group` type:

Step 2: Review the entity/entities within the group which have an outcome of Manual Review.

Note: From the dashboard, you’ll notice that the `Review Group` button is disabled until all applicants in the group have an outcome of Approved or Denied:

Click on the `Review` button in the entity’s Evaluation from the Group view:

Select an outcome for the Manual Review and provide a Review Reason:

c. Once the review is submitted, the Group may be reviewed & decisioned on. The review process will be similar to that from the previous step. Click the `Review Group` button in the upper righthand corner and provide an outcome, along with a reason, and, optionally, a note.

Note: The `Review Group` button is no longer disabled.

d. Once you’ve submitted your Group Review, the status of the Group will change, as shown here:

Related Articles