Skip to content
Jobs/
Create a new job

TradeEngage OpenAPI (1.0.0)

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
Download OpenAPI description
openapi.json
openapi.yaml
Overview
TradeEngage API Support
api-support@tradeengage.com
License
Proprietary
Languages
Servers
Mock server
https://docs.api.tradeengage.com/_mock/openapi
Production
https://api.tradeengage.com/api/v1/open
Staging
https://api.staging.tradeengage.com/api/v1/open

Jobs

Job creation and management endpoints

Operations

Create a new job

Request

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.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
homeownerobject(Homeowner)required
homeowner.​first_namestringrequired

Homeowner's first name

Example: "John"
homeowner.​last_namestringrequired

Homeowner's last name

Example: "Doe"
homeowner.​phonestringrequired

Homeowner's phone number. Must be a valid US phone number. Will be normalized to international format (+1XXXXXXXXXX).

Example: "5551234567"
homeowner.​emailstring or null(email)

Homeowner's email address (optional but recommended)

Example: "john.doe@example.com"
homeowner.​zip_codestring^\d{5}$required

5-digit US zip code for the service location

Example: "90210"
homeowner.​streetstring or null

Street address

Example: "123 Main Street"
homeowner.​citystring or null

City name

Example: "Beverly Hills"
homeowner.​statestring or null

State abbreviation or full name

Example: "CA"
call_centerobject(CallCenter)

Call center information including the agent who handled the call and details about the call itself.

If agent is provided, they will be credited as the referring user for this job (taking precedence over referring_user).

referring_userobject(ReferringUser)

The person who referred this job. This could be an employee, partner, or other contact who sourced the lead.

Note: If call_center.agent is also provided, the agent takes precedence for attribution purposes.

If the referring user doesn't exist in TradeEngage, they will be invited to create an account.

summarystring

A text description of the job or service needed. This is used to identify the job sector (HVAC, Plumbing, Electrical, etc.) and match with appropriate service providers.

Required if call_center.call.transcript is not provided.

Example: "Customer needs AC repair - unit not cooling, making strange noise"
service_titan_tenant_idstring

ServiceTitan tenant ID to identify the company creating this job. Used for companies integrated with ServiceTitan.

Takes precedence over brand_location_id if both are provided.

Example: "st_tenant_12345"
brand_location_idstring

Unique public identifier for the company/location creating this job. Used when service_titan_tenant_id is not available.

Example: "hvac-company-dallas-001"
idempotency_keystring

Unique identifier for this request to enable idempotent operations. If a request with the same key has already been processed, the original response will be returned.

Recommended format: UUID v4

Example: "550e8400-e29b-41d4-a716-446655440000"
external_identifiersobject

Key-value pairs for storing external system identifiers. Useful for correlating jobs with records in your own systems.

Example: {"service_titan_job_id":"ST-12345","crm_lead_id":"LEAD-67890","call_id":"CALL-11111"}
sourcestring

Identifier for the source system creating this job. Used for tracking and analytics.

Example: "CUSTOM_SOURCE"
curl -i -X POST \
  https://docs.api.tradeengage.com/_mock/openapi/jobs \
  -H 'Content-Type: application/json' \
  -H 'X-TradeEngage-Signature: YOUR_API_KEY_HERE' \
  -d '{
    "homeowner": {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "5551234567",
      "email": "john.doe@example.com",
      "zip_code": "90210"
    },
    "summary": "Customer needs HVAC repair - AC not cooling properly"
  }'

Responses

Job created successfully

Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "public_id": "JOB-a1b2c3d4e5",
    "status": "HOMEOWNER_ACCEPTED",
    "source": "CUSTOM_SOURCE"
  }
}