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: