# Create a new job

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.

Endpoint: POST /jobs
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `homeowner` (object, required)

  - `homeowner.first_name` (string, required)
    Homeowner's first name
    Example: "John"

  - `homeowner.last_name` (string, required)
    Homeowner's last name
    Example: "Doe"

  - `homeowner.phone` (string, required)
    Homeowner's phone number. Must be a valid US phone number.
Will be normalized to international format (+1XXXXXXXXXX).
    Example: "5551234567"

  - `homeowner.email` (string,null)
    Homeowner's email address (optional but recommended)
    Example: "john.doe@example.com"

  - `homeowner.zip_code` (string, required)
    5-digit US zip code for the service location
    Example: "90210"

  - `homeowner.street` (string,null)
    Street address
    Example: "123 Main Street"

  - `homeowner.city` (string,null)
    City name
    Example: "Beverly Hills"

  - `homeowner.state` (string,null)
    State abbreviation or full name
    Example: "CA"

  - `call_center` (object)
    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).

  - `call_center.agent` (object)

  - `call_center.agent.first_name` (string, required)
    Agent's first name
    Example: "Sarah"

  - `call_center.agent.last_name` (string, required)
    Agent's last name
    Example: "Smith"

  - `call_center.agent.email` (string,null)
    Agent's email address
    Example: "sarah.smith@callcenter.com"

  - `call_center.agent.phone` (string, required)
    Agent's phone number (must be valid US number)
    Example: "5559876543"

  - `call_center.call` (object)

  - `call_center.call.transcript` (string, required)
    Full transcript of the call. Used to identify the job sector
and understand the customer's needs.

This can substitute for summary as the job context.
    Example: "Customer called about their AC unit not cooling. Unit is 15 years old, located in the attic. Making a loud noise when running."

  - `referring_user` (object)
    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.

  - `referring_user.first_name` (string, required)
    Referring user's first name
    Example: "Mike"

  - `referring_user.last_name` (string, required)
    Referring user's last name
    Example: "Johnson"

  - `referring_user.email` (string,null)
    Referring user's email address
    Example: "mike.johnson@company.com"

  - `referring_user.phone` (string, required)
    Referring user's phone number (must be valid US number)
    Example: "5551112222"

  - `summary` (string)
    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_id` (string)
    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_id` (string)
    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_key` (string)
    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_identifiers` (object)
    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"}

  - `source` (string)
    Identifier for the source system creating this job.
Used for tracking and analytics.
    Example: "CUSTOM_SOURCE"

## Response 201 fields (application/json):

  - `data` (object)

  - `data.public_id` (string)
    Unique public identifier for the created job.
Use this ID to query job status via the GET endpoint.
    Example: "JOB-a1b2c3d4e5"

  - `data.status` (string)
    Current status of the job. Newly created jobs typically
have status HOMEOWNER_ACCEPTED.
    Example: "HOMEOWNER_ACCEPTED"

  - `data.source` (string,null)
    The source identifier provided in the request
    Example: "CUSTOM_SOURCE"

## Response 400 fields (application/json):

  - `detail` (any)
    Validation error details

## Response 401 fields (application/json):

  - `detail` (string)
    Human-readable error message
    Example: "Invalid API key"

## Response 403 fields (application/json):

  - `detail` (string)
    Human-readable error message
    Example: "Invalid API key"

## Response 404 fields (application/json):

  - `detail` (string)
    Human-readable error message
    Example: "Invalid API key"