API Documentation: Customer Usage Guide

Overview

This document provides a step-by-step guide for interacting with the API provided by Aletheia Systems. The API enables customers to validate user admissions information via HTTP requests. This guide includes details on authentication, request formats, and examples for validating single or multiple records.

---

Authentication

To access the API, you must first obtain a set of tokens (Access Token, Refresh Token, and Id Token). These tokens are used to authenticate subsequent API requests.

Endpoint:

https://api.aletheiasystems.com/login

Request:

curl -u 'username:password' https://api.aletheiasystems.com/login

Example Response:

{
  "AccessToken": "<redacted_access_token>",
  "ExpiresIn": 3600,
  "TokenType": "Bearer",
  "RefreshToken": "<redacted_refresh_token>",
  "IdToken": "<redacted_id_token>"
}

---

Validating User Admissions Information

Once authenticated, use the access token to validate user admissions information. The API supports two validation methods:

1. Single Record Validation (via GET)
2. Multiple Records Validation (via POST)

Input Parameters

The following fields can be included in validation requests:

• fname (First Name)
• lname (Last Name)
• mname (Middle Name)
• email (Email Address)
• phone (Phone Number)
• addressline1, addressline2, addressline3, addressline4
• country
• city
• state
• postalcode
• ip (IP Address)

1. Single Record Validation

Use the GET method to validate a single record by providing the required parameters in the query string.

Endpoint:

https://api.aletheiasystems.com/validate

Example Request:

curl -H "Authorization: Bearer ${AccessToken}" 'https://api.aletheiasystems.com/validate?addressline1=123+some+street&city=Miami&state=fl&postalcode=&email=&fname=Fred&lname=Flintstone&phone=&ssn='

Example Response:

{
  "status": [
    {"code": "CAE02", "short": "Unknown Street", "long": "Could not match the input street to a unique street name. Either no matches or too many matches found."},
    {"code": "CAS81", "short": "Non Residential Address", "long": "The address is a business or unknown address type"}
  ],
  "nascore": 14,
  "adscore": 17,
  "score": 15
}

2. Multiple Records Validation

Use the POST method to validate multiple records. Each record should include a recordid field, which will be returned in the response for easier tracking.

Endpoint:

https://api.aletheiasystems.com/validate

Example Request:

curl -H "Content-Type: application/json" -H "Authorization: Bearer ${AccessToken}" -X POST -d '{
"Records": [
  {
    "recordid": 112,
    "city": "State University",
    "name": "Accounts Payable/Disbursing",
    "addressline2": "",
    "company": "Arkansas State University",
    "addressline1": "PO Box 850",
    "state": "AR"
  },
  {
    "recordid": 113,
    "city": "Russellville",
    "name": "Accounts Payable",
    "addressline2": "",
    "company": "Arkansas Tech University",
    "addressline1": "1505 N Boulder Ave Rm 302",
    "state": "AR"
  }
]
}' 'https://api.aletheiasystems.com/validate'

Example Response:

{
"Results": [
  {
    "status": [
      {"code": "CAC01", "short": "Postal Code Change", "long": "The postal code was changed or added."},
      {"code": "CAS01", "short": "Address Fully Verified", "long": "The address is valid and deliverable according to official postal agencies."},
      {"code": "CAS20", "short": "Deliverable Only by USPS", "long": "US Only. This address can only receive mail delivered through the USPS (i.e. PO Box or a military address)."},
      {"code": "CAS81", "short": "Non Residential Address", "long": "The address is a business or unknown address type"}
    ],
    "adscore": 31,
    "score": 31,
    "recordid": 112
  },
  {
    "status": [
      {"code": "CAC01", "short": "Postal Code Change", "long": "The postal code was changed or added."},
      {"code": "CAS01", "short": "Address Fully Verified", "long": "The address is valid and deliverable according to official postal agencies."},
      {"code": "CAS17", "short": "No USPS Mail Delivery", "long": "This address is classified as not receiving mail by the USPS via their No-Stat flag. Delivery might still be possible by third party carriers but that cannot be counted on."},
      {"code": "CAS23", "short": "Extraneous Suite Information", "long": "Extraneous information not used in verifying the address was found. This information was returned in the suite field."},
      {"code": "CAS81", "short": "Non Residential Address", "long": "The address is a business or unknown address type"}
    ],
    "adscore": 39,
    "score": 39,
    "recordid": 113
  }
]
}

---

Additional Notes

• Ensure all requests include the Authorization header with a valid access token.
• Response details, such as status codes and their meanings, will be covered in a separate document.