# Types The fields of every response and event type, and the enumerations they use. ## Lookup types Model and event classes are `final readonly` classes with public promoted properties, built only by the SDK in normal use. Property names are the camelCase form of the API's field names except where noted. Every timestamp is a `DateTimeImmutable` in UTC. ### IpInfo The result of an IP lookup. See the [IP API](https://docs.synthient.com/ipapi) for how each field is derived. - `ip` `string` — The address that was looked up, in canonical form. - `network` `?Network` — The network the address belongs to, or `null` if the API has no network data. - `location` `?Location` — Where the address is located, or `null` if the API has no location data. - `intelligence` `?Intelligence` — What Synthient has observed about the address, or `null` if the API has no intelligence data. ### Network The network an address belongs to. - `asn` `int` — The autonomous system number, or `0` if the address is not routed. - `isp` `string` — The internet service provider that operates the network. - `type` `string` — The kind of network, such as `NetworkType::RESIDENTIAL`. See [Enumerations](#enumerations). - `org` `?string` — The organization the address is registered to, or `null` if unknown. - `domain` `?string` — The network operator's domain, or `null` if unknown. - `abuseEmail` `?string` — The operator's abuse contact email, or `null` if unknown. - `abusePhone` `?string` — The operator's abuse contact phone number, or `null` if unknown. ### Location Where an address is located. - `country` `string` — The ISO 3166-1 alpha-2 country code. - `state` `string` — The state or region. - `city` `string` — The city. - `timezone` `string` — The IANA time zone name. - `latitude` `float` — The latitude in degrees. - `longitude` `float` — The longitude in degrees. - `geoHash` `string` — The geohash of the coordinates. ### Intelligence What Synthient has observed about an address. See [Methodology](https://docs.synthient.com/methodology) for how it is built. - `riskScore` `int` — The risk of the address, from 0 (no risk) to 100. - `categories` `list` — The kinds of services seen on the address, such as `"RESIDENTIAL_PROXY"`. The API may add values. - `behavior` `list` — Behaviors observed from the address. - `providers` `list` — The proxy and VPN providers seen using the address. - `devices` `list` — The devices seen behind the address. ### Provider A proxy or VPN provider seen using an address. - `name` `string` — The provider's service tag. The API names this field `provider`. See [Service Tags](https://docs.synthient.com/service-tags). - `type` `string` — The service category. - `lastSeen` `DateTimeImmutable` — When the provider was last seen on the address. ### Device A device seen behind an address. - `os` `string` — The operating system, such as `OperatingSystem::ANDROID`. See [Enumerations](#enumerations). - `version` `string` — The operating system version. - `lastSeen` `DateTimeImmutable` — When the device was last seen. ## Domain types ### DomainInfo The result of a domain lookup, covering the last 30 days. A domain that was never observed is inactive with zeroed stats. - `domain` `string` — The domain that was looked up. - `status` `string` — `DomainStatus::ACTIVE` when the domain had events in the last 24 hours, otherwise `DomainStatus::INACTIVE`. - `stats` `DomainStats` — Aggregate event counts. - `uniqueIps` `UniqueIps` — Counts of the distinct source addresses. - `timeSeries` `list` — Daily event counts. - `topSubdomains` `list` — The most targeted subdomains. - `topPorts` `list` — The most targeted ports. - `geoDistribution` `list` — Event counts by source country. - `hourDowHeatmap` `list>` — Event counts as 7 rows of 24 hours, Monday first, in UTC, indexed as `$hourDowHeatmap[$day][$hour]`. - `activityStats` `ActivityStats` — The hourly activity pattern. - `recentEvents` `list` — The most recent events, capped by the `limit` argument of `lookupDomain()`. - `topAsn` `?AsnCount` — The network that sent the most events, or `null` when the domain has no events. ### DomainStats Event counts for a domain. - `events24h` `int` — Events in the last 24 hours. - `totalEvents30d` `int` — Events in the last 30 days. ### UniqueIps Distinct source addresses seen for a domain. - `value24h` `int` — Distinct source addresses in the last 24 hours. - `value30d` `int` — Distinct source addresses in the last 30 days. - `sparkline24h` `list` — Hourly counts over the last 24 hours. ### TimeSeriesPoint One day of a domain's activity. - `date` `DateTimeImmutable` — The start of the day, in UTC. - `events` `int` — Events that day. - `uniqueIps` `int` — The number of distinct source addresses that day. ### AsnCount Events from one autonomous system. - `asn` `int` — The autonomous system number. - `events` `int` — Events from that network. ### SubdomainCount Events for one subdomain. - `subdomain` `string` — The subdomain. - `count` `int` — The number of events that targeted it. ### PortCount Events on one port. - `port` `int` — The port. - `count` `int` — The number of events that targeted it. ### CountryCount Activity from one country. - `countryCode` `string` — The source country code. - `events` `int` — Events from that country. - `uniqueIps` `int` — Distinct source addresses from that country. ### ActivityStats Patterns in a domain's hourly activity, in UTC. - `cadence` `string` — A sentence describing the pattern over the last 30 days. See [Enumerations](#enumerations). - `medianPerHour` `int` — The median number of events per hour. - `p95PerHour` `int` — The 95th percentile of events per hour. - `peakHour` `int` — The busiest hour, 0 to 23. - `quietHour` `int` — The quietest hour, 0 to 23. ### DomainEvent A recent event for a domain. - `timestamp` `DateTimeImmutable` — When the event happened. - `sourceIp` `string` — The proxy exit address that carried the event. The API names the field `source_ip_masked`, but the address is not masked. - `targetSubdomain` `string` — The subdomain that was targeted. - `port` `int` — The destination port. - `countryCode` `string` — The source country. ## Account types ### Account The account that owns the API key, from `Client::account()`. - `email` `string` — The account's email address. - `firstName` `string` — The account holder's first name. - `lastName` `string` — The account holder's last name. - `organization` `Organization` — The organization the account belongs to. - `scopes` `list` — The permissions granted to the key. See `Scope` under [Enumerations](#enumerations). - `lookupQuota` `LookupQuota` — The team's remaining lookup credits. - `apiKey` `?AccountApiKey` — The key that made the request, or `null` if the API omits it. ### Organization The organization an account belongs to. - `id` `string` — The organization's ID. - `name` `string` — The organization's name. - `relation` `string` — The account's role in the organization. See [Enumerations](#enumerations). ### LookupQuota The team's remaining lookup credits. - `credits` `int` — The number of lookup credits remaining. - `resetsIn` `int` — Seconds until the credits reset. ### AccountApiKey The API key that made a request. It never includes the secret. - `id` `string` — Identifies the key. - `name` `string` — The key's display name. - `createdAt` `DateTimeImmutable` — When the key was created. ## Export types ### ExportPage One page of a feed's exports, newest first. - `stream` `string` — The feed's stream identifier. - `exports` `list` — The exports on this page. The API names this field `feeds`. - `nextCursor` `?string` — The cursor for the next page, passed as the `cursor` argument of `listExports()`. It is `null` or empty on the last page. ### Export A Parquet snapshot of a feed. - `id` `string` — Identifies the export for `exportMeta()`, `downloadUrl()`, and `download()`. On the first page, `latest` means the newest hourly export. - `kind` `string` — `ExportKind::HOURLY` or `ExportKind::DAILY`. - `date` `string` — The snapshot date as `YYYY-MM-DD`, in UTC. - `sizeBytes` `int` — The size of the Parquet file in bytes. - `rowCount` `int` — The number of rows in the file. - `checksum` `string` — The hex-encoded SHA-256 of the file. - `createdAt` `DateTimeImmutable` — When the export was created. - `downloadPath` `string` — The API path of the export's download. - `hour` `?int` — The hour of an hourly export, or `null` for a daily export. ### ExportMeta Details of one export, including its Parquet schema. - `id` `string` — The export ID. - `stream` `string` — The feed's stream identifier. - `kind` `string` — `ExportKind::HOURLY` or `ExportKind::DAILY`. - `format` `string` — Always `"parquet"`. - `date` `DateTimeImmutable` — The start of the day or hour the export covers. - `rows` `int` — The number of rows in the file. - `size` `int` — The size of the Parquet file in bytes. - `checksum` `string` — The hex-encoded SHA-256 of the file. - `createdAt` `DateTimeImmutable` — When the export was created. - `schema` `ParquetSchema` — The Parquet columns. - `hour` `?int` — The hour of an hourly export, or `null` for a daily export. ### ParquetSchema The columns of a Parquet export. - `fields` `list` — The columns. ### ParquetColumn A column of a Parquet export. - `name` `string` — The column name. - `type` `string` — The column type. See [Enumerations](#enumerations). ## Event types Stream events are decoded into the classes below. - **Units:** Timestamps are `DateTimeImmutable` in UTC whatever unit the feed sends: integers of `1e12` or more are read as milliseconds, and smaller ones as seconds. - **Missing fields:** On the proxies, anonymizers, torrents, and JA4T feeds every property is nullable and is `null` when the API omits it. Helios events require their core properties, so an event missing one throws `SynthientException` and ends the stream. ### ProxyEvent A proxy sighting from the `proxies` feed. - `ip` `?string` — The proxy exit address. - `provider` `?string` — The proxy service tag. - `type` `?string` — The service category. See [Enumerations](#enumerations). - `countryCode` `?string` — The ISO 3166-1 alpha-2 country of the address. - `asn` `?int` — The autonomous system number of the address. - `timestamp` `?DateTimeImmutable` — When the proxy was seen. ### AnonymizerEvent A VPN or anonymizer IP range from the `anonymizers` feed. - `rangeStart` `?string` — The first address of the range. - `rangeEnd` `?string` — The last address of the range. - `provider` `?string` — The service tag. - `type` `?string` — The service category, such as `ProxyType::COMMERCIAL_VPN`. - `countryCode` `?string` — The ISO 3166-1 alpha-2 country of `rangeStart`. - `asn` `?int` — The autonomous system number of `rangeStart`. - `timestamp` `?DateTimeImmutable` — When the range was seen. ### TorrentEvent A torrent from the `torrents` feed. - `infoHash` `?string` — The hex-encoded SHA-1 info hash. - `name` `?string` — The torrent's name. - `magnetUri` `?string` — The torrent's magnet link. - `totalSize` `?int` — The total size of the torrent's files in bytes. - `pieceLength` `?int` — The piece size in bytes. - `fileCount` `?int` — The number of files in the torrent. - `files` `list|null` — The files in the torrent. - `peers` `list|null` — The peers seen sharing the torrent. - `timestamp` `?DateTimeImmutable` — When the torrent was seen. ### TorrentFile A file in a torrent. - `path` `?string` — The file path within the torrent. - `length` `?int` — The file size in bytes. ### TorrentPeer A peer sharing a torrent. - `ip` `?string` — The peer's address. - `port` `?int` — The peer's port. - `source` `?string` — Where the peer was found: `"DHT"`, `"PEX"`, or `"tracker"`. - `encrypted` `?bool` — Whether the peer supports encrypted connections. ### Ja4tEvent A JA4T TCP fingerprint sighting from the `ja4t` feed. - `ip` `?string` — The address the fingerprint was seen from. - `ja4t` `?string` — The JA4T fingerprint. - `provider` `?string` — The service tag of the address. - `type` `?string` — The service category, such as `ProxyType::DATACENTER_PROXY`. - `countryCode` `?string` — The ISO 3166-1 alpha-2 country of the address. - `asn` `?int` — The autonomous system number of the address. - `timestamp` `?DateTimeImmutable` — When the fingerprint was seen. ### HeliosMeta Where a Helios honeypot capture came from. - `proxyIp` `?string` — The proxy address the traffic arrived from. - `server` `?string` — The sensor that captured the traffic. - `poolId` `?string` — The sensor pool. - `provider` `?string` — The proxy service the traffic arrived through. ### HeliosHttpEvent An HTTP request captured by a Helios honeypot. - `timestamp` `DateTimeImmutable` — When the request was captured. - `tunnelId` `string` — Identifies the proxy tunnel the request arrived through. It is a `uint64` as a decimal string, because it can exceed `PHP_INT_MAX`. - `domain` `string` — The host the tunnel was opened to. - `port` `int` — The destination port. - `protocol` `string` — Always `"http"`. - `meta` `HeliosMeta` — The capturing sensor. - `details` `?HttpRequestDetails` — The parsed request, or `null` if the API omits it. - `raw` `?string` — The raw request, still base64-encoded. Decode it with `base64_decode()`. ### HttpRequestDetails The parsed request line and headers of a captured HTTP request. - `method` `?string` — The request method. - `uri` `?string` — The request target. - `version` `?string` — The HTTP version, such as `"HTTP/1.1"`. - `headers` `array|null` — The request headers by name. PHP stores a numeric name such as `"123"` as an `int` key. ### HeliosHttpsEvent A TLS handshake captured by a Helios honeypot. - `timestamp` `DateTimeImmutable` — When the handshake was captured. - `tunnelId` `string` — Identifies the proxy tunnel the handshake arrived through. It is a `uint64` as a decimal string, because it can exceed `PHP_INT_MAX`. - `domain` `string` — The host the tunnel was opened to. - `port` `int` — The destination port. - `protocol` `string` — Always `"https"`. - `meta` `HeliosMeta` — The capturing sensor. - `details` `?TlsClientHello` — The parsed ClientHello, or `null` when the sensor could not parse the handshake. - `raw` `?string` — Always `null`, because the sensors do not capture handshake bytes. ### TlsClientHello A parsed TLS ClientHello. Fields the sensor could not parse are `null`. - `recordVersion` `?string` — The record layer version, such as `"TLS 1.0"`. - `handshakeVersion` `?string` — The ClientHello version, such as `"TLS 1.2"`. - `clientRandom` `?string` — The hex-encoded 32-byte client random. - `sessionId` `?string` — The hex-encoded session ID. - `sessionIdLength` `?int` — The length of the session ID in bytes. - `cipherSuites` `list|null` — The offered cipher suites. - `compressionMethods` `list|null` — The offered compression methods. - `extensions` `list|null` — The extensions in wire order. - `sni` `?string` — The `server_name` extension value. - `alpn` `list|null` — The offered application protocols. - `supportedVersions` `list|null` — The offered TLS versions. - `supportedGroups` `list|null` — The offered key exchange groups. - `signatureAlgorithms` `list|null` — The offered signature algorithms. - `ecPointFormats` `list|null` — The offered elliptic curve point formats. - `keyShareGroups` `list|null` — The groups the client sent key shares for. - `pskKeyExchangeModes` `list|null` — The offered pre-shared key exchange modes. - `compressCertificate` `list|null` — The offered certificate compression algorithms. - `hasGrease` `?bool` — Whether the ClientHello contains GREASE values. - `applicationSettings` `?bool` — Whether the client offered application settings (ALPS). - `delegatedCredentials` `?bool` — Whether the client offered the `delegated_credentials` extension. - `encryptThenMac` `?bool` — Whether the client offered the `encrypt_then_mac` extension. - `extendedMasterSecret` `?bool` — Whether the client offered the `extended_master_secret` extension. - `postHandshakeAuth` `?bool` — Whether the client offered the `post_handshake_auth` extension. - `renegotiationInfo` `?bool` — Whether the client offered the `renegotiation_info` extension. - `signedCertificateTimestamps` `?bool` — Whether the client offered the `signed_certificate_timestamp` extension. - `statusRequest` `?bool` — Whether the client requested OCSP stapling. ### TlsCodeName A TLS code point and its name. GREASE values are named `GREASE(0x....)`. - `code` `?int` — The code point. - `name` `?string` — The code point's registered name. ### TlsExtension A TLS extension in a ClientHello. - `code` `?int` — The extension type. - `name` `?string` — The extension's registered name. - `length` `?int` — The extension body length in bytes. ### HeliosDnsEvent A tunnel destination captured by a Helios honeypot. Despite the feed's name, these are destinations, not DNS queries. - `timestamp` `DateTimeImmutable` — When the event was captured. - `tunnelId` `string` — Identifies the proxy tunnel. It is a `uint64` as a decimal string, because it can exceed `PHP_INT_MAX`. - `domain` `string` — The host the tunnel was opened to. - `port` `int` — The destination port. - `protocol` `string` — Always `"dns"`. - `meta` `HeliosMeta` — The capturing sensor. ### HeliosAdbEvent A shell command captured by a Helios Android Debug Bridge honeypot. It has no timestamp because the sensor sends none. - `session` `string` — Identifies the ADB session as 32 hex characters. - `sequentialId` `int` — The 1-based position of the command within its session. - `command` `string` — The shell command as text. Invalid UTF-8 bytes become U+FFFD. - `hash` `string` — The hex-encoded SHA-256 of the session's payload. It is not a hash of `command`: every command in a session shares it. ## Enumerations Each value set is a `final` class of string constants in `Synthient\Enum`, not a native PHP enum, and the properties that hold these values are typed `string`. Compare them with `===` or `match`. The API may add values to the sets marked open, so handle unknown values instead of assuming a closed `match`. ```php use Synthient\Enum\NetworkType; $info = $client->lookupIp('8.8.8.8'); echo match ($info->network?->type) { NetworkType::RESIDENTIAL, NetworkType::MOBILE => 'consumer', NetworkType::DATACENTER => 'hosting', default => 'other', }, "\n"; ``` ### NetworkType The kind of network an address belongs to. Open. | Constant | Value | | ----------------------------- | ---------------- | | `NetworkType::MOBILE` | `MOBILE` | | `NetworkType::SATELLITE` | `SATELLITE` | | `NetworkType::IN_FLIGHT_WIFI` | `IN_FLIGHT_WIFI` | | `NetworkType::RESIDENTIAL` | `RESIDENTIAL` | | `NetworkType::CORPORATE` | `CORPORATE` | | `NetworkType::ACADEMIC` | `ACADEMIC` | | `NetworkType::DATACENTER` | `DATACENTER` | | `NetworkType::GOVERNMENT` | `GOVERNMENT` | ### ProxyType The kind of proxy, VPN, or automated service behind an address in a feed. Open. | Constant | Value | | ------------------------------ | ------------------- | | `ProxyType::FREE_VPN` | `FREE_VPN` | | `ProxyType::COMMERCIAL_VPN` | `COMMERCIAL_VPN` | | `ProxyType::ENTERPRISE_VPN` | `ENTERPRISE_VPN` | | `ProxyType::MOBILE_PROXY` | `MOBILE_PROXY` | | `ProxyType::BLOCKCHAIN_PROXY` | `BLOCKCHAIN_PROXY` | | `ProxyType::RESIDENTIAL_PROXY` | `RESIDENTIAL_PROXY` | | `ProxyType::PUBLIC_PROXY` | `PUBLIC_PROXY` | | `ProxyType::DATACENTER_PROXY` | `DATACENTER_PROXY` | | `ProxyType::TOR_NODE` | `TOR_NODE` | | `ProxyType::PRIVATE_RELAY` | `PRIVATE_RELAY` | | `ProxyType::BOTNET` | `BOTNET` | | `ProxyType::SEARCH_ENGINE` | `SEARCH_ENGINE` | | `ProxyType::AI_CRAWLER` | `AI_CRAWLER` | | `ProxyType::SOCIAL_MEDIA` | `SOCIAL_MEDIA` | | `ProxyType::UPTIME_MONITOR` | `UPTIME_MONITOR` | | `ProxyType::LINK_PREVIEW` | `LINK_PREVIEW` | | `ProxyType::SEO_CRAWLER` | `SEO_CRAWLER` | | `ProxyType::WEB_ARCHIVER` | `WEB_ARCHIVER` | | `ProxyType::WEBHOOK_PROVIDER` | `WEBHOOK_PROVIDER` | | `ProxyType::PAYMENT_PROCESSOR` | `PAYMENT_PROCESSOR` | | `ProxyType::INTERNET_SCANNER` | `INTERNET_SCANNER` | ### OperatingSystem The operating system of a device seen behind an address. Open. | Constant | Value | | ---------------------------- | ----------- | | `OperatingSystem::ANDROID` | `Android` | | `OperatingSystem::CHROME_OS` | `Chrome OS` | | `OperatingSystem::FREEBSD` | `FreeBSD` | | `OperatingSystem::IOS` | `iOS` | | `OperatingSystem::LINUX` | `Linux` | | `OperatingSystem::MAC_OS_X` | `Mac OS X` | | `OperatingSystem::WINDOWS` | `Windows` | ### Scope A permission granted to an API key. Open. `Scope::BASIC` authorizes lookups and account details. Each feed has one scope for its exports and one for its stream, as listed under [Feeds](https://docs.synthient.com/sdks/php/feeds). See [Authentication](https://docs.synthient.com/authentication) for how scopes are granted. | Constant | Value | | ------------------------------ | ----------------------- | | `Scope::BASIC` | `BASIC` | | `Scope::PROXY_FEEDS` | `PROXY_FEEDS` | | `Scope::PROXY_FIREHOSE` | `PROXY_FIREHOSE` | | `Scope::ANONYMIZERS_FEED` | `ANONYMIZERS_FEED` | | `Scope::ANONYMIZERS_STREAM` | `ANONYMIZERS_STREAM` | | `Scope::JA3_FEED` | `JA3_FEED` | | `Scope::JA3_STREAM` | `JA3_STREAM` | | `Scope::TORRENTS_FEED` | `TORRENTS_FEED` | | `Scope::TORRENTS_STREAM` | `TORRENTS_STREAM` | | `Scope::HONEYPOT_HTTP_FEED` | `HONEYPOT_HTTP_FEED` | | `Scope::HONEYPOT_HTTP_STREAM` | `HONEYPOT_HTTP_STREAM` | | `Scope::HONEYPOT_HTTPS_FEED` | `HONEYPOT_HTTPS_FEED` | | `Scope::HONEYPOT_HTTPS_STREAM` | `HONEYPOT_HTTPS_STREAM` | | `Scope::HONEYPOT_ADB_FEED` | `HONEYPOT_ADB_FEED` | | `Scope::HONEYPOT_ADB_STREAM` | `HONEYPOT_ADB_STREAM` | | `Scope::HONEYPOT_DNS_FEED` | `HONEYPOT_DNS_FEED` | | `Scope::HONEYPOT_DNS_STREAM` | `HONEYPOT_DNS_STREAM` | | `Scope::JA4_FEED` | `JA4_FEED` | | `Scope::JA4_STREAM` | `JA4_STREAM` | | `Scope::JA4T_FEED` | `JA4T_FEED` | | `Scope::JA4T_STREAM` | `JA4T_STREAM` | | `Scope::ADMIN_PROXIES` | `ADMIN_PROXIES` | ### Relation An account's role in its organization. | Constant | Value | | ------------------ | -------- | | `Relation::OWNER` | `OWNER` | | `Relation::ADMIN` | `ADMIN` | | `Relation::MEMBER` | `MEMBER` | ### DomainStatus Whether a domain had events in the last 24 hours. | Constant | Value | Meaning | | ------------------------ | ---------- | -------------------------------------------------------------------------- | | `DomainStatus::ACTIVE` | `active` | The domain had events in the last 24 hours. | | `DomainStatus::INACTIVE` | `inactive` | The domain had no events in the last 24 hours, or has never been observed. | ### Cadence The activity pattern of a domain over the last 30 days, as a sentence. | Constant | Value | | ----------------------------- | ---------------------------------------------------- | | `Cadence::NO_ACTIVITY` | `No activity in the last 30 days.` | | `Cadence::EVENLY_DISTRIBUTED` | `Activity is evenly distributed across the day.` | | `Cadence::BUSINESS_HOURS` | `Activity follows a weekday business-hours pattern.` | | `Cadence::WEEKEND` | `Activity follows a weekend pattern.` | | `Cadence::BURST_DRIVEN` | `Activity is burst-driven with significant peaks.` | ### ExportKind Whether an export covers an hour or a day. | Constant | Value | | -------------------- | -------- | | `ExportKind::HOURLY` | `hourly` | | `ExportKind::DAILY` | `daily` | ### ParquetType The type of a column in a Parquet export. Open. | Constant | Value | | --------------------- | -------- | | `ParquetType::STRING` | `string` | | `ParquetType::INT64` | `int64` | | `ParquetType::UINT32` | `uint32` | | `ParquetType::UINT64` | `uint64` | | `ParquetType::BOOL` | `bool` | | `ParquetType::BYTES` | `bytes` |