Note: Groups is a legacy feature for the Groups model - They were the older way to represent one application involving multiple entity evaluations. Journeys replaced the Groups model, and the Group Evaluation endpoint is now deprecated in favor of Multi-Entity Applications in Journeys.
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)
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
sandboxtoapifor live evaluationsNote: The
application_tokenandapplication_secretshould 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_tokenwhich 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"
}
}'
Response: If successful, you will receive a response similar to the response shown below.
Note: The
group_tokenis 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
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-Tokengenerated by Alloy is not the same as theExternal-Group-IDused 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.
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.
3. Click on the Review button in the entity’s Evaluation from the Group view.
4. Select an outcome for the Manual Review and provide a Review Reason.
5. 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.
6. Once you’ve submitted your Group Review, the status of the Group will change.