# TradeEngage OpenAPI

The TradeEngage OpenAPI enables third-party systems to create and manage jobs
within the TradeEngage referral network.

## Authentication

All requests require an API key in the `X-TradeEngage-Signature` header.
API keys are provisioned by TradeEngage administrators.

## Company Resolution

The company context for each request is determined by:
1. `service_titan_tenant_id` - Links to the company via ServiceTitan integration
2. `brand_location_id` - The company's unique public identifier
3. Default company - Falls back to the API key's configured default


Version: 1.0.0
License: Proprietary

## Servers

Production
```
https://api.tradeengage.com/api/v1/open
```

Staging
```
https://api.staging.tradeengage.com/api/v1/open
```

## Security

### ApiKeyAuth

API key for authentication. Keys are prefixed with `te_open_` and issued
by TradeEngage administrators.

Example: `te_open_abc123def456...`


Type: apiKey
In: header
Name: X-TradeEngage-Signature

## Download OpenAPI description

[TradeEngage OpenAPI](https://tradeengage.redocly.app/_bundle/openapi.yaml)

## Jobs

Job creation and management endpoints

### Create a new job

 - [POST /jobs](https://tradeengage.redocly.app/openapi/jobs/createjob.md): Creates a new job in TradeEngage with the provided homeowner information.
The job is automatically processed through the TradeEngage referral network
to find qualified service providers.

## Idempotency

This endpoint supports idempotent requests. If you provide an idempotency_key
and a request with the same key has already been processed, the original
response will be returned without creating a duplicate job.

## Job Context Requirements

Every job requires context about what service the homeowner needs. This can be
provided in one of two ways:

1. Summary: A text description of the job (e.g., "Water heater replacement needed")
2. Call Transcript: A transcript from a call center interaction

At least one of these must be provided. If neither is available, the request
will be rejected.

## Referring User vs Call Center Agent

Jobs can be attributed to a referring user (the person who referred the job)
or a call center agent (who took the call). If both are provided, the call
center agent takes priority for attribution purposes.