The Bid Developer API (1.0.0)

Your Bid account manager will provide a client_id and client_secret. See the Quickstart guide to make your first API call in 5 minutes.

1. Get Your Credentials

Your Bid account manager will provide:

• client_id — UUID identifying your integration
• client_secret — starts with bid_cs_ (store securely, never expose in client-side code)

2. Exchange for an Access Token

curl -X POST https://api.thebid.uk/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }'

Response:

{
  "data": {
    "access_token": "bid_at_...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "permissions": ["referrals:read", "referrals:write", "properties:read"]
  }
}

3. Verify Your Connection

curl https://api.thebid.uk/v1/health

Returns {"status":"ok","version":"1","timestamp":"..."} — no auth needed.

4. List Your Branches

curl https://api.thebid.uk/v1/branches \
  -H "Authorization: Bearer bid_at_..."

Cache the branch_id values — you'll need one to submit referrals.

5. Submit a Referral

curl -X POST https://api.thebid.uk/v1/referrals \
  -H "Authorization: Bearer bid_at_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "branch_id": "YOUR_BRANCH_ID",
    "house_name_or_number": "42",
    "street_name": "High Street",
    "town_or_city": "London",
    "post_code": "SW1A 1AA",
    "customer_name": "Jane Smith",
    "customer_email": "jane@example.com"
  }'

Response (201):

{
  "data": {
    "referral_id": "uuid-here",
    "status": "new",
    "created_at": "2026-05-23T14:00:00Z"
  }
}

The Bid API uses OAuth 2.0 Client Credentials for machine-to-machine authentication.

How It Works

1. You receive a client_id and client_secret from Bid
2. Exchange them for a short-lived access token (1 hour)
3. Use the access token as a Bearer token on all API requests
4. When it expires, exchange again — no refresh tokens needed

Token Exchange

cURL:

curl -X POST https://api.thebid.uk/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-uuid",
    "client_secret": "bid_cs_your_secret",
    "grant_type": "client_credentials"
  }'

Node/TypeScript:

const res = await fetch("https://api.thebid.uk/v1/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: process.env.BID_CLIENT_ID,
    client_secret: process.env.BID_CLIENT_SECRET,
    grant_type: "client_credentials",
  }),
});
const { data } = await res.json();
// data.access_token, data.expires_in

C#:

var client = new HttpClient();
var response = await client.PostAsync(
    "https://api.thebid.uk/v1/oauth/token",
    new StringContent(JsonSerializer.Serialize(new {
        client_id = Environment.GetEnvironmentVariable("BID_CLIENT_ID"),
        client_secret = Environment.GetEnvironmentVariable("BID_CLIENT_SECRET"),
        grant_type = "client_credentials"
    }), Encoding.UTF8, "application/json"));
var result = await response.Content.ReadFromJsonAsync<TokenResponse>();

Handling Token Expiry

Tokens expire after 3600 seconds (1 hour). On receiving a 401 response, re-authenticate:

async function apiCall(url: string, options: RequestInit = {}) {
  let token = await getToken(); // cached token
  let res = await fetch(url, {
    ...options,
    headers: { ...options.headers, Authorization: `Bearer ${token}` },
  });
  if (res.status === 401) {
    token = await refreshToken(); // exchange credentials again
    res = await fetch(url, {
      ...options,
      headers: { ...options.headers, Authorization: `Bearer ${token}` },
    });
  }
  return res;
}

Storing Credentials

• Never commit client_secret to source control
• Use environment variables or a secrets manager
• The client_secret starts with bid_cs_ — if you see this in logs, rotate immediately

Rate Limits

• 60 requests per minute per client (configurable by Bid)
• Token exchange: 10 requests per minute
• On 429 Too Many Requests: back off and retry after the rate window resets (1 minute)

Permissions

Your client is issued with specific permissions. Calling an endpoint you don't have permission for returns 403 FORBIDDEN:

Receive real-time notifications when referral status changes, properties reach milestones, or new buyers are registered.

Registering a Subscription

curl -X POST https://api.thebid.uk/v1/webhooks \
  -H "Authorization: Bearer bid_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/bid",
    "events": ["referral.created", "referral.status_changed", "property.status_changed"]
  }'

Requirements:

• URL must use https://
• No localhost, private IPs (10.*, 172.16-31.*, 192.168.*), or .local domains
• The secret is returned once on creation — store it immediately

Available Events

Payload Envelope

Every delivery uses this structure:

{
  "version": "1",
  "event_id": "uuid",
  "event_type": "referral.status_changed",
  "created_at": "2026-05-23T14:30:00Z",
  "data": {
    "referral_id": "uuid",
    "old_status": "new",
    "new_status": "contacted"
  }
}

Branch on version for forward compatibility. Treat missing version as "1".

No PII in payloads — only IDs and status values. Fetch full details via the GET endpoints.

Verifying Signatures

Every delivery includes three headers:

