# Klaus Lookup Service API

Klaus Lookup services is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes, authentication, and verbs.

## Our Endpoints

We aim to provide a simple and user-friendly API. We have 2 endpoint for searching Driver License and SSNDOB.
The endpoint availability are different for different user.

Every endpoint will always have 'status' field in response:
Values possible: **"ok"** or **"error"**.
No results response is still an OK response.
"error" can be in case of missing permissions, insufficient credits, invalid params or internal errors.

### Optional fields:
- **"body"**
Actual results of a search request. **list**
- **"message"**
Information about request, remaining credits or error message. **str**

### API Endpoints

#### User info

POST https://api.klauslookup.shop:5300/api/user/info

request data:

{
    "api_key": "<YOUR_API_KEY>"
}

Example response:

{
    "status": "ok",
    "data": {
        "credits": 880,
        "request_count": 43
    }
}

#### SSNDOB API endpoint

POST https://api.klauslookup.shop:5300/api/search/ssn

Request data:
First and Last name AND at least ONE PART of the ADDRESS is required

{
    "api_key": "<YOUR_API_KEY>",
    "search_params": {
        "fname": "<FIRST NAME>",  # Required
        "mname": "<MIDDLE NAME>",  # Required
        "lname": "<LAST NAME>",  # Optional
        "address1": "<ADDRESS>",  # Optional
        "city": "<"CITY>",  # Optional
        "state": "<STATE SHORTCODE, EX: NY>",  # Optional
        "zip_code": "<5 DIGIT ZIP CODE>"  # Optional
    }
}

Example response:

{
    "data": {
        "request_id": "<YOUR_REQUEST_ID_TO_GET_RESULTS>"
    },
    "status": "ok",
    "message": "You have 129 credits remaining"
}

Now wait for a half a minute and get results:

POST https://api.klauslookup.shop:5300/api/results

Example request:

{
    "api_key": "<YOUR_API_KEY_HERE>",
    "request_id": "<YOUR_REQUEST_ID_TO_GET_RESULTS>"
}

Example response:

{
  "data": [
    {
      "name": "Aladin Pikachu",
      "DOB": "07/22/1987", 
      "SSN": "623-88-9929",
      "addresses": [
        {
          "address_city": "305 n chandler ave  monterey park",
          "state": "ca",
          "zip_code": "91754"
        },
        {
          "address_city": "615 n baltimore ave  monterey park",
          "state": "ca",
          "zip_code": "91754"
        }
      ]
    }
  ]
}

#### Reveal SSN API endpoint

POST https://api.klauslookup.shop:5300/api/search/ssn/reveal_request

Request data:
`request_id` - the request ID you got to retrieve SSN request results
`masked_ssn` - SSN value to unmask. Must be exactly matching one from SSN search results

{
    "api_key": "<YOUR_API_KEY>",
    "request_id": "<YOUR_REQUEST_ID_TO_GET_RESULTS",
    "masked_ssn": "111-22-XXXX"
}

Example response:

{
    "data": {
        "request_id": 5505
    },
    "status": "ok",
    "message": "You have 128 credits remaining"
}

Now to get revealed SSN, take request_id from response above, and make a request to:

POST https://api.klauslookup.shop:5300/api/search/ssn/reveal_request

Example request:

{
    "api_key": "<YOUR_API_KEY>",
    "request_id": "5505"
}

Example response:

{
    "data": "111-22-4283",
    "status": "ok",
    "message": "You have 127 credits remaining"
}