Lead Creation API

Overview

The Lead Creation endpoint allows external systems to create new leads in the Hitch platform. This endpoint creates a quote, establishes a user account, and returns a magic login URL for immediate user access.

Endpoint: POST /api/{partner}/lead/create

Authentication Token: Provided by Hitch for each partner integration

Source System: Partner-specific

Quick Reference

Item	Value
HTTP Method	`POST`
Content-Type	`application/json`
Authentication	Bearer Token
Success Response	`200 OK`

Sections

Authentication - How to authenticate requests
Request Format - Payload schema and validation rules
Response Format - Success and error response structures
Examples - Valid request/response examples
Error Handling - Invalid use cases and error responses

Implementation Notes

Duplicate Detection: The endpoint checks for both existing quotes and existing users with the same email address. If either exists, the request will fail with a 400 error.
User Creation: The endpoint automatically creates a user account after successfully creating the quote.
Quote Status: Created quotes are automatically set to prequalCredit status.
Referral Source: All leads are tagged with the partner identifier as the referral source.
Login URL: The returned loginUrl is a magic link that allows immediate passwordless authentication. It redirects users to /prequal/credit-check after login.
Idempotency: This endpoint is NOT idempotent. Duplicate requests with the same email will be rejected.