Person statuses

In the Orum system, a person can have one of the following statuses, indicated by the status field:

  • Created - A person was created to represent an individual or a person’s record was updated. The person is not able to send or receive funds.
  • Verified - A person passed customer identification. The person is able to send or receive funds.
  • Rejected - A person did not pass customer identification. The person is not able to send or receive funds.
  • Restricted - A person matched a sanctions list during watchlist screening. The person is not able to send or receive funds.
  • Closed - A person has been soft deleted in Orum’s platform. The person is not able to send or receive funds. This status is terminal and once a person enters this state they are unable to change statuses even after PUT or PATCH updates. This status is only assigned via a manual request.

The diagram below shows how a person can move through the above statuses. Note that a person can move from Verified to Restricted if a person matches a sanctions list anytime after their initial customer identification. To learn more about why a person is in the Rejected or Restricted state, refer to the status_reason field in the API response.

If a person fails customer identification and is set to the rejected status, Orum will automatically kick off a manual review and attempt to retry the customer identification workflow to resolve the issue.

18421842

Status reasons

If a person fails customer identification, Orum will send a person_rejected or person_restricted webhook. The person object in the webhook will have a status of "rejected" or "restricted" and a status_reasons array that explains why the person failed customer identification.

status_reasons consist of:

  • reason_code a word-based code that describes the customer identification failure
  • reason_code_message a friendly description of the reason code that can be surfaced directly to end users

To reattempt customer identification, you can use the PATCH /persons endpoint to update any invalid or missing information.

status_reasons will also be present in the GET /persons and GET /persons/{id} API responses.

Sample webhook payload

Momentum will send webhooks to notify you of changes to a person's status.

{
    "event_id": "0p0aw9a4-d9ab-49d1-97da-7253ea40wd09",
    "event_type": "person_rejected",
    "created_at": "2022-08-26T18:40:31.775Z",
    "event_data": {
        "person": {
            "id": "b4c780fd-cn90-427f-a12d-60d4709410d7",
            "customer_reference_id": "4m70-da8pv1-3md086",
            "first_name": "Jane",
            "last_name": "Tester",
            "date_of_birth": "2010-01-01",
            "status": "rejected",
            "status_reasons": [
                {
                    "reason_code": "invalid_address_type",
                    "reason_code_message": "Address submitted is a non-supported address type"
                },
                {
                    "reason_code": "ineligible_age",
                    "reason_code_message": "Age submitted is under 18 and not eligible for this product"
                }
            ],
            "addresses": [
                {
                    "id": "pw9ad970-637f-4e4a-b808-917efce373dn",
                    "address1": "PO Box 100",
                    "city": "New York",
                    "state": "NY",
                    "country": "US",
                    "zip5": "10001",
                    "created_at": "2022-08-26T18:28:50.569975Z",
                    "updated_at": "2022-08-26T18:28:50.569975Z"
                }
            ],
            "contacts": [
                {
                    "id": "pr8d8aa5-cdcf-4e31-82b4-c438e786e5w7",
                    "value": "[email protected]",
                    "created_at": "2022-08-26T18:28:50.569975Z",
                    "updated_at": "2022-08-26T18:28:50.569975Z"
                },
                {
                    "id": "c8479dd1-2d98-4967-a4f8-18d9e1e9a8bv",
                    "value": "+15552346789",
                    "created_at": "2022-08-26T18:28:50.569975Z",
                    "updated_at": "2022-08-26T18:28:50.569975Z"
                }
            ],
            "created_at": "2022-08-26T18:28:50.569975Z",
            "updated_at": "2022-08-26T18:29:12.052262Z"
        }
    }
}

Possible status reasons

reason_codereason_code_message
deceased_personUser is reported as deceased
incomplete_addressAddress submitted is missing some or all required elements
incomplete_dobDate of birth submitted is missing some or all required elements
incomplete_ssnSSN submitted is missing some or all required elements
ineligible_ageAge submitted is under 18 and not eligible for this product
invalid_address_typeAddress submitted is a non-supported address type
invalid_dobDate of birth is invalid
invalid_nameName is invalid
invalid_ssnSSN is invalid
matched_alertlistMatched a list of known fraudulent users
matched_watchlistMatched one or multiple sanctions lists