Skip to content

Ping-post API reference

Two JSON endpoints: price a lead with a ping, then deliver it with a signed post. Code, field names and error messages are in English, so one integration works in every market.

Base URLhttps://verybookedai.com

How the flow works

Send a ping when a visitor submits a request. If you want to sell the lead at the price returned, send a post with the contact details and consent within 15 minutes.

  1. POST /api/lead/ping

    Service, postal code, country and urgency. No personal data.

    A price, its currency, a transaction ID and when it expires.

  2. POST /api/lead/post

    The transaction ID, the contact details and the consent record, signed.

    The lead ID and the payout.

  • Requests and responses are JSON over HTTPS. Send Content-Type: application/json.
  • Amounts are numbers in major units: 45.6 means $45.60.
  • Times are ISO 8601 in UTC.

Signing posts

Pings carry no personal data and are not signed. Sign every post with the signing secret we share when your partner account is approved.

Headers

X-Timestamp
Unix time in whole seconds at the moment you sign the request.
X-Signature-SHA256
Hex-encoded HMAC SHA-256 of {timestamp}.{body} with your signing secret. X-Signature is accepted as an alias.
Content-Type
Always application/json.
  • A timestamp more than 300 seconds away from our clock is refused.
  • Sign the exact bytes you send. Re-serialising the JSON after signing changes the body and breaks the signature.
  • A signature is always verified when present. Where signing is enforced, an unsigned post is refused.
Shell · openssl + cURL
BODY='{"transactionId":"tx_3f9a1c7e5b2d4a60","contact":{"name":"Alex Martin","email":"[email protected]","phoneE164":"+14165550123"},"location":{"postcode":"M5V 3L9","country":"CA"},"consent":{"acknowledged":true,"acknowledgedAt":"2026-09-16T09:00:00.000Z","disclosureText":"I agree that VeryBookedAI and one local business may contact me about this request."},"notes":"Leaking pipe under the kitchen sink."}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$BODY" \
  | openssl dgst -sha256 -hmac "$VBA_SIGNING_SECRET" | sed 's/^.*= //')

curl -X POST https://verybookedai.com/api/lead/post \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature-SHA256: $SIGNATURE" \
  --data "$BODY"
Node.js
import { createHmac } from "node:crypto";

const body = JSON.stringify(lead);
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = createHmac("sha256", process.env.VBA_SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest("hex");

const response = await fetch("https://verybookedai.com/api/lead/post", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Timestamp": timestamp,
    "X-Signature-SHA256": signature,
  },
  body,
});
POST/api/lead/ping

Price a lead

Send the service and where the job is. The response prices the lead and holds that price for 15 minutes.

Request body

parametertype · description
industrystring
Required
The service requested, as an industry slug from the list below. Send one of industry, vertical or taxonomyTermId.
verticalstring
Optional
Alternative to industry.
taxonomyTermIdstring | number
Optional
Alternative to industry: our taxonomy term ID.
postcodestring
Required
Postal code of the job. Send postcode or postal_code.
postal_codestring
Optional
Alternative to postcode.
countrystring
Optional
ISO 3166-1 alpha-2 code of the job’s country. Sets the currency. Defaults to GB.
urgencystring
Optional
How soon the work is needed. emergency, immediate and urgent raise the price; flexible lowers it.
job_typestring
Optional
The kind of job, such as repair or installation. jobType is accepted too.
budgetstring
Optional
The budget the visitor gave, as text.
Example request · cURL
curl -X POST https://verybookedai.com/api/lead/ping \
  -H "Content-Type: application/json" \
  --data '{"industry":"plumber","postcode":"M5V 3L9","country":"CA","urgency":"urgent","job_type":"repair"}'
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Server-Timing: auction;dur=1;desc="Demand Auction", buyer_cell;dur=1;desc="Coverage Gate", total;dur=1
X-Response-Time: 1ms
200 OK · JSON
{
  "accepted": true,
  "bidPrice": 45.6,
  "currency": "CAD",
  "transactionId": "tx_3f9a1c7e5b2d4a60",
  "expiresAt": "2026-09-16T09:15:00.000Z"
}

