# TradeEngage OpenAPI

Welcome to the TradeEngage OpenAPI documentation. This API enables third-party systems to integrate with TradeEngage for automated job creation and management.

## Overview

The TradeEngage OpenAPI provides a secure, programmatic interface for external systems such as call centers, CRM platforms, and field service management tools to create and track jobs within TradeEngage. Jobs created through this API automatically flow through the TradeEngage referral network, connecting homeowners with qualified service providers.

## Use Cases

- **Call Center Integration**: Automatically create jobs from call transcripts when a homeowner contacts your call center
- **CRM Integration**: Sync leads from your CRM system directly into TradeEngage
- **Field Service Management**: Connect platforms like ServiceTitan to create referral jobs for services outside your expertise


## Authentication

All API requests require authentication using an API key provided in the `X-TradeEngage-Signature` header.


```bash
curl -X POST https://api.tradeengage.com/api/v1/open/jobs \
  -H "Content-Type: application/json" \
  -H "X-TradeEngage-Signature: te_open_your_api_key_here" \
  -d '{ ... }'
```

### Obtaining an API Key

API keys are provided by your TradeEngage administrator.

## Base URL

| Environment | Base URL |
|  --- | --- |
| Production | `https://api.tradeengage.com/api/v1/open` |
| Staging | `https://api.staging.tradeengage.com/api/v1/open` |


## Idempotency

The API supports idempotent requests using the `idempotency_key` field. When provided:

- If a request with the same `idempotency_key` and endpoint has already been processed, the original response is returned
- This prevents duplicate job creation from retry logic or network issues
- Idempotency keys should be unique UUIDs generated by the client



```json
{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "homeowner": { ... }
}
```

## Rate Limiting

API requests are rate-limited to ensure system stability. Current limits:

- **100 requests per minute** per API key
- **1,000 requests per hour** per API key


Exceeding these limits will result in a `429 Too Many Requests` response.

## Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:


```json
{
  "detail": "Error message describing what went wrong"
}
```

### Common Status Codes

| Code | Description |
|  --- | --- |
| `200` | Success |
| `201` | Created successfully |
| `400` | Bad request - validation error |
| `401` | Unauthorized - invalid or missing API key |
| `403` | Forbidden - API key doesn't have access to the requested company |
| `404` | Not found |
| `422` | Unprocessable entity - business rule violation |
| `429` | Too many requests - rate limit exceeded |
| `500` | Internal server error |


## Support

For technical support or to report issues with the API:

- Email: support@tradeengage.com


## Changelog

### 2026-01-24

- Initial public release of OpenAPI documentation
- Endpoints: Create Job