Skip to main content

API Documentation

Capture leads from your website forms directly into TradeSender using our REST API.

https://app.tradesender.co.uk/api/v1

Authentication

All API requests require an API key passed in the X-API-Key header. You can create and manage API keys from your TradeSender dashboard.

curl -H "X-API-Key: ts_live_abc123..." \
  https://app.tradesender.co.uk/api/v1/leads
Keep your API key secret

Never expose your API key in client-side JavaScript. Always make API calls from your server or serverless functions.

Create Lead

POST
/api/v1/leads

Creates a new lead in your TradeSender account. The request body is a discriminated union based on the type field. Choose the type that matches your form:

Request Body

NameTypeRequiredDescription
typestringMust be "quote_request"
namestringFull name of the requester (max 255)
emailstringValid email address
phonestringPhone number (max 50)
messagestringAdditional details (max 5000)
servicestringRequested service type (max 255)
addressobjectService address (see fields below)
└ line1stringStreet address
└ line2stringApt, suite, unit, etc.
└ citystringCity name
└ statestringState or county
└ zipCodestringPostal / ZIP code
└ countrystringCountry name
timeframestringPreferred timeframe (max 100)
budgetRangestringBudget range (max 100)
photosstring[]Array of HTTPS photo URLs (max 10)

Code Examples

cURL
curl -X POST https://app.tradesender.co.uk/api/v1/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ts_live_abc123..." \
  -d '{
    "type": "quote_request",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "service": "Lawn Mowing",
    "message": "Looking for a weekly mowing service for my front and back garden."
  }'
JavaScript (fetch)
const response = await fetch("https://app.tradesender.co.uk/api/v1/leads", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.TRADESENDER_API_KEY,
  },
  body: JSON.stringify({
    type: "quote_request",
    name: "Jane Smith",
    email: "jane@example.com",
    phone: "+44 7700 900123",
    service: "Lawn Mowing",
    message: "Looking for a weekly mowing service.",
  }),
});

const lead = await response.json();
console.log(lead.id); // "a1b2c3d4-..."
Python (requests)
import requests

response = requests.post(
    "https://app.tradesender.co.uk/api/v1/leads",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "ts_live_abc123...",
    },
    json={
        "type": "quote_request",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "+44 7700 900123",
        "service": "Lawn Mowing",
        "message": "Looking for a weekly mowing service.",
    },
)

lead = response.json()
print(lead["id"])  # "a1b2c3d4-..."

Responses

201
Lead Created

Response
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "quote_request",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+44 7700 900123",
  "createdAt": "2025-06-15T10:30:00.000Z"
}

Error Responses

401
Unauthorized

Missing or invalid API key. Check your X-API-Key header.

403
Forbidden

API key lacks the required leads:write scope, or has been revoked.

422
Validation Error

Request body failed validation. The response includes field-level details:

{
  "error": "Validation failed",
  "details": [
    {
      "path": ["email"],
      "message": "Invalid email"
    }
  ]
}

429
Too Many Requests

Rate limit exceeded. Wait until the X-RateLimit-Reset time before retrying.

Rate Limiting

Every response includes rate limit headers so you can track your usage:

NameTypeRequiredDescription
X-RateLimit-LimitnumberMaximum requests per window
X-RateLimit-RemainingnumberRequests remaining in current window
X-RateLimit-ResetnumberUnix timestamp when the window resets
Handling 429 responses

Read the X-RateLimit-Reset header and wait until that timestamp before retrying. Implement exponential backoff for the best reliability.

Ready to integrate?

Create your free TradeSender account and generate an API key to get started.

Get Started Free