Check digit API

[awolfe76]

### Feel free to comment with changes here. This is just a suggestion to get us started.

Based on conversations that endpoints and responses have been updated ... but still feel free to comment. 😄

We'll need 2 endpoints for the check digit API. Both should return json response and file uploads should allow for both json and CSV responses.

A few quick notes:

• the validation for a ULI can be found on page 20 of the 2018 FIG
  • alphanumeric
  • max width of 45 characters
• ULI check digit is calculated using the ISO/IEC 7064, MOD 97-10 as it appears on the International Standard ISO/IEC 7064:2003, which is published by the International Organization for Standardization (ISO)
  • https://www.iso.org/obp/ui/#iso:std:iso-iec:7064:ed-1:v1:en
  • https://github.com/stvkoch/ISO7064-Mod-97-10

---

/checkDigit and /checkDigit/csv

POST - Accepts a single loan id input or a file upload and responds with the check digit(s).

Single input

Example POST data:

{
  "loanId": "1A2B3C4D5E6F"
}

Example single input response, in json format:

{
  "loanId": "1A2B3C4D5E6F",
  "checkDigit": "22",
  "uli": "1A2B3C4D5E6F22"
}

File upload

Example file upload (loans.txt):

1A2B3C4D5E6F
2B3C4D5E6F7G
3C4D5E6F7G8H
4D5E6F7G8H9I
...

Example file upload response, in json format:

{
  "loanIds": [
    {
      "loanId": "1A2B3C4D5E6F",
      "checkDigit": "22",
      "uli": "1A2B3C4D5E6F22"
    },
    {
      "loanId": "2B3C4D5E6F7G",
      "checkDigit": "33",
      "uli": "2B3C4D5E6F7G33"
    },
    {
      "loanId": "3C4D5E6F7G8H",
      "checkDigit": "44",
      "uli": "3C4D5E6F7G8H44"
    },
    {
      "loanId": "4D5E6F7G8H9I",
      "checkDigit": "55",
      "uli": "4D5E6F7G8H9I55"
    }
  ]
}

Example file upload response, in CSV format:

loanId, checkDigit, uli
1A2B3C4D5E6F, 22, 1A2B3C4D5E6F22
2B3C4D5E6F7G, 33, 2B3C4D5E6F7G33
3C4D5E6F7G8H, 44, 3C4D5E6F7G8H44
4D5E6F7G8H9I, 55, 4D5E6F7G8H9I55

---

/checkDigit/validate

POST - Accepts a single ULI input or a file upload and responds with true/false.

Single input

Example POST data:

{
  "uli": "1A2B3C4D5E6F22"
}

Example single input response, in json format:

{
  "isValid": true
}

File upload

Example file (ulis.txt):

1A2B3C4D5E6F22
2B3C4D5E6F7G33
3C4D5E6F7G8H44
4D5E6F7G8H9I55
...

Example file upload response, in json format:

{
  "ulis": [
    {
      "uli": "1A2B3C4D5E6F22",
      "isValid": true
    },
    {
      "uli": "2B3C4D5E6F7G33",
      "isValid": true
    },
    {
      "uli": "3C4D5E6F7G8H44",
      "isValid": true
    },
    {
      "uli": "4D5E6F7G8H9I55",
      "isValid": false
    }
  ]
}

Example file upload response, in CSV format:

uli, isValid
1A2B3C4D5E6F22, true
2B3C4D5E6F7G33, true
3C4D5E6F7G8H44, true
4D5E6F7G8H9I55, false

[jmarin]

@awolfe76 Quick question about the second API endpoint. According to the spec as published in Regulation C there are two operations here:

1) Calculate check digit from loan id (loan id is LEI + loan or application identifier). A Universal Loan Identifier (ULI) is then calculated by appending loan id followed by the check digit 2) Validate ULI. Given a complete ULI, determine whether it contains transcription errors with the check digit calculation

The second API endpoint is asking for a conversion from check digit --> ULI, but that is something that based on this spec can't be done. The check digit is two numbers, while the ULI is a large string. What am I missing?

[awolfe76]

Good point (and good catch). I think I had the wrong terminology.

Based on what you found in Reg C it looks like we should be asking for a "loan id" as an input and from that, we should be able to return the check digit AND the ULI. Not sure if we need to return both but it doesn't hurt.

Then, the reverse would be asking for the ULI and from that, we should be able to return the loan id AND the check digit. OR we could just return true/false, valid or not.

Does that make more sense? Probably worth a bit of discussion.

[keileyo]

If it is helpful - here is how we show the LEI/Loan ID/Check Digit breakdown in the FIG.