Person Reason Codes

Status reasons

If a person fails customer identification, Orum sends 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 your 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.

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

Example Webhook Payload

Deliver sends 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"
        }
    }
}