Jump to Content

Standard response

The structure and content of the standard JSON response returned by Validin API enrichment

Standard response example

The following JSON block illustrates a successful request for a domain's A record:

{
  "query_opts": {                   
    "type": "dom",
    "annotate": false
  },
  "query_key": "example.com",       
  "status": "finished",
  "records": {                      
    "A": [                          
      {                               
        "key": "example.com",         
        "value": "93.184.215.14",     
        "value_type": "ip4",          
        "first_seen": 1713463200,     
        "last_seen": 1727719200       
      }
    ]
  },
  "records_returned": 1,            
  "limited": false                  
}

Field definitions

The top level of the JSON response contains metadata about the query status and scope:

Field	Type	Description
`query_opts`	`object`	The inferred or provided options used to execute the search (e.g., `type: "dom"` for domain).
`query_key`	`string`	The input indicator or search key that was used (e.g., `example.com`).
`status`	`string`	The completion status of the query (`finished` or an error state).
`records_returned`	`integer`	The total number of unique records found and returned in the `records` object.
`limited`	`boolean`	Indicates if the result set was restricted due to result limits or resource constraints (`true` if restricted).

The `records` object

The records object contains the actual data payload. It's a hash map where keys represent the type of data returned (e.g., A record, WHOIS record, CERT), and values are arrays of associated data objects.

Each record object within the records array uses a standard structure to detail the observation:

Field	Type	Description
`key`	`string`	The indicator (domain, IP, etc.) that matched the search criteria.
`value`	`string`	The value associated with the key (e.g., the IP address resolved from the domain).
`value_type`	`string`	How the `value` is interpreted (`dom`, `ip4`, `ip6`, `hash`, or `raw`).
`first_seen`	`integer`	Unix timestamp (seconds since epoch) of the earliest observation window for this specific record.
`last_seen`	`integer`	Unix timestamp of the most recent observation window for this specific record.

👍
Tip: Timestamps
The first_seen and last_seen fields are provided in Unix epoch time. You'll need to convert to local time in your application for human readability.

Updated about 1 month ago