The office is closed on Friday 25 December for Christmas.
", "type": "notice", "pinned": true, "publishedBy": { "id": "665f1c2ab7e94d0012a3c4c1", "employeeCode": "EMP0007", "name": "Ravi Kumar" }, "publishedAt": "2026-11-11T05:30:00.000Z", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects": { "get": { "operationId": "list-projects", "tags": [ "Projects" ], "summary": "List projects", "description": "Every project, by name, with its people and how many of its tasks are at each stage. Needs an app approved for Projects.", "security": [ { "soomApp": [ "projects" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only projects with this status.", "schema": { "type": "string", "enum": [ "active", "on_hold", "completed", "archived" ] }, "example": "active" }, { "name": "employeeCode", "in": "query", "required": false, "description": "Only projects this person owns or is a member of.", "schema": { "type": "string" }, "example": "EMP0032" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "status", "owner", "members", "client", "startDate", "dueDate", "taskCounts", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the project, the projectId List tasks takes." }, "name": { "type": "string", "description": "Its name." }, "description": { "type": "string", "description": "What it is about, when written down.", "nullable": true }, "status": { "type": "string", "description": "Where it stands.", "enum": [ "active", "on_hold", "completed", "archived" ] }, "owner": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Who runs it.", "nullable": true }, "members": { "type": "array", "items": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } } }, "description": "Who works on it, besides its owner." }, "client": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the client, the id in List clients." }, "name": { "type": "string", "description": "Its name." } }, "description": "The client it is for, when it is work done for a client.", "nullable": true }, "startDate": { "type": "string", "format": "date", "description": "When it starts.", "nullable": true }, "dueDate": { "type": "string", "format": "date", "description": "When it is due.", "nullable": true }, "taskCounts": { "type": "object", "required": [ "todo", "in_progress", "in_review", "done" ], "properties": { "todo": { "type": "number", "description": "Still to do." }, "in_progress": { "type": "number", "description": "Being worked on." }, "in_review": { "type": "number", "description": "Waiting to be checked." }, "done": { "type": "number", "description": "Finished." } }, "description": "How many of its tasks are at each stage." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b24e5f6a7b8c9d0e1f20314", "name": "Payroll go-live", "description": "Move October payroll from spreadsheets to Soom.", "status": "active", "owner": { "id": "665f1c2ab7e94d0012a3c4c1", "employeeCode": "EMP0007", "name": "Ravi Kumar" }, "members": [ { "id": "665f1c2ab7e94d0012a3c4d5", "employeeCode": "EMP0032", "name": "Priya Sharma" } ], "client": null, "startDate": "2026-10-01", "dueDate": "2026-11-30", "taskCounts": { "todo": 4, "in_progress": 2, "in_review": 1, "done": 9 }, "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks": { "get": { "operationId": "list-tasks", "tags": [ "Projects" ], "summary": "List tasks", "description": "Every task in every project, newest first. Needs an app approved for Projects.", "security": [ { "soomApp": [ "projects" ] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Only this project’s tasks, an id from List projects.", "schema": { "type": "string" }, "example": "6b24e5f6a7b8c9d0e1f20314" }, { "name": "status", "in": "query", "required": false, "description": "Only tasks at this stage.", "schema": { "type": "string", "enum": [ "todo", "in_progress", "in_review", "done" ] }, "example": "in_progress" }, { "name": "employeeCode", "in": "query", "required": false, "description": "Only tasks assigned to this person.", "schema": { "type": "string" }, "example": "EMP0032" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "project", "title", "description", "status", "priority", "assignee", "dueDate", "createdAt", "completedAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the task." }, "project": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List projects." }, "name": { "type": "string", "description": "Its name." } }, "description": "The project it belongs to.", "nullable": true }, "title": { "type": "string", "description": "What it is." }, "description": { "type": "string", "description": "More about it, when written down.", "nullable": true }, "status": { "type": "string", "description": "Its column on the board.", "enum": [ "todo", "in_progress", "in_review", "done" ] }, "priority": { "type": "string", "description": "How urgent it is.", "enum": [ "low", "medium", "high", "urgent" ] }, "assignee": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Who has it. null when nobody does yet.", "nullable": true }, "dueDate": { "type": "string", "format": "date", "description": "When it is due.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When it was added, in UTC.", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "description": "When it was moved to done, in UTC.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b24e5f6a7b8c9d0e1f20425", "project": { "id": "6b24e5f6a7b8c9d0e1f20314", "name": "Payroll go-live" }, "title": "Check October PF figures against last year", "description": null, "status": "in_progress", "priority": "high", "assignee": { "id": "665f1c2ab7e94d0012a3c4d5", "employeeCode": "EMP0032", "name": "Priya Sharma" }, "dueDate": "2026-11-14", "createdAt": "2026-11-02T07:45:00.000Z", "completedAt": null, "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/review-cycles": { "get": { "operationId": "list-review-cycles", "tags": [ "Performance" ], "summary": "List review cycles", "description": "Every review cycle, the latest period first, with how many reviews are in. Needs an app approved for Performance.", "security": [ { "soomApp": [ "performance" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only cycles at this step.", "schema": { "type": "string", "enum": [ "draft", "self_review", "manager_review", "calibration", "closed" ] }, "example": "closed" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "periodFrom", "periodTo", "status", "selfReviewDeadline", "managerReviewDeadline", "people", "selfReviewsDone", "managerReviewsDone", "openedAt", "closedAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the cycle, the cycleId List reviews and List goals take." }, "name": { "type": "string", "description": "Its name." }, "description": { "type": "string", "description": "What it is for, when written down.", "nullable": true }, "periodFrom": { "type": "string", "format": "date", "description": "First day of the time it reviews." }, "periodTo": { "type": "string", "format": "date", "description": "Last day of the time it reviews." }, "status": { "type": "string", "description": "Its step: draft, people reviewing themselves, managers reviewing, HR settling the ratings, or closed.", "enum": [ "draft", "self_review", "manager_review", "calibration", "closed" ] }, "selfReviewDeadline": { "type": "string", "format": "date", "description": "When self-reviews are due, when set.", "nullable": true }, "managerReviewDeadline": { "type": "string", "format": "date", "description": "When managers’ reviews are due, when set.", "nullable": true }, "people": { "type": "number", "description": "How many people it reviews." }, "selfReviewsDone": { "type": "number", "description": "How many sent their self-review." }, "managerReviewsDone": { "type": "number", "description": "How many had their manager’s review sent." }, "openedAt": { "type": "string", "format": "date-time", "description": "When it was opened, in UTC.", "nullable": true }, "closedAt": { "type": "string", "format": "date-time", "description": "When it was closed, in UTC.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b68c9d0e1f2031425364758", "name": "April to September 2026", "description": "How the first half of the financial year went.", "periodFrom": "2026-04-01", "periodTo": "2026-09-30", "status": "closed", "selfReviewDeadline": "2026-10-15", "managerReviewDeadline": "2026-10-31", "people": 42, "selfReviewsDone": 41, "managerReviewsDone": 42, "openedAt": "2026-10-01T04:30:00.000Z", "closedAt": "2026-11-06T09:30:00.000Z", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reviews": { "get": { "operationId": "list-reviews", "tags": [ "Performance" ], "summary": "List reviews", "description": "Each person’s review in each cycle, newest first: who reviews them, where it stands, and the final rating once it is released to them. Never the answers or comments. Needs an app approved for Performance.", "security": [ { "soomApp": [ "performance" ] } ], "parameters": [ { "name": "cycleId", "in": "query", "required": false, "description": "Only this review cycle’s, an id from List review cycles.", "schema": { "type": "string" }, "example": "6b68c9d0e1f2031425364758" }, { "name": "status", "in": "query", "required": false, "description": "Only reviews where this stands.", "schema": { "type": "string", "enum": [ "pending", "self_submitted", "manager_submitted", "closed" ] }, "example": "closed" }, { "name": "employeeCode", "in": "query", "required": false, "description": "Only this person, by the employee code your company gave them.", "schema": { "type": "string" }, "example": "EMP0032" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "cycle", "employee", "reviewer", "status", "selfSubmittedAt", "managerSubmittedAt", "closedAt", "finalRating", "finalRatingLabel", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the review." }, "cycle": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List review cycles." }, "name": { "type": "string", "description": "Its name." } }, "description": "The review cycle it is in.", "nullable": true }, "employee": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Whose review it is.", "nullable": true }, "reviewer": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Who reviews them, usually their manager, when someone does.", "nullable": true }, "status": { "type": "string", "description": "Where it stands: waiting on them, self-review sent, manager’s review sent, or closed.", "enum": [ "pending", "self_submitted", "manager_submitted", "closed" ] }, "selfSubmittedAt": { "type": "string", "format": "date-time", "description": "When they sent their self-review, in UTC.", "nullable": true }, "managerSubmittedAt": { "type": "string", "format": "date-time", "description": "When the reviewer sent theirs, in UTC.", "nullable": true }, "closedAt": { "type": "string", "format": "date-time", "description": "When it was closed, in UTC.", "nullable": true }, "finalRating": { "type": "number", "description": "The final rating, once the review is released to them: it or its cycle closed. null before.", "nullable": true }, "finalRatingLabel": { "type": "string", "description": "What that rating means on the company’s scale.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b68c9d0e1f2031425364869", "cycle": { "id": "6b68c9d0e1f2031425364758", "name": "April to September 2026" }, "employee": { "id": "665f1c2ab7e94d0012a3c4d5", "employeeCode": "EMP0032", "name": "Priya Sharma" }, "reviewer": { "id": "665f1c2ab7e94d0012a3c4c1", "employeeCode": "EMP0007", "name": "Ravi Kumar" }, "status": "closed", "selfSubmittedAt": "2026-10-12T08:20:00.000Z", "managerSubmittedAt": "2026-10-28T11:05:00.000Z", "closedAt": "2026-11-06T09:30:00.000Z", "finalRating": 4, "finalRatingLabel": "Exceeds expectations", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/goals": { "get": { "operationId": "list-goals", "tags": [ "Performance" ], "summary": "List goals", "description": "Everyone’s goals, newest first. A goal its owner still has in draft isn’t listed. Needs an app approved for Performance.", "security": [ { "soomApp": [ "performance" ] } ], "parameters": [ { "name": "cycleId", "in": "query", "required": false, "description": "Only this review cycle’s, an id from List review cycles.", "schema": { "type": "string" }, "example": "6b68c9d0e1f2031425364758" }, { "name": "status", "in": "query", "required": false, "description": "Only goals where this stands.", "schema": { "type": "string", "enum": [ "active", "on_track", "at_risk", "done", "missed" ] }, "example": "on_track" }, { "name": "employeeCode", "in": "query", "required": false, "description": "Only this person, by the employee code your company gave them.", "schema": { "type": "string" }, "example": "EMP0032" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "employee", "cycle", "title", "description", "metric", "status", "weight", "startDate", "dueDate", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the goal." }, "employee": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Whose goal it is.", "nullable": true }, "cycle": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List review cycles." }, "name": { "type": "string", "description": "Its name." } }, "description": "The review cycle it counts towards, when it is tied to one.", "nullable": true }, "title": { "type": "string", "description": "The goal." }, "description": { "type": "string", "description": "More about it, when written down.", "nullable": true }, "metric": { "type": "string", "description": "How it is measured, when written down.", "nullable": true }, "status": { "type": "string", "description": "Where it stands.", "enum": [ "active", "on_track", "at_risk", "done", "missed" ] }, "weight": { "type": "number", "description": "How much it counts, out of 100, when weighted.", "nullable": true }, "startDate": { "type": "string", "format": "date", "description": "When it starts, when set.", "nullable": true }, "dueDate": { "type": "string", "format": "date", "description": "When it is due, when set.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When it was set in Soom, in UTC.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b68c9d0e1f203142536497a", "employee": { "id": "665f1c2ab7e94d0012a3c4d5", "employeeCode": "EMP0032", "name": "Priya Sharma" }, "cycle": { "id": "6b68c9d0e1f2031425364758", "name": "April to September 2026" }, "title": "Move every branch’s payroll to Soom", "description": "Every branch paid from Soom, with no spreadsheet step.", "metric": "Branches paid from Soom", "status": "on_track", "weight": 40, "startDate": "2026-04-01", "dueDate": "2026-09-30", "createdAt": "2026-04-03T06:15:00.000Z", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs": { "get": { "operationId": "list-jobs", "tags": [ "Recruitment" ], "summary": "List jobs", "description": "Every job opening, newest first, with how many candidates are at each stage. Ask for status=open to show what you are hiring for. Needs an app approved for Recruitment.", "security": [ { "soomApp": [ "recruitment" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only openings with this status.", "schema": { "type": "string", "enum": [ "open", "on_hold", "closed", "filled" ] }, "example": "open" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "department", "location", "employmentType", "description", "openings", "status", "hiringManager", "candidateCounts", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the opening, the jobId List candidates takes." }, "title": { "type": "string", "description": "The role." }, "department": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List departments." }, "name": { "type": "string", "description": "Its name." } }, "description": "The department it is in.", "nullable": true }, "location": { "type": "string", "description": "Where the role is, as written on the opening.", "nullable": true }, "employmentType": { "type": "string", "description": "Kind of role.", "enum": [ "full_time", "part_time", "contract", "intern" ] }, "description": { "type": "string", "description": "What the role is, when written down.", "nullable": true }, "openings": { "type": "number", "description": "How many people it is for." }, "status": { "type": "string", "description": "Where it stands. filled is when everyone was hired.", "enum": [ "open", "on_hold", "closed", "filled" ] }, "hiringManager": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Who the role reports to, when set.", "nullable": true }, "candidateCounts": { "type": "object", "required": [ "applied", "screening", "interview", "offer", "hired", "rejected" ], "properties": { "applied": { "type": "number", "description": "Applied, not looked at yet." }, "screening": { "type": "number", "description": "Being screened." }, "interview": { "type": "number", "description": "In interviews." }, "offer": { "type": "number", "description": "Offered the job." }, "hired": { "type": "number", "description": "Hired." }, "rejected": { "type": "number", "description": "Not taken forward." } }, "description": "How many candidates are at each stage." }, "createdAt": { "type": "string", "format": "date-time", "description": "When it was opened in Soom, in UTC.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b35f6a7b8c9d0e1f2031425", "title": "Senior Developer", "department": { "id": "665f0a11b7e94d0012a3b101", "name": "Engineering" }, "location": "Hyderabad", "employmentType": "full_time", "description": "Build and run the payroll engine.", "openings": 2, "status": "open", "hiringManager": { "id": "665f1c2ab7e94d0012a3c4c1", "employeeCode": "EMP0007", "name": "Ravi Kumar" }, "candidateCounts": { "applied": 14, "screening": 5, "interview": 3, "offer": 1, "hired": 0, "rejected": 6 }, "createdAt": "2026-10-20T05:00:00.000Z", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/candidates": { "get": { "operationId": "list-candidates", "tags": [ "Recruitment" ], "summary": "List candidates", "description": "Every candidate, newest first, and where they stand. A hired candidate names the employee they became. Needs an app approved for Recruitment.", "security": [ { "soomApp": [ "recruitment" ] } ], "parameters": [ { "name": "jobId", "in": "query", "required": false, "description": "Only this opening’s candidates, an id from List jobs.", "schema": { "type": "string" }, "example": "6b35f6a7b8c9d0e1f2031425" }, { "name": "stage", "in": "query", "required": false, "description": "Only candidates at this stage.", "schema": { "type": "string", "enum": [ "applied", "screening", "interview", "offer", "hired", "rejected" ] }, "example": "interview" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "job", "name", "email", "source", "stage", "offerStatus", "hiredEmployee", "addedAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the candidate." }, "job": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List jobs." }, "title": { "type": "string", "description": "The role." } }, "description": "The opening they are a candidate for.", "nullable": true }, "name": { "type": "string", "description": "Their name." }, "email": { "type": "string", "description": "Their email." }, "source": { "type": "string", "description": "Where they came from.", "enum": [ "referral", "linkedin", "naukri", "walk_in", "agency", "website", "other" ] }, "stage": { "type": "string", "description": "Where they stand.", "enum": [ "applied", "screening", "interview", "offer", "hired", "rejected" ] }, "offerStatus": { "type": "string", "description": "Where their offer stands, once one was sent.", "enum": [ "sent", "accepted", "declined", "withdrawn" ], "nullable": true }, "hiredEmployee": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "The employee they became, once hired. Their id is the one in List employees.", "nullable": true }, "addedAt": { "type": "string", "format": "date-time", "description": "When they were added in Soom, in UTC.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b35f6a7b8c9d0e1f2031536", "job": { "id": "6b35f6a7b8c9d0e1f2031425", "title": "Senior Developer" }, "name": "Kiran Rao", "email": "kiran.rao@example.com", "source": "referral", "stage": "interview", "offerStatus": null, "hiredEmployee": null, "addedAt": "2026-10-28T09:15:00.000Z", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "add-candidate", "tags": [ "Recruitment" ], "summary": "Add a candidate", "description": "Adds someone who applied for an open job, as HR does in Recruitment: they start at applied, and HR sees they came through the Soom API. Sending the same email for the same job again is refused, so a retry never adds anyone twice. Needs an app approved for Add candidates.", "security": [ { "soomApp": [ "add_candidates" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "name", "email" ], "additionalProperties": false, "properties": { "jobId": { "type": "string", "description": "The job they applied for, the id of an open job from List jobs." }, "name": { "type": "string", "description": "Their full name." }, "email": { "type": "string", "description": "Their email." }, "phone": { "type": "string", "description": "Their phone number, for HR. No list gives it back." }, "source": { "type": "string", "description": "Where they came from. website when left out.", "enum": [ "referral", "linkedin", "naukri", "walk_in", "agency", "website", "other" ] }, "resumeKey": { "type": "string", "description": "Their resume: the resumeKey from Upload a resume, once the file is uploaded." } } }, "example": { "jobId": "6b35f6a7b8c9d0e1f2031425", "name": "Meera Iyer", "email": "meera.iyer@example.com", "phone": "+91 98480 22338", "source": "website", "resumeKey": "v2/tenants/665f0a11b7e94d0012a3b001/recruitment/resumes/1762929600000_k3j9x2_meera-iyer-cv.pdf" } } } }, "responses": { "201": { "description": "What was made.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "candidate", "resumeAttached" ], "properties": { "candidate": { "type": "object", "required": [ "id", "job", "name", "email", "source", "stage", "offerStatus", "hiredEmployee", "addedAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the candidate." }, "job": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List jobs." }, "title": { "type": "string", "description": "The role." } }, "description": "The opening they are a candidate for.", "nullable": true }, "name": { "type": "string", "description": "Their name." }, "email": { "type": "string", "description": "Their email." }, "source": { "type": "string", "description": "Where they came from.", "enum": [ "referral", "linkedin", "naukri", "walk_in", "agency", "website", "other" ] }, "stage": { "type": "string", "description": "Where they stand.", "enum": [ "applied", "screening", "interview", "offer", "hired", "rejected" ] }, "offerStatus": { "type": "string", "description": "Where their offer stands, once one was sent.", "enum": [ "sent", "accepted", "declined", "withdrawn" ], "nullable": true }, "hiredEmployee": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "The employee they became, once hired. Their id is the one in List employees.", "nullable": true }, "addedAt": { "type": "string", "format": "date-time", "description": "When they were added in Soom, in UTC.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } }, "description": "The new candidate, as List candidates gives them." }, "resumeAttached": { "type": "boolean", "description": "true when their resume was attached." } } } } }, "example": { "success": true, "data": { "candidate": { "id": "6b35f6a7b8c9d0e1f2031647", "job": { "id": "6b35f6a7b8c9d0e1f2031425", "title": "Senior Developer" }, "name": "Meera Iyer", "email": "meera.iyer@example.com", "source": "website", "stage": "applied", "offerStatus": null, "hiredEmployee": null, "addedAt": "2026-11-12T06:40:00.000Z", "updatedAt": "2026-11-12T06:40:00.000Z" }, "resumeAttached": true } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/resume-uploads": { "post": { "operationId": "upload-resume", "tags": [ "Recruitment" ], "summary": "Upload a resume", "description": "Gives a link to upload one candidate’s resume to, before Add a candidate. PUT the file to uploadUrl within expiresIn seconds, with a Content-Type header the same as contentType, then send resumeKey with the candidate. Resumes stay private in Soom: HR opens them there, and no list gives them back. Needs an app approved for Add candidates.", "security": [ { "soomApp": [ "add_candidates" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fileName", "contentType", "size" ], "additionalProperties": false, "properties": { "fileName": { "type": "string", "description": "The file’s name, as HR will see it." }, "contentType": { "type": "string", "description": "What kind of file it is: a PDF, a Word file, or a photo of the resume.", "enum": [ "application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "image/jpeg", "image/png" ] }, "size": { "type": "number", "description": "Its size in bytes, up to 15 MB." } } }, "example": { "fileName": "meera-iyer-cv.pdf", "contentType": "application/pdf", "size": 248000 } } } }, "responses": { "201": { "description": "What was made.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "uploadUrl", "resumeKey", "expiresIn", "maxBytes" ], "properties": { "uploadUrl": { "type": "string", "description": "PUT the file’s bytes here, with the same Content-Type, before expiresIn runs out." }, "resumeKey": { "type": "string", "description": "Send this as resumeKey in Add a candidate, once the file is uploaded." }, "expiresIn": { "type": "number", "description": "Seconds uploadUrl works for." }, "maxBytes": { "type": "number", "description": "The largest file it takes, in bytes." } } } } }, "example": { "success": true, "data": { "uploadUrl": "https://example-bucket.s3.ap-south-1.amazonaws.com/v2/tenants/665f0a11b7e94d0012a3b001/recruitment/resumes/1762929600000_k3j9x2_meera-iyer-cv.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=9f2c7e1b", "resumeKey": "v2/tenants/665f0a11b7e94d0012a3b001/recruitment/resumes/1762929600000_k3j9x2_meera-iyer-cv.pdf", "expiresIn": 300, "maxBytes": 15728640 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/clients": { "get": { "operationId": "list-clients", "tags": [ "Clients" ], "summary": "List clients", "description": "Every client, by name, with how many of your people work for it now. Needs an app approved for Clients.", "security": [ { "soomApp": [ "clients" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only clients with this status.", "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "example": "active" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "status", "currency", "invoiceCycle", "timezone", "activeEmployees", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the client, the clientId the other client addresses take." }, "name": { "type": "string", "description": "Its name." }, "status": { "type": "string", "description": "inactive when you no longer work for it.", "enum": [ "active", "inactive" ] }, "currency": { "type": "string", "description": "What it is invoiced in, like INR or AUD." }, "invoiceCycle": { "type": "string", "description": "How often it is invoiced.", "enum": [ "monthly", "fortnightly", "weekly" ] }, "timezone": { "type": "string", "description": "Its time zone, like Australia/Sydney, when set.", "nullable": true }, "activeEmployees": { "type": "number", "description": "How many of your people work for it now." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "665f0a11b7e94d0012a3b801", "name": "Northwind Retail", "status": "active", "currency": "AUD", "invoiceCycle": "monthly", "timezone": "Australia/Sydney", "activeEmployees": 6, "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/client-assignments": { "get": { "operationId": "list-client-assignments", "tags": [ "Clients" ], "summary": "List client assignments", "description": "Who of yours works for which client, newest first: their role there and from when to when. Needs an app approved for Clients.", "security": [ { "soomApp": [ "clients" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "active (the default) is who works for a client now, ended is who did, all is both.", "schema": { "type": "string", "enum": [ "active", "ended", "all" ] }, "example": "active" }, { "name": "clientId", "in": "query", "required": false, "description": "Only this client’s, an id from List clients.", "schema": { "type": "string" }, "example": "665f0a11b7e94d0012a3b801" }, { "name": "employeeCode", "in": "query", "required": false, "description": "Only this person, by the employee code your company gave them.", "schema": { "type": "string" }, "example": "EMP0032" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "client", "employee", "role", "engagementType", "startDate", "endDate", "status", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the assignment." }, "client": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List clients." }, "name": { "type": "string", "description": "Its name." } }, "description": "The client.", "nullable": true }, "employee": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Who works for it.", "nullable": true }, "role": { "type": "string", "description": "Their role at the client, like Backend Developer.", "nullable": true }, "engagementType": { "type": "string", "description": "dedicated is full time for that client; contract is for a piece of work.", "enum": [ "dedicated", "contract" ], "nullable": true }, "startDate": { "type": "string", "format": "date", "description": "When they started for the client.", "nullable": true }, "endDate": { "type": "string", "format": "date", "description": "When they stopped, or are due to.", "nullable": true }, "status": { "type": "string", "description": "active while they work for it.", "enum": [ "active", "ended" ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b46a7b8c9d0e1f203142536", "client": { "id": "665f0a11b7e94d0012a3b801", "name": "Northwind Retail" }, "employee": { "id": "665f1c2ab7e94d0012a3c4d5", "employeeCode": "EMP0032", "name": "Priya Sharma" }, "role": "Backend Developer", "engagementType": "dedicated", "startDate": "2025-04-01", "endDate": null, "status": "active", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/client-invoices": { "get": { "operationId": "list-client-invoices", "tags": [ "Clients" ], "summary": "List client invoices", "description": "What you invoiced your clients, latest period first, with the totals. Each person’s line stays in Soom, since it shows their rate. Needs an app approved for Clients.", "security": [ { "soomApp": [ "clients" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only invoices with this status.", "schema": { "type": "string", "enum": [ "draft", "approved", "sent", "paid", "void" ] }, "example": "sent" }, { "name": "clientId", "in": "query", "required": false, "description": "Only this client’s, an id from List clients.", "schema": { "type": "string" }, "example": "665f0a11b7e94d0012a3b801" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "invoiceNo", "client", "periodStart", "periodEnd", "status", "currency", "subtotal", "taxPercent", "taxAmount", "total", "issueDate", "dueDate", "paidDate", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the invoice." }, "invoiceNo": { "type": "string", "description": "Its number." }, "client": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for it, the id in List clients." }, "name": { "type": "string", "description": "Its name." } }, "description": "Who it is for.", "nullable": true }, "periodStart": { "type": "string", "format": "date", "description": "First day it bills for." }, "periodEnd": { "type": "string", "format": "date", "description": "Last day it bills for." }, "status": { "type": "string", "description": "Where it stands. void is cancelled.", "enum": [ "draft", "approved", "sent", "paid", "void" ] }, "currency": { "type": "string", "description": "What it is in, like AUD." }, "subtotal": { "type": "number", "description": "Before tax." }, "taxPercent": { "type": "number", "description": "The tax rate, like 18." }, "taxAmount": { "type": "number", "description": "The tax." }, "total": { "type": "number", "description": "What the client pays." }, "issueDate": { "type": "string", "format": "date", "description": "When it was sent.", "nullable": true }, "dueDate": { "type": "string", "format": "date", "description": "When it is to be paid by.", "nullable": true }, "paidDate": { "type": "string", "format": "date", "description": "When it was paid.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b46a7b8c9d0e1f203142647", "invoiceNo": "INV-2026-0031", "client": { "id": "665f0a11b7e94d0012a3b801", "name": "Northwind Retail" }, "periodStart": "2026-10-01", "periodEnd": "2026-10-31", "status": "sent", "currency": "AUD", "subtotal": 42000, "taxPercent": 10, "taxAmount": 4200, "total": 46200, "issueDate": "2026-11-01", "dueDate": "2026-11-15", "paidDate": null, "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-runs": { "get": { "operationId": "list-payroll-runs", "tags": [ "Payroll" ], "summary": "List payroll runs", "description": "Each month’s payroll, latest first, with its totals and how far it has gone. Its figures are final once it is locked. Needs an app approved for Payroll.", "security": [ { "soomApp": [ "payroll" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only runs with this status.", "schema": { "type": "string", "enum": [ "draft", "computing", "computed", "locked", "failed" ] }, "example": "locked" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "month", "status", "employeeCount", "grossPay", "deductions", "employerContributions", "netPay", "paidCount", "sentCount", "computedAt", "lockedAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the run." }, "month": { "type": "string", "description": "The month it pays, like 2026-10." }, "status": { "type": "string", "description": "draft is made but not worked out yet, computing is being worked out now, computed is worked out but can still change, locked is final, and failed is a work-out that stopped part-way and has to be done again in Soom.", "enum": [ "draft", "computing", "computed", "locked", "failed" ] }, "employeeCount": { "type": "number", "description": "How many people it pays, leavers’ final settlements included." }, "grossPay": { "type": "number", "description": "Everyone’s pay before anything is taken off." }, "deductions": { "type": "number", "description": "Everything taken off it: PF, ESI, professional tax, TDS, loan instalments and the like." }, "employerContributions": { "type": "number", "description": "What the company pays on top, like its share of PF and ESI." }, "netPay": { "type": "number", "description": "What is taken home: gross pay less deductions." }, "paidCount": { "type": "number", "description": "How many of its payslips are paid." }, "sentCount": { "type": "number", "description": "How many people can see their payslip in Soom." }, "computedAt": { "type": "string", "format": "date-time", "description": "When its figures were last worked out.", "nullable": true }, "lockedAt": { "type": "string", "format": "date-time", "description": "When it was locked.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b57b8c9d0e1f20314253647", "month": "2026-10", "status": "locked", "employeeCount": 42, "grossPay": 2184500, "deductions": 196230, "employerContributions": 98750, "netPay": 1988270, "paidCount": 42, "sentCount": 42, "computedAt": "2026-10-29T10:12:00.000Z", "lockedAt": "2026-10-30T06:45:00.000Z", "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payslips": { "get": { "operationId": "list-payslips", "tags": [ "Payroll" ], "summary": "List payslips", "description": "Each person’s payslip totals, latest month first, then by employee code. A payslip is here once it is final: when its month is locked, or a leaver’s final settlement once it is settled. Until then its figures can change. Needs an app approved for Payroll.", "security": [ { "soomApp": [ "payroll" ] } ], "parameters": [ { "name": "month", "in": "query", "required": false, "description": "Only this month’s, like 2026-10.", "schema": { "type": "string" }, "example": "2026-10" }, { "name": "employeeCode", "in": "query", "required": false, "description": "Only this person, by the employee code your company gave them.", "schema": { "type": "string" }, "example": "EMP0032" }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only what was added or changed at or after this moment, like 2026-11-12T09:30:00Z. The list then comes oldest change first: keep the last updatedAt you got and send it as updatedSince next time. Leave it out the first time to get everything.", "schema": { "type": "string" }, "example": "2026-11-01T00:00:00Z" }, { "name": "page", "in": "query", "required": false, "description": "Which page of the list, from 1.", "schema": { "type": "integer" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "How many items a page, up to 200. 25 when left out.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "A page of the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "month", "employee", "kind", "paidDays", "lopDays", "grossPay", "deductions", "employerContributions", "netPay", "paidOn", "sentToEmployee", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the payslip." }, "month": { "type": "string", "description": "The month it pays, the month of a run in List payroll runs." }, "employee": { "type": "object", "required": [ "id", "employeeCode", "name" ], "properties": { "id": { "type": "string", "description": "Soom’s id for the person, the id in List employees." }, "employeeCode": { "type": "string", "description": "The code your company gave them.", "nullable": true }, "name": { "type": "string", "description": "First and last name." } }, "description": "Whose it is.", "nullable": true }, "kind": { "type": "string", "description": "final_settlement is a leaver’s last payslip, settled on its own.", "enum": [ "monthly", "final_settlement" ] }, "paidDays": { "type": "number", "description": "The days it pays for: the days their salary covered, less loss of pay." }, "lopDays": { "type": "number", "description": "Days of loss of pay." }, "grossPay": { "type": "number", "description": "Their pay before anything is taken off." }, "deductions": { "type": "number", "description": "Everything taken off it: PF, ESI, professional tax, TDS, loan instalments and the like." }, "employerContributions": { "type": "number", "description": "What the company pays on top, like its share of PF and ESI." }, "netPay": { "type": "number", "description": "What is taken home: gross pay less deductions." }, "paidOn": { "type": "string", "format": "date", "description": "The day it was paid.", "nullable": true }, "sentToEmployee": { "type": "boolean", "description": "true once they can see it in Soom: when it is sent to them, or for a final settlement once it is paid." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When it was last added or changed in Soom, in UTC. Send it back as updatedSince.", "nullable": true } } } }, "total": { "type": "integer", "description": "How many items match, on every page together." }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "example": { "success": true, "data": { "items": [ { "id": "6b57b8c9d0e1f20314253758", "month": "2026-10", "employee": { "id": "665f1c2ab7e94d0012a3c4d5", "employeeCode": "EMP0032", "name": "Priya Sharma" }, "kind": "monthly", "paidDays": 30, "lopDays": 1, "grossPay": 82258, "deductions": 8466, "employerContributions": 1800, "netPay": 73792, "paidOn": "2026-10-31", "sentToEmployee": true, "updatedAt": "2026-11-12T06:40:00.000Z" } ], "total": 1, "page": 1, "limit": 25 } } } } }, "400": { "description": "VALIDATION_ERROR: A filter, or a field you sent, is missing or isn’t valid. The message says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHORIZED: No access token, or it isn’t in the Authorization header. INVALID_TOKEN: The access token is wrong or was ended, or its app was switched off by the company or stopped by Soom. TOKEN_EXPIRED: The access token has run out: each works for an hour. Get a new one with your client id and secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SCOPE_MISSING: Your app isn’t approved for this. Ask for it in Settings ▸ Integrations ▸ Soom API, and Soom approves it. API_ACCESS_OFF: The Soom API is switched off for this company. TENANT_UNAVAILABLE: The company’s Soom account isn’t active. FEATURE_OFF: This part of Soom, like overtime, time off, shift changes, assets, expenses, documents, onboarding, daily reports, announcements, projects, performance, recruitment or clients, isn’t switched on for the company, so there is nothing to read or add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: There is no such address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "BALANCES_IN_PAYROLL: The company keeps its leave balances in Xero, so Soom has none to give. Its leave is still in List leave. PAYROLL_IN_XERO: The company runs its payroll in Xero, so Soom has no payroll runs or payslips to give. EMAIL_IN_USE: Someone in Soom already signs in with that email, so nobody was added. Sending the same person twice gets this too. CODE_IN_USE: Someone in the company already has that employee code, so nobody was added. DAY_TAKEN: That day already has times from somewhere else in Soom (clocked in there, typed by HR, regularized or synced), so they weren’t changed. HR can change them in Soom. ON_LEAVE: The person is on approved leave all that day. That day’s leave has to be cancelled in Soom first. PAYROLL_LOCKED: That month’s payroll is locked, so its days can’t change. LEAVE_OVERLAPS: The person already has leave, pending or approved, on some of those days. Sending the same leave twice gets this too. TIMEOFF_OVERLAPS: The person has a request to work from home, or a permission, on those days, and the company doesn’t allow leave on the same days. DAY_WORKED: The person clocked in on a day the leave would cover in full. Ask for half that day, or apply in Soom, where the clock-in can be cancelled. JOB_NOT_OPEN: The job is on hold, closed or filled, so nobody can be added to it. CANDIDATE_EXISTS: Someone with that email is already a candidate for that job, so nobody was added. Sending the same person twice gets this too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "LEAVE_NOT_ALLOWED: The leave type’s rules don’t allow this leave: who can take it, the notice it needs, the fewest or most days, a document it needs, or it is no longer in use. Or every day is a weekly off or holiday. The message says which, ready to show the person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many calls this minute. Wait for the seconds in the Retry-After header, then try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "soomApp": { "type": "oauth2", "description": "Your app’s client id and secret, from Settings ▸ Integrations ▸ Soom API once Soom approved it, swapped for an access token sent as Authorization: Bearer