Response body

parametertype · description
acceptedboolean
Required
true when the lead is priced.
bidPricenumber
Required
The price for this lead, in major units.
currencystring
Required
GBP, EUR, USD, CAD or AUD, from the country.
transactionIdstring
Required
Starts with tx_. Send it with the post.
expiresAtstring
Required
When the price expires, 15 minutes after the ping.

Successful responses carry Server-Timing and X-Response-Time headers.

Currency by country

  • GBGBP
  • FR · BE · DE · AT · ES · IT · NL · IEEUR
  • USUSD
  • CACAD
  • AUAUD
  • Any other country code, including CHGBP
POST/api/lead/post

Deliver a lead

Send the contact details and the consent record against the transaction ID from the ping. Nested fields are listed; the alternatives named in each description are accepted in their place.

Request body

parametertype · description
transactionIdstring
Required
The transactionId from the ping response.
partnerIdstring
Optional
Your partner identifier when operating under multiple affiliate accounts.
contact.emailstring
Required
Email address of the person asking for the quote. email at the top level is accepted instead.
contact.namestring
Optional
Their full name. contact.fullName or top-level name are accepted too.
contact.phoneE164string
Optional
Phone number in E.164 format, for example +447700900123. contact.phone or top-level phone are accepted too.
location.postcodestring
Optional
Postal code of the job; defaults to the ping’s. location.postal_code, postcode or postal_code are accepted too.
location.addressstring
Optional
Street address. location.street_address or top-level address are accepted too.
location.countrystring
Optional
Country code; defaults to the ping’s. Top-level country is accepted too.
consent.acknowledgedtrue
Required
Must be true: the person actively agreed to be contacted about this request.
consent.acknowledgedAtstring
Optional
When they gave consent, in ISO 8601.
consent.disclosureTextstring
Optional
The exact consent wording they agreed to.
consent.recipientHashstring
Optional
SHA-256 hash of the consent recipient authority.
consent.trustedFormCertUrlstring
Optional
Your TrustedForm certificate URL. Top-level trustedFormCertUrl is accepted too.
consent.jornayaLeadIdstring
Optional
Your Jornaya LeadiD token. Top-level jornayaLeadId is accepted too.
notesstring
Optional
The visitor’s description of the job.
answersobject
Optional
Answers to your form’s own questions, as key–value pairs.
Example request · JSON
{
  "transactionId": "tx_3f9a1c7e5b2d4a60",
  "contact": {
    "name": "Alex Martin",
    "email": "[email protected]",
    "phoneE164": "+14165550123"
  },
  "location": {
    "postcode": "M5V 3L9",
    "country": "CA"
  },
  "consent": {
    "acknowledged": true,
    "acknowledgedAt": "2026-09-16T09:00:00.000Z",
    "disclosureText": "I agree that VeryBookedAI and one local business may contact me about this request."
  },
  "notes": "Leaking pipe under the kitchen sink."
}
Example response · 200 OK
{
  "status": "success",
  "leadId": "ld_8c41e0b27d9f4a13",
  "payout": 45.6,
  "transactionId": "tx_3f9a1c7e5b2d4a60",
  "hmacVerified": true,
  "envelope": {
    "piiCiphertext": "<base64>",
    "wrappedDek": "<base64>",
    "iv": "<base64>",
    "authTag": "<base64>"
  }
}

Response body

parametertype · description
statusstring
Required
success when the lead is accepted.
leadIdstring
Required
Starts with ld_. Keep it to reconcile payouts.
payoutnumber
Required
The payout for this lead: the ping’s bidPrice, in its currency.
transactionIdstring
Required
The transaction the lead was delivered against.
hmacVerifiedboolean
Required
true when the post carried a valid signature.
envelopeobject
Optional
The encrypted contact record, as base64 fields. You do not need to store it.

