{"openapi":"3.1.2","info":{"title":"Pulse Developer API","version":"1.0.0","description":"Submit website enquiries to Pulse. Generate a lead-submission secret in Settings → Developer API. Keep the secret on your server. Other existing API operations are documented at /api-reference."},"servers":[{"url":"/api/v1","description":"This Pulse environment"}],"security":[{"bearerAuth":[]},{"apiKey":[]}],"paths":{"/leads":{"post":{"operationId":"submitLead","tags":["Leads"],"summary":"Submit or correct a website enquiry","description":"Requires leads:write or the existing broad write scope and the Open API entitlement. Send a stable external_id. A new enquiry needs name (or first_name/last_name) and email or phone. Repeating the id updates only submitted fields that changed since the last accepted submission. Omitted fields stay unchanged; null clears an optional field if a contact method remains. An identical retry preserves staff edits. Staff notes, assignment, stage and opt-out are never writable here. Requests sharing an external_id must be sent in order; do not retry an older version after submitting a correction. Different integration secrets have separate enquiry ids. Refresh the existing secret to retain retry history.","requestBody":{"required":true,"description":"JSON object, maximum 16 KiB. Unknown fields are rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadSubmission"},"example":{"external_id":"website:enquiry-12345","first_name":"Alex","last_name":"Taylor","email":"alex@example.com","phone":"0412 345 678","source":"Direct Website","message":"Swimming lessons for Jamie, age 7. Tuesday afternoons preferred.","plan_interest":"Learn to swim"}}}},"responses":{"200":{"description":"Existing enquiry accepted; same lead id.","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"},"description":"Reference for support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Shared write budget per key: 1000 requests/hour."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Estimated remaining write requests."},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp when the write window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadReceipt"},"example":{"data":{"id":"73d2f897-3926-4cf9-a49e-31c0b994d211","external_id":"website:enquiry-12345"},"created":false}}}},"201":{"description":"New lead created in the gym inbox.","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"},"description":"Reference for support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Shared write budget per key: 1000 requests/hour."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Estimated remaining write requests."},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp when the write window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadReceipt"},"example":{"data":{"id":"73d2f897-3926-4cf9-a49e-31c0b994d211","external_id":"website:enquiry-12345"},"created":true}}}},"400":{"description":"Invalid input or correction would remove the last contact method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope missing or Open API entitlement unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Staff deleted this enquiry. A retry cannot recreate it; use a new id for a genuinely new enquiry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds 16 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Write rate limit exceeded. Wait until X-RateLimit-Reset before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"},"description":"Reference for support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Shared write budget per key: 1000 requests/hour."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Estimated remaining write requests."},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp when the write window resets."}}},"500":{"description":"Unable to persist the enquiry. Retry with backoff and the same external_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"},"description":"Reference for support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Shared write budget per key: 1000 requests/hour."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Estimated remaining write requests."},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp when the write window resets."}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Developer secret from Settings → Developer API. Paste the secret without the Bearer prefix."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to Authorization: Bearer."}},"schemas":{"LeadSubmission":{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":200,"description":"Stable enquiry id, unique within this integration. Reuse on retries and corrections. Refreshing the secret preserves this identity."},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Full contact name. Alternatively send first_name and optional last_name. Required on creation, along with email or phone."},"first_name":{"type":"string","minLength":1,"maxLength":200},"last_name":{"type":["string","null"],"minLength":1,"maxLength":200},"email":{"type":["string","null"],"minLength":1,"maxLength":255,"format":"email"},"phone":{"type":["string","null"],"minLength":1,"maxLength":40},"phone_country":{"type":"string","minLength":1,"maxLength":2,"enum":["AU","NZ","GB","US","CA","AF","AX","AL","DZ","AS","AD","AO","AI","AG","AR","AM","AW","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BR","IO","VG","BN","BG","BF","BI","KH","CM","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","XK","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NI","NE","NG","NU","NF","KP","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","KR","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","UY","VI","UZ","VU","VA","VE","VN","WF","EH","YE","ZM","ZW"],"description":"Country code for local phone numbers. Send together with phone; defaults to the gym country."},"source":{"type":"string","minLength":1,"maxLength":80,"enum":["Walk-In","Phone-In","Direct Website","Referral","Referral - POS","Internet Lead","Outreach"],"description":"Defaults to Direct Website on creation; omitted values are preserved on correction."},"message":{"type":["string","null"],"minLength":1,"maxLength":5000,"description":"Website enquiry text, displayed separately from staff notes. Can include child details and preferred lesson times."},"plan_interest":{"type":["string","null"],"minLength":1,"maxLength":200}},"not":{"required":["name"],"anyOf":[{"required":["first_name"]},{"required":["last_name"]}]},"dependentRequired":{"last_name":["first_name"],"phone_country":["phone"]}},"LeadReceipt":{"type":"object","additionalProperties":false,"required":["data","created"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["id","external_id"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"}}},"created":{"type":"boolean"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}