Groups: Joint Accounts with Individual Applicants

Decisioning on Each Individual

1. The client generates an 'Alloy-External-Group-ID' for a joint account, which will be their application ID, a unique ID that corresponds to the whole application session. It will be used to associate the joint applicants together into one group.

2. For each joint applicant, make a POST request to the /evaluations endpoint ( https://developer.alloy.com/public/reference/post_evaluations), with the addition of the following:

• Add 'Alloy-External-Group-Id' with the corresponding unique string as a header.
• Add a "meta" object in the body of the POST request with corresponding key-value pairs for the 'applicant_role,' which can be 'primary' or 'secondary.' This will allow you to use Input Attributes to use this information in decisioning. For example, if you only wanted to trigger KBA questions for the primary applicant, you could do this using your Input Attribute.

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

*Remember to switch the URL from 'sandbox' to 'api' for live evaluations. The application_token and application_secret should correspond to the Individual Workflow Token & Individual Workflow Secret (https://developer.alloy.com/public/docs/authentication-guide)

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": "Jane",
    "name_last": "Doe",
    "document_ssn": "555555555",
    "birth_date": "1990-01-01",
    "phone_number": "55555555555",
    "email_address": "jane@fortesting.com",
    "address_line_1": "123 Fake St.",
    "address_city": "Faketown",
    "address_state": "NY",
    "address_postal_code": "11111",
    "address_country_code": "US",
"meta": {
    "applicant_role": "primary"
    }
}'

If successful, you will receive a response similar to the reaction shown below. Notice that Alloy generates a 'group_token' which will be used to evaluate the Group as a whole after each individual entity within the group has been evaluated. This 'group_token' is going to be the same in both evaluations!

{
    "status_code": 201,
    "error": null,
    "timestamp": 1585321707350,
    "evaluation_token": "S-OiH1f0TbsVxBf8mioizL",
    "entity_token": "B-V9qCPWeRoIdmSYCrlDwn",
    "parent_entity_token": null,
    "group_token": "G-VnOpPeJV1bOLh8FIcaOI", //this was just created!
    "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. Once your evaluations have been run, you'll be able to see the status of them from the Alloy dashboard. If either of the Individuals in the Group received a "Manual Review" outcome, you'll need to decision on those before you can decision on the group itself (see the last section of this document called Handling Groups Within the Review Queue).

Decisioning on the Group

Once each individual in the Joint application has been decisioned on, the group as a whole will need to be decisioned on in a separate workflow, as already mentioned. We'll call that workflow "Group Evaluations." The outcome logic may be configured to suit a client's 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

As you can see in the screenshot below, at this point, the group does not have a status:

In order to get the group's outcome status (Approved, Denied, or Manual Review) you'd run it through the Group Evaluations workflow:

To evaluate the group as a whole, you will make a call to that Group Evaluations workflow using your Alloy-External-Group-ID. Remember to use the Auth token and secret of this Groups workflow, and not the Individual workflow. Also, note that you'd have an empty request body.

This is what you would call that separate "Group Evaluations" workflow:

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

As a CURL request:

curl -X POST <https://sandbox.alloy.co/v1/groups/><Alloy-External-Group-ID>/evaluations
 -H 'Authorization: Bearer NQXJ0LlhJkCU2dRubdgmtyrENitz8CihxZQ5dUNt'
 -H 'Content-Type: application/json' \\ -d $'{}'

Handling Groups Within the Review Queue

If either individual applying for the Joint Account received a Manual Review outcome, that entity must be reviewed and decisioned on before the group can be decisioned on. Each entity must have an outcome of Approved or Denied before you can decision on the group. Follow the steps below (in the dashboard) to make sure you're ready to decision on the group:

1. Filter for the Type "Groups" from the Review Queue.

2. When ready to decision on a selected group, click the "Review Group" button in the top center of the page:

3. If the "Review Group" button is greyed out, this means that individual entities within the group need to be decisioned on before the group can be reviewed:

The reviewer must check the column on the left-hand side of the screen. If either of the entities is not "Approved" or "Denied," they would click on that entity and submit a review.

4. In the dashboard, the reviewer would select the "Review Group" button. A pop-up window appears to select the Outcome chosen for this group, as well as a Review Reason, and notes (if any).

Please see the Decisioning on a Group section above in order to see how that API call is made.