Errors

An error returns ok: false and a message. Validation errors add errors: one entry per problem, with the path of the field and what is wrong. A rejected request stores nothing.

StatusMessageEndpointWhat to do
400Invalid JSON payloadping · postThe body is not valid JSON. Check quoting and encoding.
400Invalid lead ping payloadpingRead errors: send industry (or vertical, taxonomyTermId) and postcode (or postal_code).
400Invalid lead post payloadpostRead errors: send transactionId, an email address and consent.acknowledged: true.
400Transaction has expiredpostMore than 15 minutes have passed since the ping. Send a new ping.
400Invalid transactionId formatpostSend the transactionId exactly as the ping returned it.
401Missing X-Timestamp header for replay attack protectionpostSend X-Timestamp with every signed post.
401Invalid X-Timestamp header formatpostUse Unix time in whole seconds.
401Timestamp outside allowed 300s tolerance windowpostSynchronise your server clock and sign just before sending.
401Invalid HMAC SHA-256 signaturepostSign {timestamp}.{body} over the exact body you send, with the right secret.
401Missing required X-Signature-SHA256 headerpostSigning is enforced: sign the post.
405Method Not Allowedping · postUse POST.
503Lead intake encryption key (LEAD_VAULT_KEK) is not configured.postWe could not store the lead. Retry while the transaction is still valid.
503Unable to save lead record.postWe could not store the lead. Retry while the transaction is still valid.
500The error’s own descriptionping · postUnexpected error on our side. Retry later.
400 · Example: a post without consent
{
  "ok": false,
  "message": "Invalid lead post payload",
  "errors": [
    {
      "code": "custom",
      "path": [
        "consent",
        "acknowledged"
      ],
      "message": "Affirmative consent acknowledged: true is required"
    }
  ]
}

Industry values

Send one of these slugs as industry. Names are shown in your language; the slugs are the same in every market.

Home services104 slugs
  • air-duct-cleanerAir duct cleaner
  • appliance-repairAppliance repair
  • arboristArborist
  • architectArchitect
  • artificial-grass-installerArtificial grass installer
  • artificial-turf-installerArtificial turf installer
  • asbestos-removalAsbestos removal
  • asphalt-contractorTarmac contractor
  • basement-contractorBasement contractor
  • basement-waterproofingBasement waterproofing
  • bathroom-remodelerBathroom fitter
  • bed-bug-exterminatorBed bug exterminator
  • cabinet-installerCabinet installer
  • carpenterCarpenter
  • carpet-cleanerCarpet cleaner
  • chimney-cleanerChimney sweep
  • chimney-repairChimney repair
  • closet-organizerWardrobe organiser
  • concrete-companyConcrete company
  • countertop-installerWorktop installer
  • custom-home-builderBespoke home builder
  • deck-and-patio-builderDecking and patio builder
  • deep-cleaning-serviceDeep cleaning service
  • demolition-contractorDemolition contractor
  • door-installerDoor installer
  • driveway-installerDriveway installer
  • drywall-contractorPlasterboard contractor
  • electricianElectrician
  • epoxy-flooring-installerResin flooring installer
  • ev-charger-installerEV charger installer
  • excavation-contractorGroundworks contractor
  • fence-contractorFence contractor
  • fireplace-installerFireplace installer
  • flooring-contractorFlooring contractor
  • foundation-repairFoundation repair
  • furniture-repairFurniture repair
  • garage-door-installerGarage door installer
  • gazebo-builderGazebo builder
  • general-contractorMain contractor
  • generator-installerGenerator installer
  • geothermal-installerGround source heat pump installer
  • granite-installerGranite installer
  • gutter-cleanerGutter cleaner
  • gutter-installerGutter installer
  • handymanHandyman
  • hardwood-floor-refinishingWood floor restoration
  • heat-pump-installerHeat pump installer
  • home-addition-contractorHome extension contractor
  • home-inspectorHome surveyor
  • home-security-installerHome security installer
  • home-theater-installerHome cinema installer
  • hot-tub-installerHot tub installer
  • house-cleanerHouse cleaner
  • hvac-contractorHVAC contractor
  • insulation-contractorInsulation contractor
  • junk-removal-serviceRubbish removal service
  • kitchen-remodelerKitchen fitter
  • land-clearing-serviceSite clearance service
  • landscaperLandscaper
  • lawn-care-serviceLawn care service
  • lead-paint-remediationLead paint remediation
  • locksmithLocksmith
  • marble-installerMarble installer
  • masonBricklayer
  • move-in-out-cleaning-serviceMove-in and move-out cleaning service
  • outdoor-kitchen-builderOutdoor kitchen builder
  • outdoor-lighting-installerOutdoor lighting installer
  • painterPainter and decorator
  • paving-contractorPaving contractor
  • pergola-builderPergola builder
  • pest-controlPest control
  • plumberPlumber
  • pool-builderSwimming pool builder
  • pool-cleanerSwimming pool cleaner
  • post-construction-cleaningPost-construction cleaning
  • pressure-washerPressure washing service
  • quartz-installerQuartz installer
  • radon-mitigationRadon mitigation
  • remodelerRenovation contractor
  • retaining-wall-builderRetaining wall builder
  • rooferRoofer
  • scaffolding-contractorScaffolding contractor
  • septic-tank-serviceSeptic tank service
  • shed-builderShed builder
  • siding-contractorCladding contractor
  • skylight-installerRooflight installer
  • smart-home-installerSmart home installer
  • snow-removal-serviceSnow clearance service
  • solar-installerSolar installer
  • spray-foam-insulation-contractorSpray foam insulation contractor
  • sprinkler-system-installerGarden irrigation installer
  • structural-engineerStructural engineer
  • terrazzo-installerTerrazzo installer
  • tile-installerTiler
  • tree-serviceTree surgeon
  • upholstery-cleanerUpholstery cleaner
  • walkway-installerPathway installer
  • water-heater-installerWater heater installer
  • water-softener-installerWater softener installer
  • waterproofing-contractorWaterproofing contractor
  • well-drillingBorehole drilling
  • wildlife-removal-serviceWildlife removal service
  • window-cleanerWindow cleaner
  • window-installerWindow installer
Automotive21 slugs
  • auto-body-shopCar body shop
  • auto-detailingCar detailing
  • auto-locksmithAuto locksmith
  • auto-repairCar repair
  • car-audio-installerCar audio installer
  • car-dealershipCar dealership
  • car-rentalCar hire
  • car-washCar wash
  • diesel-mechanicDiesel mechanic
  • electronics-installerVehicle electronics installer
  • limo-rentalLimousine hire
  • marine-mechanicMarine mechanic
  • motorcycle-repairMotorcycle mechanic
  • roadside-assistanceRoadside assistance
  • rv-mechanicRV mechanic
  • tire-shopTyre shop
  • towing-serviceTowing service
  • transmission-repairGearbox repair
  • truck-mechanicLorry mechanic
  • truck-rentalLorry hire
  • window-tintingWindow tinting
Moving & transport3 slugs
  • moving-companyRemovals company
  • piano-moverPiano mover
  • taxiTaxi firm
Health & wellness60 slugs
  • acupuncturistAcupuncturist
  • addiction-counselorAddiction counsellor
  • addiction-treatment-centerAddiction treatment centre
  • audiologistAudiologist
  • barberBarber
  • bariatric-surgeonBariatric surgeon
  • behavioral-therapistBehavioural therapist
  • cardiologistCardiologist
  • child-psychologistChild psychologist
  • chiropractorChiropractor
  • cognitive-therapistCognitive therapist
  • coolsculptingCoolSculpting
  • cosmetic-dentistCosmetic dentist
  • counselorCounsellor
  • crossfit-gymCrossFit gym
  • dance-studioDance studio
  • dental-veneers-clinicDental veneers clinic
  • dentistDentist
  • dermatologistDermatologist
  • ent-specialistENT specialist
  • family-doctorGeneral practitioner
  • family-therapistFamily therapist
  • grief-counselorGrief counsellor
  • gymGym
  • hair-stylistHairdresser
  • hair-transplant-clinicHair transplant clinic
  • laser-clinicLaser clinic
  • laser-hair-removalLaser hair removal
  • life-coachLife coach
  • marriage-counselorMarriage counsellor
  • martial-arts-studioMartial arts studio
  • massage-spaMassage spa
  • massage-therapistMassage therapist
  • med-spaMedical spa
  • mental-health-counselorMental health counsellor
  • nail-technicianNail technician
  • naturopathic-doctorNaturopath
  • nutritionistNutritionist
  • obstetrician-gynecologistObstetrician and gynaecologist
  • occupational-therapistOccupational therapist
  • ophthalmologistOphthalmologist
  • optometristOptometrist
  • oral-surgeonOral surgeon
  • orthodontistOrthodontist
  • orthopedic-surgeonOrthopaedic surgeon
  • pain-management-clinicPain management clinic
  • pediatricianPaediatrician
  • personal-trainerPersonal trainer
  • physical-therapistPhysiotherapist
  • plastic-surgeonPlastic surgeon
  • podiatristPodiatrist
  • psychiatristPsychiatrist
  • psychologistPsychologist
  • speech-therapistSpeech and language therapist
  • therapistTherapist
  • trauma-therapistTrauma therapist
  • urgent-careUrgent treatment centre
  • veterinarianVeterinary surgeon
  • walk-in-clinicWalk-in clinic
  • weight-loss-clinicWeight-loss clinic
Medical & senior care11 slugs
  • adult-day-careAdult day centre
  • assisted-livingAssisted living
  • home-healthcareHome healthcare
  • hospice-careHospice care
  • live-in-caregiverLive-in carer
  • medical-transportationMedical transport
  • memory-careDementia care
  • nursing-homeCare home
  • senior-careElderly care
  • senior-home-careElderly home care
  • senior-transportationElderly transport
Legal services25 slugs
  • adoption-lawyerAdoption lawyer
  • bankruptcy-lawyerInsolvency lawyer
  • business-lawyerBusiness lawyer
  • car-accident-lawyerRoad traffic accident lawyer
  • child-custody-lawyerChild custody lawyer
  • corporate-lawyerCorporate lawyer
  • criminal-defense-lawyerCriminal defence lawyer
  • dui-lawyerDUI lawyer
  • elder-law-attorneyElder law solicitor
  • employment-lawyerEmployment lawyer
  • estate-planning-lawyerEstate planning lawyer
  • golden-visa-consultantGolden visa consultant
  • guardianship-lawyerGuardianship lawyer
  • immigration-lawyerImmigration lawyer
  • intellectual-property-lawyerIntellectual property lawyer
  • lawyerLawyer
  • medical-malpractice-lawyerClinical negligence lawyer
  • notary-publicNotary public
  • personal-injury-lawyerPersonal injury lawyer
  • probate-lawyerProbate lawyer
  • real-estate-lawyerProperty lawyer
  • tax-lawyerTax lawyer
  • trust-lawyerTrust lawyer
  • will-attorneyWill writer
  • workers-compensation-lawyerWorkplace injury lawyer
Property law & finance4 slugs
  • accountantAccountant
  • financial-advisorFinancial adviser
  • insurance-brokerInsurance broker
  • tax-preparerTax preparer
Financial services26 slugs
  • auto-insurance-agentMotor insurance agent
  • bankruptcy-advisorInsolvency adviser
  • business-insurance-brokerBusiness insurance broker
  • business-loan-brokerBusiness loan broker
  • cpaChartered accountant
  • credit-repair-serviceCredit repair service
  • debt-consolidationDebt consolidation adviser
  • disability-insurance-agentDisability insurance agent
  • equipment-financingEquipment finance broker
  • estate-plannerEstate planner
  • financial-counselorFinancial counsellor
  • financial-plannerFinancial planner
  • health-insurance-brokerHealth insurance broker
  • home-insurance-agentHome insurance agent
  • insurance-agentInsurance agent
  • investment-advisorInvestment adviser
  • life-insurance-agentLife insurance agent
  • loan-officerLoan officer
  • mortgage-brokerMortgage broker
  • mortgage-lenderMortgage lender
  • payroll-servicePayroll service
  • retirement-plannerRetirement planner
  • tax-debt-reliefTax debt relief service
  • tax-plannerTax planner
  • timeshare-exitTimeshare exit service
  • wealth-managerWealth manager
Professional services24 slugs
  • bookkeeperBookkeeper
  • business-brokerBusiness broker
  • business-coachBusiness coach
  • commercial-cateringCommercial catering
  • commercial-electricalCommercial electrical
  • commercial-hvacCommercial HVAC
  • commercial-landscapingCommercial landscaping
  • commercial-paintingCommercial painting
  • commercial-plumbingCommercial plumbing
  • commercial-printingCommercial printing
  • commercial-roofingCommercial roofing
  • commercial-securityCommercial security
  • commercial-waste-managementCommercial waste management
  • computer-repairComputer repair
  • copywriterCopywriter
  • data-recovery-serviceData recovery service
  • elevator-serviceLift service
  • fire-protection-serviceFire protection service
  • it-consultantIT consultant
  • project-managerProject manager
  • recruiterRecruitment consultant
  • signage-companySignage company
  • staffing-agencyStaffing agency
  • temp-agencyTemporary staffing agency
Business services14 slugs
  • commercial-cleaningCommercial cleaning
  • content-marketing-agencyContent marketing agency
  • e-commerce-agencyE-commerce agency
  • email-marketing-agencyEmail marketing agency
  • graphic-designerGraphic designer
  • hr-consultantHR consultant
  • industrial-cleaningIndustrial cleaning
  • manufacturerManufacturer
  • marketing-agencyMarketing agency
  • ppc-agencyPPC agency
  • seo-agencySEO agency
  • social-media-agencySocial media agency
  • video-producerVideo producer
  • web-designerWeb designer
Property & real estate13 slugs
  • closing-agentClosing agent
  • escrow-serviceEscrow service
  • home-stagerHome stager
  • interior-decoratorInterior decorator
  • leasing-agentLetting agent
  • mold-inspectorMould inspector
  • property-managerProperty manager
  • real-estate-agentEstate agent
  • real-estate-appraiserProperty valuer
  • real-estate-brokerEstate agency broker
  • real-estate-photographerProperty photographer
  • termite-inspectorTermite inspector
  • title-companyTitle company
Events & lifestyle17 slugs
  • bartenderBartender
  • catererCaterer
  • corporate-event-plannerCorporate event planner
  • djDJ
  • event-plannerEvent planner
  • floristFlorist
  • live-bandLive band
  • magicianMagician
  • party-plannerParty planner
  • personal-chefPersonal chef
  • photographerPhotographer
  • videographerVideographer
  • wedding-catererWedding caterer
  • wedding-djWedding DJ
  • wedding-officiantWedding celebrant
  • wedding-photographerWedding photographer
  • wedding-plannerWedding planner
Education & tutoring9 slugs
  • art-teacherArt teacher
  • babysitterBabysitter
  • dance-teacherDance teacher
  • daycareDay nursery
  • driving-schoolDriving school
  • music-teacherMusic teacher
  • nannyNanny
  • special-needs-tutorSpecial educational needs tutor
  • tutorTutor
Emergency call-outs5 slugs
  • fire-damage-restorationFire damage restoration
  • hoarding-cleanupHoarding clean-up
  • mold-remediation-specialistMould remediation specialist
  • security-guardSecurity guard
  • water-damage-restorationWater damage restoration

Ready to integrate?

Apply for partner access. We share your signing secret once your application is approved.