{"openapi":"3.1.0","info":{"title":"The Veil API","version":"1.0.0","description":"Read your leads, bookings, invoices and calendar, add leads, notes and scheduled replies, and manage webhooks. A key acts as the team member who made it: it sees what they see in the portal, narrowed to the key's scopes. Nothing in the API messages a client on its own; replies go out through your scheduled-send queue. Read keys on Pro and Studio; write keys on Studio. Make keys on Team → API and connectors.","contact":{"name":"The Veil","url":"https://www.theveilwedding.com/help"}},"servers":[{"url":"https://www.theveilwedding.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"veil_live_api_…, shown once when you make it."}},"responses":{"Error":{"description":"An error. code is one of unauthorized, key_revoked, key_paused, scope_missing, not_found, not_allowed, validation, plan_required, rate_limited, too_large, server_error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"scope":{"type":"string"},"plan":{"type":"string"},"fields":{"type":"object"}},"required":["code","message"]}}}}}}},"schemas":{"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"The couple, the event name, or the contact."},"status":{"type":"string","enum":["sent","vendor_opened","replied","proposal_sent","booked","dead"]},"event":{"type":"object","properties":{"type":{"type":"string","enum":["wedding","corporate","social","other"]},"date":{"type":["string","null"],"format":"date"},"guests":{"type":["string","null"]},"budget":{"type":["string","null"]},"name":{"type":["string","null"]},"organization":{"type":["string","null"]},"room_id":{"type":["string","null"],"format":"uuid"}}},"contact":{"type":"object","description":"Email and phone only when the key's member is a coordinator or above.","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"source":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"assigned_to":{"type":["string","null"],"format":"uuid"},"lost_reason":{"type":["string","null"]},"on_the_veil":{"type":"boolean","description":"The client plans on The Veil's app."},"waiting_on":{"type":"string","enum":["you","them","nobody"]},"quote_total_cents":{"type":["integer","null"]},"currency":{"type":"string","const":"usd"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"portal_url":{"type":"string","format":"uri"}}}}},"paths":{"/me":{"get":{"summary":"The business, the member the key acts as, and the key","responses":{"200":{"description":"Who you are","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/leads":{"get":{"summary":"Leads, newest first","description":"Scope leads:read. Paginate with next_cursor.","parameters":[{"name":"status","in":"query","required":false,"description":"sent, vendor_opened, replied, proposal_sent, booked or dead","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Only leads changed at or after this time (ISO 8601)","schema":{"type":"string","format":"date-time"}},{"name":"assigned","in":"query","required":false,"description":"A member's id","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search names, email, event name and organization","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 200, default 50","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of leads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Add a lead","description":"Scope leads:write, Studio. For voice AI, website builders and forms. The same email (or phone) to the same business within an hour returns the existing lead with duplicate: true. The team is notified as for any new lead, and lead.created webhooks fire.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact"],"properties":{"contact":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}}},"name":{"type":"string","description":"The couple's names, if different from the contact"},"event":{"type":"object","properties":{"date":{"type":"string","format":"date"},"type":{"type":"string","enum":["wedding","corporate","social","other"]},"guests":{"type":"string"},"budget":{"type":"string"}}},"message":{"type":"string","maxLength":4000},"source":{"type":"string","description":"Shown on the lead as a tag, e.g. AddSalt. Defaults to the key's name."}}}}}},"responses":{"200":{"description":"An existing lead (duplicate)","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"The new lead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/leads/{id}":{"get":{"summary":"A lead with its notes, messages and scheduled replies","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The lead","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Assign, tag or close a lead","description":"Scope leads:write, Studio. assigned_to needs a manager. status may only be lost, with lost_reason.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assigned_to":{"type":["string","null"],"format":"uuid"},"tags":{"type":"array","items":{"type":"string"},"maxItems":20},"status":{"type":"string","const":"lost"},"lost_reason":{"type":"string","enum":["budget","date","elsewhere","no_reply","other"]},"lost_note":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"The lead","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/leads/{id}/notes":{"post":{"summary":"Add a note","description":"Scope leads:write. Notes are internal to your team and are marked with the key's name.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":4000}}}}}},"responses":{"201":{"description":"The note","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/leads/{id}/replies":{"post":{"summary":"Schedule a reply to the client","description":"Scope leads:write. Goes out through your scheduled-send queue, never inline: at send_at (2 minutes to 180 days ahead), or in about three minutes. Cancel it from the lead in the portal.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":4000},"send_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"The scheduled reply","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/bookings":{"get":{"summary":"Booked events in a window","description":"Scope bookings:read. money appears when the key's member is a manager or owner.","parameters":[{"name":"from","in":"query","required":false,"description":"Default today","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Default a year on","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Bookings","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/bookings/{id}":{"get":{"summary":"One booking","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/invoices":{"get":{"summary":"Invoices","description":"Scope invoices:read; owners and managers.","parameters":[{"name":"lead","in":"query","required":false,"description":"A lead's id","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"sent, scheduled, paid or overdue","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 200","schema":{"type":"integer"}}],"responses":{"200":{"description":"Invoices","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/payments":{"get":{"summary":"Payments through The Veil, with fees and net","description":"Scope invoices:read; owners and managers.","parameters":[{"name":"from","in":"query","required":false,"description":"Default 90 days ago","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Default today","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Payments","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/calendar":{"get":{"summary":"Booked days, holds, tours and tastings, and blocked days","description":"Scope calendar:read. Up to 400 days at a time.","parameters":[{"name":"from","in":"query","required":false,"description":"Default today","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Default 90 days on","schema":{"type":"string","format":"date"}},{"name":"room","in":"query","required":false,"description":"A room's id","schema":{"type":"string"}}],"responses":{"200":{"description":"The calendar","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/clients/{id}":{"get":{"summary":"A lead's client and their page link","description":"Scope clients:read; coordinators and up.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The client","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/team":{"get":{"summary":"Members and roles","description":"Scope team:read.","responses":{"200":{"description":"The team","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks":{"get":{"summary":"Webhook endpoints","description":"Scope webhooks:manage; owners and managers.","responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Add a webhook endpoint","description":"Returns the signing secret once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"kind":{"type":"string","enum":["generic","slack"]},"events":{"type":"array","items":{"type":"string","enum":["lead.created","lead.replied","lead.assigned","quote.sent","quote.accepted","booking.confirmed","payment.received","client.details_sent"]}},"description":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"The endpoint and its secret","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}}}