Decision Signals API
Decision Signals API
Decision Signals API returns 70+ data signals and network insights in a single query, providing match statuses, validity flags, enriched metadata, and distance calculations across name, email, phone, address, and IP.
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.Primary and secondary use cases
Query Parameters
Authentication
string
Your Trestle API key, as an alternative to the
x-api-key header. One of the
two is required. The header is recommended. Example: api_key=YOUR_API_KEYTransaction context
string
required
Caller-supplied correlation ID for the transaction. Example:
transaction_id=txn_123string
required
UTC timestamp for the transaction, in
YYYY-MM-DD HH:MM or ISO 8601 format.
Example: transaction_time=2026-06-15T10:00Identity inputs
string
required
Full legal name of the primary person. Either
primary.name or
primary.business_name is required. Example: primary.name=Robin Cookestring
Full legal name of the primary business. Either
primary.name or
primary.business_name is required. Example:
primary.business_name=The Golden Companystring
Full legal name of the secondary person. Example:
secondary.name=Vicky Kunalstring
Full legal name of the secondary business. Example:
secondary.business_name=The Silver CompanyPhone inputs
string
Primary phone number. Accepted formats:
+12065551234, 12065551234,
2065551234, (206) 555-1234, 206-555-1234. E.164 format is recommended.
Example: primary.phone=13606769260string (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=USstring
Secondary phone number. Same accepted formats as the primary phone.
Example:
secondary.phone=14259851212string (ISO-3166-2)
The ISO-3166 alpha-2 country code associated with the secondary phone.
Example:
secondary.phone.country_hint=USAddress inputs
string
The first line of the primary street address. Example:
primary.address.street_line_1=12843 NE 91st Ststring
The second line of the primary street address. Example:
primary.address.street_line_2=Apt 4Bstring
The city name of the primary address. Example:
primary.address.city=Bellinghamstring
The two-letter state or province code of the primary address. Example:
primary.address.state_code=WAstring
The postal or ZIP code of the primary address. Example:
primary.address.postal_code=98033string (ISO-3166-2)
The ISO-3166 alpha-2 country code of the primary address. Example:
primary.address.country_code=USstring
The first line of the secondary street address. Example:
secondary.address.street_line_1=4492 163rd Pl SEstring
The second line of the secondary street address. Example:
secondary.address.street_line_2=Suite 200string
The city name of the secondary address. Example:
secondary.address.city=Bellevuestring
The two-letter state or province code of the secondary address. Example:
secondary.address.state_code=WAstring
The postal or ZIP code of the secondary address. Example:
secondary.address.postal_code=98006string (ISO-3166-2)
The ISO-3166 alpha-2 country code of the secondary address. Example:
secondary.address.country_code=USEmail inputs
string
The primary email address. Example:
primary.email_address=john.doe@gmail.comstring
The secondary email address. Example:
secondary.email_address=jane.doe@gmail.comIP input
string
The IPv4 or IPv6 address associated with the transaction. Example:
ip_address=73.25.97.8Sandbox
boolean
Set to
true to return pre-stored sandbox responses instead of live
enrichment. See Sandbox for the available test scenarios.
Example: is_sandbox=trueHeaders
string
Your API key for authentication. Required unless the key is supplied as an
api_key query parameter. Example: {{ apiKey }}Response
The response contains a block for each input type provided. Blocks arenull 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.
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.
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.
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.
Sandbox
The Decision Signals API supports sandbox mode for integration testing without consuming live enrichment. Addis_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 rootwarnings list and prefixed by the component it came from, for example "Primary Email: Disposable Email" or "IP: Proxy detected".
Root
Missing required input: primary.name (or primary.business_name) is required. Missing required input: transaction_id is required. Missing required input: transaction_time is required. Invalid Input Missing InputPhone (primary / secondary)
Invalid PhoneAddress (primary / secondary)
Invalid Address Partial Address Missing unit/apt/suite number Invalid unit/apt/suite number Invalid house/building number Freight Forwarder Partial Error-Could not retrieve entire responseEmail (primary / secondary)
Invalid Email Disposable Email Role Based Email Potential Junk Email Tumbled Email Privacy Email Email is a spam trap Email is a known abuse email address TimeoutError: Timeout getting response for email age score InternalError: Error retrieving the email age score responseIP
Input IP address is invalid. Please provide a valid IPv4 or IPv6 address Proxy detected Timeout getting response for IP information. Partial response returned.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.
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 asN/AorNONE; leave the parameter empty instead. - Phone: E.164 format is recommended, for example
+12065551234. Includephone.country_hintfor non-US numbers. - Address: Include
state_codeandpostal_codefor the best validation results. For a street-level result, submitstreet_line_1plus 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, and127.0.0.1returnis_valid: false.
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.Error Responses
400 Bad Request
The server cannot process the request due to client-side errors.Check for: Syntax errors in the request script, malformed JSON, or invalid parameters.403 Forbidden
The request is understood, but the server is refusing to fulfill it. Error responses include anerrorCode field identifying the cause:-
Invalid API Key (
INVALID_API_KEY): The key is incorrect, deactivated, or missing from the request. Check for: Trailing spaces, syntax errors, incorrect character counts, or a missingx-api-keyheader. -
API Key Disabled (Portal Issue) (
FORBIDDEN): The key is inactive. Check for: Insufficient funds in your self-serve wallet or if a Trestle Admin manually deactivated your API key. -
API Key does not have Product Access (Portal Issue) (
FORBIDDEN): The API key is active, but it is not enabled for this product or API version. Check for: Incorrect endpoint, incorrect API version, or missing product access on the key. -
API Key Expired (
FORBIDDEN): The key has reached its end-of-life (primarily affects Trial users).
429 Too Many Requests
You have sent too many requests in a given amount of time.-
Rate Limit Exceeded (
RATE_LIMIT_EXCEEDED): You have surpassed the queries-per-second (QPS) threshold for your tier. -
Quota Exceeded (Portal Issue) (
QUOTA_EXCEEDED): You have reached the total volume allowed for your current billing cycle. Upgrade your plan in the portal to resume service.
