{"openapi":"3.1.0","info":{"title":"TeamzHQ API","version":"1.0.0","description":"Connect TeamzHQ to the systems your business already runs. Authenticate with a workspace API key: Authorization: Bearer tzhq_... Keys with the read scope can list; keys with the write scope can also create and update employees."},"servers":[{"url":"https://teamzhq.vercel.app/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/employees":{"get":{"summary":"List employees","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"},{"name":"status","in":"query","schema":{"enum":["active","left"]}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass as cursor to get the next page."}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}},"post":{"summary":"Create or update employees in bulk","description":"Matches on external_id, then email. Send one person or { employees: [...] } with up to 500. Set managers with manager_email or manager_external_id.","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EmployeeInput"},{"type":"object","properties":{"employees":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/EmployeeInput"}}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"created_ids":{"type":"array","items":{"type":"string"}},"updated_ids":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}}},"/employees/{id}":{"get":{"summary":"Get one employee","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}},"patch":{"summary":"Update an employee","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"full_name":{"type":"string"},"job_title":{"type":"string"},"department":{"type":"string"},"level":{"type":"string"},"start_date":{"type":"string","format":"date"},"status":{"enum":["active","left"]},"manager_id":{"type":"string","format":"uuid"},"external_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}}},"/jobs":{"get":{"summary":"List jobs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"},{"name":"status","in":"query","schema":{"enum":["draft","open","closed"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass as cursor to get the next page."}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}}},"/applications":{"get":{"summary":"List applications","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"},{"name":"job_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"stage","in":"query","schema":{"enum":["applied","screening","interview","offer","hired","rejected"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass as cursor to get the next page."}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}}},"/goals":{"get":{"summary":"List goals","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"},{"name":"employee_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Goal"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass as cursor to get the next page."}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}}},"/reviews":{"get":{"summary":"Released review results","description":"Without cycle_id, lists released cycles. With cycle_id, returns final ratings per person.","parameters":[{"name":"cycle_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorised"}}}}},"webhooks":{"employee.created":{"post":{"summary":"A person is added","description":"Signed with your endpoint secret. Header TeamzHQ-Signature: t=<unix seconds>,v1=<hex HMAC SHA256 of \"t.body\">. Reject if t is more than five minutes old.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"employee.created"},"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Return any 2xx to acknowledge."}}}},"employee.updated":{"post":{"summary":"A person's details change","description":"Signed with your endpoint secret. Header TeamzHQ-Signature: t=<unix seconds>,v1=<hex HMAC SHA256 of \"t.body\">. Reject if t is more than five minutes old.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"employee.updated"},"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Return any 2xx to acknowledge."}}}},"application.created":{"post":{"summary":"Someone applies for a job","description":"Signed with your endpoint secret. Header TeamzHQ-Signature: t=<unix seconds>,v1=<hex HMAC SHA256 of \"t.body\">. Reject if t is more than five minutes old.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"application.created"},"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Return any 2xx to acknowledge."}}}},"application.stage_changed":{"post":{"summary":"A candidate moves stage","description":"Signed with your endpoint secret. Header TeamzHQ-Signature: t=<unix seconds>,v1=<hex HMAC SHA256 of \"t.body\">. Reject if t is more than five minutes old.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"application.stage_changed"},"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Return any 2xx to acknowledge."}}}},"goal.completed":{"post":{"summary":"A goal is completed","description":"Signed with your endpoint secret. Header TeamzHQ-Signature: t=<unix seconds>,v1=<hex HMAC SHA256 of \"t.body\">. Reject if t is more than five minutes old.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"goal.completed"},"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Return any 2xx to acknowledge."}}}},"review.released":{"post":{"summary":"A review cycle is released","description":"Signed with your endpoint secret. Header TeamzHQ-Signature: t=<unix seconds>,v1=<hex HMAC SHA256 of \"t.body\">. Reject if t is more than five minutes old.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"review.released"},"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Return any 2xx to acknowledge."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A workspace API key from Integrations."}},"responses":{"Unauthorised":{"description":"Missing, invalid or revoked API key."}},"schemas":{"Employee":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"full_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"level":{"type":"string","nullable":true},"manager_id":{"type":"string","nullable":true},"start_date":{"type":"string","format":"date","nullable":true},"status":{"enum":["active","left"]},"external_id":{"type":"string","nullable":true},"source":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"EmployeeInput":{"type":"object","required":["email","full_name"],"properties":{"email":{"type":"string"},"full_name":{"type":"string"},"job_title":{"type":"string"},"department":{"type":"string"},"level":{"type":"string"},"start_date":{"type":"string","format":"date"},"external_id":{"type":"string"},"manager_email":{"type":"string"},"manager_external_id":{"type":"string"},"status":{"enum":["active","left"]}}},"Job":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"level":{"type":"string"},"city":{"type":"string"},"work_mode":{"type":"string"},"employment_type":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"created_at":{"type":"string"}}},"Application":{"type":"object","properties":{"id":{"type":"string"},"job_id":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","nullable":true},"source":{"type":"string"},"stage":{"type":"string"},"ai_fit":{"type":"integer","nullable":true},"created_at":{"type":"string"}}},"Goal":{"type":"object","properties":{"id":{"type":"string"},"employee_id":{"type":"string","nullable":true},"parent_id":{"type":"string","nullable":true},"title":{"type":"string"},"progress":{"type":"integer"},"status":{"enum":["on_track","at_risk","off_track","done"]},"due_date":{"type":"string","nullable":true}}}}}}