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:
