---
# System prepended metadata

title: Klaus Lookup Service API

---

# 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:
```json
{
    "api_key": "<YOUR_API_KEY>"
}
```


Example response:

```json
{
    "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
```json
{
    "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:
```json
{
    "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:
```json
{
    "api_key": "<YOUR_API_KEY_HERE>",
    "request_id": "<YOUR_REQUEST_ID_TO_GET_RESULTS>"
}

```

Example response:
```json
{
  "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

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

Example response:
```json
{
    "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:
```json
{
    "api_key": "<YOUR_API_KEY>",
    "request_id": "5505"
}
```

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