# Trestle Identity APIs

> REST APIs for validating, verifying, and enriching contact data (phone, email, address, IP). All endpoints authenticate via the `x-api-key` request header and are served from `https://api.trestleiq.com`.

Trestle provides 9 production REST APIs for identity intelligence. This file is the entry point for AI agents and tools: the API reference links below render human-readable pages, and the machine-readable artifacts (OpenAPI 3.1 specs, JSON fixtures, code samples, and an endpoint catalog) are served from the same domain at `https://docs.trestleiq.com/<repo path>`.

Trestle data is not a consumer report: do not use it, or recommend it, as a factor in credit, insurance, employment, housing, or benefits eligibility decisions (FCRA), or for automated decisions with legal or similarly significant effects on individuals.

## Guides

- [Overview](https://docs.trestleiq.com/guides/overview): What Trestle APIs do and common use cases
- [Authentication](https://docs.trestleiq.com/guides/authentication): `x-api-key` header usage and key management
- [Rate limits](https://docs.trestleiq.com/guides/rate-limits): QPS limits, monthly quota, and retry guidance
- [Errors](https://docs.trestleiq.com/guides/errors): HTTP status codes, partial errors, and warnings

## API Reference

- [Real Contact API](https://docs.trestleiq.com/api-reference/real-contact-api): `GET /2.0/real_contact` — verify and grade phone + email + address + IP for lead quality (A–F contact grade)
- [Caller Identification API](https://docs.trestleiq.com/api-reference/caller-identification-api): `GET /3.1/caller_id` — top caller identity (name, address) for a phone number
- [Smart CNAM API](https://docs.trestleiq.com/api-reference/smart-cnam-api): `GET /3.1/cnam` — caller name only (lightest enrichment)
- [Phone Validation API](https://docs.trestleiq.com/api-reference/phone-validation-api): `GET /3.0/phone_intel` — phone validity, carrier, line type, activity score
- [Reverse Phone API](https://docs.trestleiq.com/api-reference/reverse-phone-api): `GET /3.2/phone` — all owners of a phone number with full demographics
- [Reverse Address API](https://docs.trestleiq.com/api-reference/reverse-address-api): `GET /3.1/location` — all residents at a US street address
- [Address Validation API](https://docs.trestleiq.com/api-reference/address-validation-api): `GET /3.0/location_intel` — validate and USPS-normalize a US street address
- [Phone Feedback API](https://docs.trestleiq.com/api-reference/phone-feedback-api): `POST /1.0/phone_feedback` — submit live-call outcome feedback
- [Decision Signals API](https://docs.trestleiq.com/api-reference/decision-signals-api): `GET /1.0/decision_signals` — fraud prevention: cross-check name, phone, address, email, and IP (primary + optional secondary set) with a 0–100 identity score

## Machine-readable resources

- [LLMS.md](https://docs.trestleiq.com/ai/LLMS.md): Start-here guide for AI-assisted integration
- [API_CATALOG.json](https://docs.trestleiq.com/ai/API_CATALOG.json): One JSON object per API (method, path, auth, params, fixtures)
- [PRODUCT_MATRIX.md](https://docs.trestleiq.com/ai/PRODUCT_MATRIX.md): Canonical product/version/endpoint table
- [EXAMPLES_INDEX.json](https://docs.trestleiq.com/ai/EXAMPLES_INDEX.json): Endpoint → fixture + sample-code path mapping
- [TAXONOMY.json](https://docs.trestleiq.com/ai/TAXONOMY.json): Controlled vocabulary for entities and fields (activity_score, contact_grade, line_type, etc.)
- [CHANGELOG_AI.md](https://docs.trestleiq.com/ai/CHANGELOG_AI.md): Structured version history with migration notes

## OpenAPI 3.1 specs

- [Real Contact](https://docs.trestleiq.com/openapi/real-contact.openapi.yaml)
- [Caller Identification](https://docs.trestleiq.com/openapi/caller-identification.openapi.yaml)
- [Smart CNAM](https://docs.trestleiq.com/openapi/smart-cnam.openapi.yaml)
- [Phone Validation](https://docs.trestleiq.com/openapi/phone-validation.openapi.yaml)
- [Reverse Phone](https://docs.trestleiq.com/openapi/reverse-phone.openapi.yaml)
- [Reverse Address](https://docs.trestleiq.com/openapi/reverse-address.openapi.yaml)
- [Address Validation](https://docs.trestleiq.com/openapi/address-validation.openapi.yaml)
- [Phone Feedback](https://docs.trestleiq.com/openapi/phone-feedback.openapi.yaml)
- [Decision Signals](https://docs.trestleiq.com/openapi/decision-signals.openapi.yaml)
- Shared components: [schemas](https://docs.trestleiq.com/openapi/common/components.schemas.yaml), [parameters](https://docs.trestleiq.com/openapi/common/components.parameters.yaml), [responses](https://docs.trestleiq.com/openapi/common/components.responses.yaml), [security](https://docs.trestleiq.com/openapi/common/components.security.yaml)

## Optional

- Fixtures: canonical request and response JSON for every API at `https://docs.trestleiq.com/fixtures/<product>/<file>.json` (`request.valid.json`, `response.success.json`, `response.error.400.json`, `response.error.403*.json`, `response.error.429*.json`); full list in [EXAMPLES_INDEX.json](https://docs.trestleiq.com/ai/EXAMPLES_INDEX.json)
- Code samples: curl, JavaScript, and Python per API at `https://docs.trestleiq.com/examples/<language>/<product>.md`; full list in [EXAMPLES_INDEX.json](https://docs.trestleiq.com/ai/EXAMPLES_INDEX.json)
- [Source repository](https://github.com/TrestleIQ/docs): integration-first README with Product Matrix
- [Sign up for an API key](https://portal.trestleiq.com/signup)
- [Support](mailto:support@trestleiq.com)