Groups: Joint Business/Shareholder Accounts

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

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. 

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",
    ...
}

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"
}
}'

• 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",
    ...
}

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 a "Group Evaluation" workflow, shown below.

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.

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

3. 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:

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

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

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

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