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 (RFC 6749 §5.1 — flat JSON, no data wrapper):

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

3. Check Your Account

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

Response:

{
  "data": {
    "agent_id": "uuid",
    "agent_name": "Acme Estate Agents",
    "branches": [
      { "branch_id": "uuid", "branch_name": "London Office", "phone_number": "020 7123 4567" }
    ],
    "api_key_name": "Production Key",
    "permissions": ["referrals:read", "referrals:write", "properties:read", "buyers:read"]
  },
  "request_id": "uuid"
}

4. Cache Reference Data

Fetch enum values so your UI stays in sync with accepted values:

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

Response includes referral_types, property_types, tenure_types, bedroom_options, property_status_categories, offer_statuses, document_types, webhook_event_types, and more. No auth required.

5. List Your Branches

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

Response:

{
  "data": [
    { "branch_id": "uuid", "branch_name": "London Office", "phone_number": "020 7123 4567" }
  ],
  "request_id": "uuid"
}

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

6. 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",
    "type": "new_instruction",
    "property": {
      "house_name_or_number": "42",
      "street_name": "High Street",
      "town_or_city": "London",
      "post_code": "SW1A 1AA",
      "property_type": "terraced",
      "number_of_bedrooms": "3",
      "number_of_bathrooms": "2",
      "tenure": "freehold",
      "vacant": true
    },
    "customers": [{
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "07700 900000",
      "house_name_or_number": "10",
      "street_name": "Oak Road",
      "town_or_city": "London",
      "post_code": "SW1A 2BB"
    }],
    "notes": "Seller wants a quick sale"
  }'

Response (201):

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

7. Track Progress

Once a referral is instructed and a property is created, you can track buyers and offers:

# Get property details (includes milestones)
curl "https://api.thebid.uk/v1/properties?property_id=PROPERTY_UUID" \
  -H "Authorization: Bearer bid_at_..."

# Get buyers for a property
curl "https://api.thebid.uk/v1/buyers?property_id=PROPERTY_UUID" \
  -H "Authorization: Bearer bid_at_..."

# Get a single buyer with full offer history
curl "https://api.thebid.uk/v1/buyers?buyer_id=BUYER_UUID" \
  -H "Authorization: Bearer bid_at_..."

8. Set Up Webhooks (Optional)

Receive real-time notifications instead of polling:

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.status_changed", "property.status_changed", "buyer.offer_updated"]
  }'

Store the returned secret immediately — it's shown once and used to verify payload signatures.

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 token = await res.json();
// token.access_token, token.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:

The following endpoints require a valid token but no specific permission:

• GET /v1/me — your account info
• GET /v1/branches — your branch list

The following endpoints require no authentication:

• GET /v1/health — API health check
• GET /v1/enums — reference data / enum values

Attribute marketplace buyers to your own campaigns, channels, or internal IDs using the optional external_ref reference on every buyer.

1. Build a tracking link

Append ?external_ref=YOUR_REF to any marketplace or branded microsite URL. A property URL works best, because the reference is attributed to that specific property:

https://marketplace.thebid.uk/{slug}/property/{id}?external_ref=YOUR_REF

YOUR_REF is any free-text value you control (for example a campaign code or your own internal customer ID). It is treated as opaque text, trimmed, and capped at 128 characters.

2. What happens when a visitor arrives

• The reference is captured on landing and removed from the URL, so if the visitor copies or shares the link it will not carry your reference and tag other people.
• It is attributed to the property the visitor was linked to (when the link points at a property page).
• It persists for up to 5 days and uses last-write-wins — if the visitor later arrives via a different tracking link, the newer reference replaces the older one.
• When the visitor enquires, bids, registers interest, or likes the property, their Buyer record is stamped with your reference.

3. Read it back

The external_ref is returned on every buyer response, and you can list all buyers carrying a reference:

curl https://api.thebid.uk/v1/buyers?external_ref=YOUR_REF \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Lookups are scoped to your own agent — you only ever see your own buyers, even if another partner happens to use the same reference value.

You can also set external_ref directly when creating a referral via the API; see the Referrals endpoint.

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": "in_progress"
  }
}

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": "in_progress"
    }
  }
}

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": "for_sale"
    }
  }
}

Idempotency

POST /referrals requires 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 /referrals = 400 VALIDATION_ERROR
• Other POST endpoints (/webhooks, /documents) do not require idempotency keys

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

Agent account and branch information

Token exchange endpoints

Referral management endpoints

Property data endpoints

Buyer and offer data endpoints, including the optional external_ref tracking reference (see the Buyer Tracking guide)

Reference data and enum values

Document signed URL endpoints

Webhook subscription management endpoints