• X-Bid-Event — the event type
• X-Bid-Timestamp — Unix epoch seconds at delivery time
• X-Bid-Signature — sha256=<hex HMAC>

The signed string is: timestamp + "." + raw_body

Node/TypeScript:

import crypto from "crypto";

function verifyWebhook(body: string, headers: Headers, secret: string): boolean {
  const timestamp = headers.get("x-bid-timestamp")!;
  const signature = headers.get("x-bid-signature")!;

  // Reject stale deliveries (replay protection)
  if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
    return false;
  }

  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

C#:

bool VerifyWebhook(string body, string timestamp, string signature, string secret) {
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(timestamp)) > 300)
        return false;

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{timestamp}.{body}"));
    var expected = "sha256=" + BitConverter.ToString(hash).Replace("-", "").ToLower();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(signature),
        Encoding.UTF8.GetBytes(expected));
}

Retry Behaviour

Failed deliveries (non-2xx or timeout) are retried with exponential backoff:

After 5 failed attempts, the event is marked as dead-letter (no further retries).

Recommended Architecture

[Bid Webhook] → [Your HTTPS endpoint] → [Message Queue] → [Worker]

Accept the delivery immediately (return 200), queue it for processing. This avoids timeouts if your processing is slow.

Access property documents (legal packs, AML reports, etc.) via short-lived signed URLs.

Listing Documents

Documents are included in property responses when you pass ?include=documents:

curl "https://api.thebid.uk/v1/properties?property_id=UUID&include=documents" \
  -H "Authorization: Bearer bid_at_..."

Response includes:

{
  "data": {
    "property_id": "...",
    "documents": [
      {
        "id": "document-uuid",
        "name": "1716480000-abc123-legal-pack.pdf",
        "type": "Legal Pack",
        "uploaded_at": "2026-05-23T10:00:00Z",
        "modified_at": "2026-05-23T10:00:00Z"
      }
    ]
  }
}

Notes:

• name is the verbatim last path segment from storage — do not assume a stable format
• file_size and mime_type are intentionally not included (not stored on the document record)
• Requires both properties:read and documents:read permissions

Getting a Signed URL

curl -X POST "https://api.thebid.uk/v1/documents/DOCUMENT_ID/access-url" \
  -H "Authorization: Bearer bid_at_..."

Response:

{
  "data": {
    "url": "https://storage.example.com/sign/documents/...",
    "expires_in": 120
  }
}

Download Pattern

The signed URL expires after 120 seconds. Download immediately:

const { data } = await bidApi.post(`/v1/documents/${docId}/access-url`);
const fileResponse = await fetch(data.url);
const buffer = await fileResponse.arrayBuffer();
fs.writeFileSync(`downloads/${filename}`, Buffer.from(buffer));

Security Considerations

• Do not cache signed URLs — they expire in 120 seconds
• Do not log signed URLs — they grant temporary access to the file
• Each access is audit-logged (agent, client, document, IP, timestamp)
• Cross-agent access returns 404 (not 403) to prevent information leakage

All errors return a JSON envelope with an error object containing code, message, and optionally details.

Error Codes

Error Response Shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: branch_id",
    "details": ["Missing required field: branch_id", "Missing required field: post_code"],
    "request_id": "uuid"
  }
}

• details is only present on 4xx errors
• 5xx errors never expose internal messages — always "Internal server error"

CONFLICT (409) — Duplicate Referrals

When submitting a referral that matches an existing address:

Open referral exists:

{
  "error": {
    "code": "CONFLICT",
    "message": "An open referral already exists for this address",
    "details": {
      "reason": "open_referral",
      "referral_id": "existing-uuid",
      "status": "contacted"
    }
  }
}

Active property at address:

{
  "error": {
    "code": "CONFLICT",
    "message": "An active property exists for this address",
    "details": {
      "reason": "active_property",
      "property_id": "property-uuid",
      "referral_id": "referral-uuid",
      "status_category": "instructed"
    }
  }
}

Idempotency

All POST endpoints require an Idempotency-Key header (max 255 characters, UUID recommended):

curl -X POST .../v1/referrals \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  ...

• Same key + same client = replayed original response (no duplicate created)
• Keys expire after 24 hours
• Missing key on POST = 400 VALIDATION_ERROR

Handling Errors Programmatically

const res = await fetch(url, options);

if (res.status === 401) {
  // Re-authenticate and retry
  token = await getNewToken();
  return retry(url, options, token);
}

if (res.status === 429) {
  // Back off 60 seconds (rate window)
  await sleep(60_000);
  return retry(url, options, token);
}

if (res.status === 409) {
  const { error } = await res.json();
  // Use error.details.reason to decide: link to existing or alert user
}

if (res.status >= 500) {
  // Retry with exponential backoff (Bid is having issues)
}

Health check endpoint

Token exchange endpoints

Referral management endpoints

Property data endpoints

Document signed URL endpoints

Webhook subscription management endpoints