Skip to main content

​
Decision Signals 1.0

In a single query, the Decision Signals API returns 70+ data signals and network insights to provide match statuses, validity flags, enriched metadata, and distance calculations between the key identity data inputs of name, email, phone, address, and IP. The Decision Signals API supports one API request with up to two sets of inputs (primary and secondary) for name, phone, address, and email, but only one IP address. You should submit specific parameters based on the amount of data you want to cross-check and validate, and we will populate the API return with components that correspond to the inputs provided.
Note: Authentication is provided via the x-api-key header.

​
Primary and secondary use cases

​
Query Parameters

​
Transaction context

​
string
required
Caller-supplied correlation ID for the transaction. Example: transaction_id=txn_123
​
string
required
UTC timestamp for the transaction, in YYYY-MM-DD HH:MM or ISO 8601 format. Example: transaction_time=2026-06-15T10:00

​
Identity inputs

​
string
required
Full legal name of the primary person. Either primary.name or primary.business_name is required. Example: primary.name=Robin Cooke
​
string
Full legal name of the primary business. Either primary.name or primary.business_name is required. Example: primary.business_name=The Golden Company
​
string
Full legal name of the secondary person. Example: secondary.name=Vicky Kunal
​
string
Full legal name of the secondary business. Example: secondary.business_name=The Silver Company

​
Phone inputs

​
string
Primary phone number. Accepted formats: +12065551234, 12065551234, 2065551234, (206) 555-1234, 206-555-1234. E.164 format is recommended. Example: primary.phone=13606769260
​
string (ISO-3166-2)
The ISO-3166 alpha-2 country code associated with the primary phone. Defaults to US if not provided. Example: primary.phone.country_hint=US
​
string
Secondary phone number. Same accepted formats as the primary phone. Example: secondary.phone=14259851212
​
string (ISO-3166-2)
The ISO-3166 alpha-2 country code associated with the secondary phone. Example: secondary.phone.country_hint=US

​
Address inputs

​
string
The first line of the primary street address. Example: primary.address.street_line_1=12843 NE 91st St
​
string
The second line of the primary street address. Example: primary.address.street_line_2=Apt 4B
​
string
The city name of the primary address. Example: primary.address.city=Bellingham
​
string
The two-letter state or province code of the primary address. Example: primary.address.state_code=WA
​
string
The postal or ZIP code of the primary address. Example: primary.address.postal_code=98033
​
string (ISO-3166-2)
The ISO-3166 alpha-2 country code of the primary address. Example: primary.address.country_code=US
​
string
The first line of the secondary street address. Example: secondary.address.street_line_1=4492 163rd Pl SE
​
string
The second line of the secondary street address. Example: secondary.address.street_line_2=Suite 200
​
string
The city name of the secondary address. Example: secondary.address.city=Bellevue
​
string
The two-letter state or province code of the secondary address. Example: secondary.address.state_code=WA
​
string
The postal or ZIP code of the secondary address. Example: secondary.address.postal_code=98006
​
string (ISO-3166-2)
The ISO-3166 alpha-2 country code of the secondary address. Example: secondary.address.country_code=US

​
Email inputs

​
string
The primary email address. Example: primary.email_address=john.doe@gmail.com
​
string
The secondary email address. Example: secondary.email_address=jane.doe@gmail.com

​
IP input

​
string
The IPv4 or IPv6 address associated with the transaction. Example: ip_address=73.25.97.8

​
Headers

​
string
required
Your API key for authentication. Example: {{ apiKey }}

​
Response

The response contains a block for each input type provided. Blocks are null when the corresponding input was not submitted. Per-check warnings and errors are consolidated into a single warnings / errors list at the root, with each entry prefixed by the component it came from (for example, "Primary Email: Disposable Email").
​
integer
A composite trust score from 0 to 100, where 100 is the safest and 0 is the riskiest. This field is never null. See Identity score for how the score is derived and how to interpret it.
​
null
Reserved for a forthcoming ML-based identity score model. Always returns null today.
​
object or null
Phone check results for the primary phone. Null when no primary phone was submitted.
​
object or null
Phone check results for the secondary phone. Null when no secondary phone was submitted.
​
object or null
Address check results for the primary address. Null when no primary address was submitted.
​
object or null
Address check results for the secondary address. Null when no secondary address was submitted.
Partial address: If an address is submitted without a street line (postal code only, or city and state only), the block is still returned with is_valid, name_match, type, and is_forwarder all set to null. A partial address contributes no weight to identity_score. The block is only null when no address input was submitted at all.
​
object or null
Email check results for the primary email. Null when no primary email was submitted.
​
object or null
Email check results for the secondary email. Null when no secondary email was submitted.
​
object or null
IP check results. Null when no IP address was submitted.
​
string[]
All warnings from every sub-check, plus root-level warnings, aggregated here and prefixed by component. See Warnings reference.
​
string[]
All errors from every sub-check, aggregated here.

​
Identity score

identity_score is a composite score from 0 to 100, derived from the phone, email, address, and IP signals. 100 is the safest and 0 is the riskiest. The score is additive: each valid, matching signal contributes positively and each mismatch or invalid signal contributes negatively from a neutral midpoint of 50. identity_score requires a name input (primary.name or primary.business_name) plus at least one of primary or secondary phone, address, email, or IP address. Providing only a name returns 50, the neutral baseline. For best results, provide as many inputs as possible to maximize signal coverage. A partial address (no street line) contributes no weight to the score.

​
Sandbox

The Decision Signals API supports sandbox mode for integration testing without consuming live enrichment. Add is_sandbox=true to the request. Pre-stored responses are returned across all input fields (phone, name, email, address, and IP), and no live API calls are made. Use the inputs below to receive each canned scenario. Note: The canned response is keyed by the test scenario, so a sandbox response may include blocks (for example, address or IP) even if those inputs were not part of the request.

​
Sandbox 1 — high trust score

​
Sandbox 2 — low trust score

​
Warnings reference

Every warning is aggregated into the root warnings list and prefixed by the component it came from, for example "Primary Email: Disposable Email" or "IP: Proxy detected".

​
Root

​
Phone (primary / secondary)

​
Address (primary / secondary)

​
Email (primary / secondary)

​
IP

​
Error responses

​
Null handling

All response fields may return null. Common reasons:
  • Input not provided: The corresponding input (phone, address, email, or IP) was not submitted.
  • Input invalid: The submitted value could not be validated, for example a fake phone number or a malformed IP.
  • Data unavailable: Trestle’s data sources do not have coverage for this input.
  • Reserved field: Some fields are reserved for future use and always return null.
Treat null categorical fields such as name_match, is_valid, and line_type as a distinct value in your risk model. Do not impute them with a default value.

​
Best practices

​
Input recommendations

  • Name: Submit the full name in primary.name. Do not pass placeholder values such as N/A or NONE; leave the parameter empty instead.
  • Phone: E.164 format is recommended, for example +12065551234. Include phone.country_hint for non-US numbers.
  • Address: Include state_code and postal_code for the best validation results. For a street-level result, submit street_line_1 plus at least one of city, state, or postal code. A submitted address is always echoed back as a block and is never null, so you can see every attribute. Only a completely absent address yields a null block.
  • Email: Submit the full email address. The API checks validity and email owner name matching.
  • IP: Both IPv4 and IPv6 are accepted. Private range IPs such as 10.x.x.x, 192.168.x.x, and 127.0.0.1 return is_valid: false.
  • Timestamp: Time zones must be in UTC. The following formats are valid:
    • YYYY-MM-DD
    • YYYY-MM-DD HH:MM
    • YYYY-MM-DD HH:MM:SS
    • YYYY-MM-DD HH:MM:SS:ss
    • YYYY-MM-DDTHH:MM
    • YYYY-MM-DDTHH:MM:SS
    • YYYY-MM-DDTHH:MM:SS:ss
    • YYYY-MM-DDTHH:MM:SS-00:00 (other negative UTC offsets)
    • YYYY-MM-DDTHH:MMZ
    • YYYY-MM-DDTHH:MM:SSZ
    • YYYY-MM-DDTHH:MM:SS:ssZ
    The following formats are not valid:
    • YYYYMMDDTHHMM
    • YYYYMMDDTHHMMZ
    • MM-DD-YYYY
    • YYYY-MM-DDTHH:MM:SS+0:00 (other positive UTC offsets)

​
Score interpretation

An identity score of 50 may be considered a neutral baseline. Positive signals, such as confirmed name matches and well-established identity elements, increase the score, while negative signals decrease it. The score distribution is broadest and most robust when a full set of identity inputs is provided. Recommended cutoff thresholds will depend on the inputs supplied and the risk profile of your traffic.

​
Rate limits

If you receive a 429 response, the request was not processed. Do not retry immediately. Wait until the rate limit window resets before resending, or contact support@trestleiq.com to update the rate limit available for your API key.