{"openapi":"3.1.0","info":{"title":"Usual API","version":"1.0.0","description":"Clients, checklists and requests for your own scripts and integrations. Authenticate with a personal access token from Settings › Developers: `Authorization: Bearer usl_…`."},"servers":[{"url":"https://api.usual.so"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A personal access token from Settings › Developers (usl_…)."}},"schemas":{"Client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["person","entity"]},"email":{"type":["string","null"]},"archived":{"type":"boolean"}},"required":["id","number","name","kind","email","archived"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"NewClient":{"type":"object","properties":{"kind":{"type":"string","enum":["person","entity"]},"name":{"type":"string","minLength":1,"maxLength":200,"description":"A person's full name or a business"},"contact":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","maxLength":100},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":40}},"required":["firstName"]}},"required":["kind","name"]},"Checklist":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string"},"builtIn":{"type":"boolean"}},"required":["id","name","category","builtIn"]},"RequestSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clientId":{"type":"string","format":"uuid"},"clientName":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"dueAt":{"type":["string","null"]},"received":{"type":"number"},"required":{"type":"number"},"percent":{"type":"number"},"toReview":{"type":"number"}},"required":["id","clientId","clientName","name","status","dueAt","received","required","percent","toReview"]},"Request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clientId":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"dueAt":{"type":["string","null"]},"received":{"type":"number"},"required":{"type":"number"},"percent":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"}},"required":["id","title","type","status"]}}},"required":["id","clientId","name","status","dueAt","received","required","percent","items"]},"NewRequest":{"type":"object","properties":{"clientId":{"type":"string","format":"uuid"},"templateId":{"type":"string","format":"uuid"},"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2027-03-15"},"send":{"type":"boolean","default":true,"description":"Email the client now (true), or keep it as a draft to check in the app"}},"required":["clientId","templateId","dueDate"]}},"parameters":{}},"paths":{"/v1/clients":{"get":{"summary":"List clients","security":[{"bearer":[]}],"responses":{"200":{"description":"Every client, archived ones last","content":{"application/json":{"schema":{"type":"object","properties":{"clients":{"type":"array","items":{"$ref":"#/components/schemas/Client"}}},"required":["clients"]}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a client","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewClient"}}}},"responses":{"201":{"description":"The new client","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates":{"get":{"summary":"List checklists","security":[{"bearer":[]}],"responses":{"200":{"description":"The firm's checklists and the built-in library","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/Checklist"}}},"required":["templates"]}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/requests":{"get":{"summary":"List requests","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","enum":["active","completed","archived"],"description":"Open ones (default), completed, or archived"},"required":false,"description":"Open ones (default), completed, or archived","name":"scope","in":"query"}],"responses":{"200":{"description":"Requests in that scope","content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/RequestSummary"}}},"required":["requests"]}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a request from a checklist, and send it","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewRequest"}}}},"responses":{"201":{"description":"The new request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["id","status"]}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/requests/{id}":{"get":{"summary":"Get a request and where each item stands","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"summary":"The firm this token belongs to","security":[{"bearer":[]}],"responses":{"200":{"description":"The firm","content":{"application/json":{"schema":{"type":"object","properties":{"firm":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"required":["firm"]}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks":{"post":{"summary":"Subscribe an address to an event","description":"Usual POSTs { id, event, created, data } there each time it happens. For tools that subscribe for themselves, like Zapier; people add webhooks in Settings › Developers.","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri"},"event":{"type":"string","enum":["request.sent","request.submitted","request.all_received","request.completed"]}},"required":["url","event"]}}}},"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}}}},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/{id}":{"delete":{"summary":"Unsubscribe","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removed"},"401":{"description":"Missing or revoked token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}