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 can be provided either as an x-api-key header or as an api_key query parameter. One of the two is required. The header is recommended, since query strings are recorded in server access logs and browser history.

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_KEY

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

Sandbox

boolean
Set to true to return pre-stored sandbox responses instead of live enrichment. See Sandbox for the available test scenarios. Example: is_sandbox=true

Headers

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 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.
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. 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. 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

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 Input

Phone (primary / secondary)

Invalid Phone

Address (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 response

Email (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 response

IP

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.
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.

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 an errorCode 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 missing x-api-key header.
  • 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.

500 Internal Server Error

An unexpected error occurred on the server side. Please contact support if this persists.See Error handling for all error response bodies and codes.