{ "openapi": "3.0.0", "info": { "title": "Folks API Documentation", "description": "This documentation explains how to use the FolksHR API to access your company's data via our REST API.\n\n## Authentication\nTo authenticate requests a scope permission is required, and must be submitted when generating a token through the oauth/token endpoint.\nMultiple scopes should be seperated by blank spaces. Please note that the scope `company:{uuid}` is no longer required if you make a request for only one company.\nHowever, if your client_id / client_secret can be used to access multiple companies, the `company:{uuid}` scope is required to determine for which company the access_token needs to be created.\n\n## Scopes\nEach request requires a scope to be defined, with the exception of the authentication requests. These scopes are explained in each request's documentation and are used to specify which actions can be perform with the access_token.\nIt is recommended to only specify the scopes needed for the access_token actions, since it limits what can be done with this access token, in case it is leaked.\n\n## Embedding related data with `_embed`\nMost read endpoints return only their own fields. Related data is opt-in through the `_embed` query parameter, repeated once per relation:\n\n```\nGET /api/v2/absences/12?_embed[]=employee&_embed[]=reason\n```\n\nThe accepted values differ from one endpoint to the next, so the authoritative list is the `_embed[]` parameter documented on each operation. Four rules explain why a field you expect may be missing:\n\n1. **Some relations are already included, and do not need embedding.** List endpoints eager-load the relations they need. On `GET /api/v2/absences` the employee is always present, which is why `employee` is not in that endpoint's `_embed[]` list; on `GET /api/v2/absences/{id}` it is not loaded, so it must be requested with `_embed[]=employee`. The same relation can therefore be automatic on the list and opt-in on the detail.\n2. **A field absent from the response is usually a relation that was not embedded**, not a field that does not exist. `created_by`, `updated_by`, `created_by_user` and `updated_by_user` behave this way: they are returned only when `createdByUser` or `updatedByUser` is embedded.\n3. **Embedding a relation the endpoint does not expose has no effect.** The parameter is accepted and the response is unchanged.\n4. **`_embed` is not the only reason a field can be missing.** Sensitive and personal fields depend on the *Sensitive Information* and *Personal Information* flags on your API key, and some fields only exist for companies configured with a given payroll or time-and-attendance integration. Those cannot be obtained with `_embed`.\n\n## Token security\nWhen accessing the API using the access_token, the request will be treated as an admin. Which means your token can be used to access all of your company's data.\nKnowing that, **IT IS YOUR RESPONSABILITY** to keep the client's information and the access_token safe. FolksHR will not be responsible for unauthorized access to your company's data from a leaked token.\n\nIf you suspect that the your credentials were used by an unauthorized party, you can delete the credentials from the 'Admin' > 'API Keys Management' page. Deleted clients cannot be used to create new access tokens.\nWhen deleting a client, all access_token created by that client will be revoked as well, and become unusable.\n\n## Stability of this contract\nField names, field types and response structures documented here will not change. When a correction is\nneeded the documentation is aligned to the API's actual behaviour rather than the reverse, so an\nintegration built against this document keeps working. New fields may be added to a response, so parse\nresponses tolerantly and ignore keys you do not recognise.\n\nTwo consequences of that policy are worth calling out, because both have surprised integrators:\n\n- **A field's type is what the API really returns, not what its name suggests.** Several flags are\n returned as strings such as `\"1\"` / `\"0\"` rather than as booleans or integers. Where that is the case\n the type in this document says `string`, and it will keep saying `string`.\n- **A documented field can be absent from a response.** See the `_embed` section above: absence normally\n means the relation was not embedded, or that an API-key flag or a company integration gates the field.\n\n## Known limitations\n- **Deleting a custom field is not supported.** Custom field definitions can be listed, created and\n updated, but there is no endpoint to delete one. Deleting an individual custom *value* for an employee\n is supported, through `DELETE /api/v2/employees/{employee}/custom-fields/{customField}/custom-value/{customValue}`.\n- **`employeeNumber` is not unique and must not be used as an identifier.** It is neither constrained in\n the database nor validated for uniqueness, so two employees of the same company can share one, and it\n can be reused after an employee leaves. Key your records on the employee `id`, which is stable and\n unique, and treat `employeeNumber` as a mutable human-facing label.", "contact": { "email": "support@folkshr.com" }, "version": "2026.10.29.03" }, "paths": { "/api/v2/departments": { "get": { "tags": [ "Departments" ], "summary": "Get all departments", "description": "Retrieve the list of all accessible departments. Requires the scope.
There are two types of supervisor for a department. A supervisor can either, be define directly on the department and apply to all working sites or be define per working site.
The property `supervisor` will return the supervisor defined directly on the department while the `workingSitesSupervisors` property will return a list of supervisor for each working sites.", "operationId": "getDepartments", "parameters": [ { "name": "_embed[]", "in": "query", "description": "The related models to be included in the response. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "supervisor", "workingSitesSupervisors" ] } }, "example": "_embed[]=supervisor" }, { "name": "description", "in": "query", "description": "Returns only the departments whose description, french or english, contains the given value.", "schema": { "type": "string" }, "example": "Martketing" }, { "name": "code", "in": "query", "description": "Returns only the departments whose code, contains the given value.", "schema": { "type": "string" }, "example": "AAA" }, { "name": "week_hours", "in": "query", "description": "Returns only the departments with hours per week that is exactly the given value.", "schema": { "type": "number" }, "example": "35" }, { "name": "week_hours_gte", "in": "query", "description": "Returns only the departments with hours per week that is greater or exactly the given value.", "schema": { "type": "number" }, "example": "38" }, { "name": "week_hours_lte", "in": "query", "description": "Returns only the departments with hours per week that is less or exactly the given value.", "schema": { "type": "number" }, "example": "30" }, { "name": "remittance", "in": "query", "description": "Returns only the departments whose remittance value is exactly the given value.", "schema": { "type": "number" }, "example": "30" }, { "name": "remittance_gte", "in": "query", "description": "Returns only the departments whose remittance value is greater or exactly the given value.", "schema": { "type": "number" }, "example": "30" }, { "name": "remittance_lte", "in": "query", "description": "Returns only the departments whose remittance value is less or exactly the given value.", "schema": { "type": "number" }, "example": "30" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/DepartmentResource" } }, "meta": { "title": "meta", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MetaResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "departments:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "Departments" ], "summary": "Add a new department", "description": "Save a new department for your company. Requires the scope.", "operationId": "StoreDepartment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDepartmentRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepartmentResource" } } } } }, "security": [ { "passport": [], "partners": [ "departments:write" ] } ], "x-group": "partners" } }, "/api/v2/departments/{department_id}": { "get": { "tags": [ "Departments" ], "summary": "Get a departments with an Id", "description": "Retrieve information about a specific department. Requires the scope.
There are two types of supervisor for a department. A supervisor can either, be define directly on the department and apply to all working sites or be define per working site.
The property `supervisor` will return the supervisor defined directly on the department while the `workingSitesSupervisors` property will return a list of supervisor for each working sites.", "operationId": "showDepartment", "parameters": [ { "name": "department_id", "in": "path", "description": "ID of the department to show", "required": true, "schema": { "type": "integer" }, "example": "93" }, { "name": "_embed[]", "in": "query", "description": "The related models to be included in the response. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "supervisor", "workingSitesSupervisors" ] } }, "example": "_embed[]=supervisor" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/DepartmentResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "departments:read" ] } ], "x-group": "partners" }, "put": { "tags": [ "Departments" ], "summary": "Update an Department", "description": "Update informations regarding a department. Requires the scope.", "operationId": "updateDepartment", "parameters": [ { "name": "department_id", "in": "path", "description": "The department ID", "required": true, "schema": { "type": "integer" }, "example": "186415" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDepartmentRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/DepartmentResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized" }, "404": { "description": "Department does not exist" } }, "security": [ { "passport": [], "partners": [ "departments:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Departments" ], "summary": "Delete a department", "description": "Delete informations regarding a department. Requires the scope.", "operationId": "deleteDepartment", "parameters": [ { "name": "department_id", "in": "path", "description": "The department ID", "required": true, "schema": { "type": "integer" }, "example": "186415" } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Department not existing" }, "403": { "description": "Unauthorized" } }, "security": [ { "passport": [], "partners": [ "departments:destroy" ] } ], "x-group": "partners" } }, "/api/v2/positions": { "get": { "tags": [ "Positions" ], "summary": "Get all positions", "description": "Retrieve the list of all accessible positions. Requires the scope.", "operationId": "getPositions", "parameters": [ { "name": "description", "in": "query", "description": "Returns only the position whose description, french or english, contains the given value", "schema": { "type": "string" }, "example": "Operator" }, { "name": "code", "in": "query", "description": "Returns only the position whose code contains the given value", "schema": { "type": "string" }, "example": "OP_1" }, { "name": "weekly_work_hours", "in": "query", "description": "Returns only the position whose normal work hours is exactly the given value.", "schema": { "type": "number" }, "example": "35" }, { "name": "weekly_work_hours_gte", "in": "query", "description": "Returns only the position whose normal work hours is greater or exactly the given value.", "schema": { "type": "number" }, "example": "35" }, { "name": "weekly_work_hours_lte", "in": "query", "description": "Returns only the position whose normal work hours is less or exactly the given value.", "schema": { "type": "number" }, "example": "40" }, { "name": "remittance", "in": "query", "description": "Returns only the position whose remittance is exactly the given value", "schema": { "type": "number" }, "example": "2" }, { "name": "remittance_gte", "in": "query", "description": "Returns only the position whose remittance is greater or exactly the given value", "schema": { "type": "number" }, "example": "5" }, { "name": "remittance_lte", "in": "query", "description": "Returns only the position whose remittance is greater or exactly the given value", "schema": { "type": "number" }, "example": "3" }, { "name": "overtime_threshold", "in": "query", "description": "Returns only the position whose overtime threshold is exactly the given value", "schema": { "type": "number" }, "example": "35" }, { "name": "overtime_threshold_gte", "in": "query", "description": "Returns only the position whose overtime threshold is greater or exactly the given value", "schema": { "type": "number" }, "example": "38" }, { "name": "overtime_threshold_lte", "in": "query", "description": "Returns only the position whose overtime threshold is less or exactly the given value", "schema": { "type": "number" }, "example": "42" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/PositionResource" } }, "meta": { "title": "meta", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MetaResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "positions:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "Positions" ], "summary": "Add a new position", "description": "Save a new position. Requires the scope.", "operationId": "storePosition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionStoreRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionResource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [], "partners": [ "positions:write" ] } ], "x-group": "partners" } }, "/api/v2/positions/{position_id}": { "get": { "tags": [ "Positions" ], "summary": "Get a position with an Id", "description": "Retrieve information about a specific position. Requires the scope.", "operationId": "getPositionById", "parameters": [ { "name": "position_id", "in": "path", "description": "Filter by a position's ID", "required": true, "schema": { "type": "integer" }, "example": "93" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PositionResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "positions:read" ] } ], "x-group": "partners" }, "put": { "tags": [ "Positions" ], "summary": "Update a existing position", "description": "Update a position. Requires the scope.", "operationId": "updatePosition", "parameters": [ { "name": "position_id", "in": "path", "description": "ID of the position to update", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PositionResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [], "partners": [ "positions:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Positions" ], "summary": "Delete a specific position", "description": "Delete the specified position. Requires the scope.", "operationId": "deletePosition", "parameters": [ { "name": "position_id", "in": "path", "description": "ID of the position to delete", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [], "partners": [ "positions:destroy" ] } ], "x-group": "partners" } }, "/api/v2/working-sites": { "get": { "tags": [ "Working Sites" ], "summary": "Get all working-sites", "description": "Retrieve the list of all accessible working-sites. Requires the scope.", "operationId": "getWorkingSites", "parameters": [ { "name": "description", "in": "query", "description": "Returns only the working sites whose description, french or english, contains the given value.", "schema": { "type": "string" }, "example": "Ottawa Headquarters" }, { "name": "code", "in": "query", "description": "Returns only the working sites whose code contains the given value", "schema": { "type": "string" }, "example": "HQ_1" }, { "name": "overtime_min", "in": "query", "description": "Returns only the working sites whose minimum overtime value is exactly the given value", "schema": { "type": "number" }, "example": "2" }, { "name": "overtime_min_gte", "in": "query", "description": "Returns only the working sites whose minimum overtime value is greater or exactly the given value", "schema": { "type": "number" }, "example": "5" }, { "name": "overtime_min_lte", "in": "query", "description": "Returns only the working sites whose minimum overtime value is less or exactly the given value", "schema": { "type": "number" }, "example": "4" }, { "name": "remittance", "in": "query", "description": "Returns only the working sites whose remittance value is exactly the given value", "schema": { "type": "number" }, "example": "2" }, { "name": "remittance_gte", "in": "query", "description": "Returns only the working sites whose remittance value is greater or exactly the given value", "schema": { "type": "number" }, "example": "5" }, { "name": "remittance_lte", "in": "query", "description": "Returns only the working sites whose remittance value is less or exactly the given value", "schema": { "type": "number" }, "example": "3" }, { "name": "week_hours", "in": "query", "description": "Returns only the working sites whose normal week hours value is exactly the given value", "schema": { "type": "number" }, "example": "35" }, { "name": "week_hours_gte", "in": "query", "description": "Returns only the working sites whose normal week hours value is greater or exactly the given value", "schema": { "type": "number" }, "example": "38" }, { "name": "week_hours_lte", "in": "query", "description": "Returns only the working sites whose normal week hours value is less or exactly the given value", "schema": { "type": "number" }, "example": "30" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/WorkingSiteResource" } }, "meta": { "title": "meta", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MetaResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "workingSites:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "Working Sites" ], "summary": "Add a new working site", "description": "Save a new working site for your company. Requires the scope.", "operationId": "storeWorkingSite", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreWorkingSiteRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingSiteResource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "workingSites:write" ] } ], "x-group": "partners" } }, "/api/v2/working-sites/{working_site_id}": { "get": { "tags": [ "Working Sites" ], "summary": "Get a working-site with an Id", "description": "Retrieve information about a specific working-site. Requires the scope.", "operationId": "showWorkingSite", "parameters": [ { "name": "working_site_id", "in": "path", "description": "ID of the working-site to show", "required": true, "schema": { "type": "integer" }, "example": "93" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WorkingSiteResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "workingSites:read" ] } ], "x-group": "partners" }, "put": { "tags": [ "Working Sites" ], "summary": "Update a Working Site", "description": "Update information regarding a working site. Requires the scope.", "operationId": "updateWorkingSite", "parameters": [ { "name": "working_site_id", "in": "path", "description": "The working site ID", "required": true, "schema": { "type": "integer" }, "example": "93" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkingSiteRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingSiteResource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "workingSites:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Working Sites" ], "summary": "Delete a working site", "description": "Delete information regarding a working site. Requires the scope.", "operationId": "deleteWorkingSite", "parameters": [ { "name": "working_site_id", "in": "path", "description": "The working site ID", "required": true, "schema": { "type": "integer" }, "example": "93" } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [], "partners": [ "workingSites:destroy" ] } ], "x-group": "partners" } }, "/oauth/token": { "post": { "tags": [ "Authentication" ], "summary": "Retrieve an access token", "description": "Retrieve an access token. A client ID and client Secret are required to perform this operation.
\n You can retrieve this information in the API keys management page, in Folks, or by asking a support agent to generate one.
\n Please note that an API key 'V2' is required here.\n ", "operationId": "getAccessToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "client_id", "client_secret", "grant_type" ], "properties": { "client_id": { "title": "client_id", "description": "The client id provided by the API key management page", "type": "string", "example": "9cb42112-1c13-440d-9ec1-4ebc689bdaf1" }, "client_secret": { "title": "client_secret", "description": "The secret key associated with your client_id", "type": "string", "example": "YK6x8n6VyjbK..." }, "grant_type": { "title": "grant_type", "description": "the grant type of the request. it's always 'client_credentials'", "type": "string", "example": "client_credentials" }, "scope": { "title": "scope", "description": "A list of scopes that define what the token can do. The list is separated by spaces. Technically optional: omitting it still returns a token, but that token carries no scope and every scope-protected endpoint will then reject it, so treat it as required in practice.", "type": "string", "example": "employees:read employees:write absences:read ..." } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "token_type": { "title": "token_type", "description": "The token type to use in the Authorization header. Always `Bearer`.", "type": "string", "example": "Bearer" }, "expires_in": { "title": "expires_in", "description": "Token expiration in seconds", "type": "integer", "example": 86400 }, "access_token": { "title": "access_token", "description": "User access token", "type": "string", "example": "prettyLongAndUnreadableString.WhichHappenToBeAToken" } }, "type": "object" } } } }, "422": { "description": "Validation error. Not observed in practice: this route is handled by the OAuth server, so malformed requests surface as 400 and rejected credentials as 401." }, "400": { "description": "The request is malformed, for example an unsupported `grant_type` or a missing `client_id`. Note that the error shape of this route is the OAuth 2.0 one and differs from the rest of the API.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "unsupported_grant_type" }, "error_description": { "type": "string", "example": "The authorization grant type is not supported by the authorization server." }, "hint": { "type": "string", "example": "Check that all required parameters have been provided" }, "message": { "type": "string", "example": "The authorization grant type is not supported by the authorization server." } }, "type": "object" } } } }, "401": { "description": "Client authentication failed, for example a wrong `client_secret` or an expired key. Same OAuth 2.0 error shape as the 400, without the `hint` property.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "invalid_client" }, "error_description": { "type": "string", "example": "Client authentication failed" }, "message": { "type": "string", "example": "Client authentication failed" } }, "type": "object" } } } } }, "x-group": "partners" } }, "/api/v2/edm/documents/{entityType}/{entityId}": { "get": { "tags": [ "EDMDocuments" ], "summary": "Get a paginated list of EDM documents of a given content object", "description": "Retrieve a paginated list of EDM documents for a given content. Private documents (pay stubs, tax slips) are not shown in the folder tree, and are only returned to a request that BOTH uses an API key allowed to read sensitive information AND filters on `content_type`, e.g. `?content_type=payStub` — an allowed key alone still gets an empty list without that filter.", "operationId": "getEDMDocumentList", "parameters": [ { "name": "entityType", "in": "path", "description": "Name of the entity object", "required": true, "schema": { "type": "string" }, "example": "employee" }, { "name": "entityId", "in": "path", "description": "ID of the entity object", "required": true, "schema": { "type": "integer" }, "example": "610" }, { "name": "folder_id", "in": "query", "description": "ID of the folder", "required": false, "schema": { "type": "integer" }, "example": 3 }, { "name": "content_type", "in": "query", "description": "Filters documents by content type. Required, together with a key allowed to read sensitive information, to retrieve pay stubs and tax slips, which are not shown in the folder tree.", "required": false, "schema": { "type": "string" }, "example": "payStub" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/order" } ], "responses": { "200": { "description": "Successful operation" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "EDMDocuments" ], "summary": "Store a new EDM Document.", "description": "Store a new EDM Document. Requires the scope. An optional folder identifier may be appended to the path (/api/v2/edm/documents/{entityType}/{entityId}/{folderId}) to store the document directly in that folder.", "operationId": "storeEDMDocument", "parameters": [ { "name": "entityType", "in": "path", "description": "Name of the entity object", "required": true, "schema": { "type": "string" }, "example": "employee" }, { "name": "entityId", "in": "path", "description": "ID of the entity object", "required": true, "schema": { "type": "integer" }, "example": "610" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/order" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreEDMDocumentRequest" } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/EDMDocumentResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:write" ] } ], "x-group": "partners" } }, "/api/v2/edm/documents/{document}/content": { "get": { "tags": [ "EDMDocuments" ], "summary": "Download document", "description": "Download the document by its ID. Requires the scope. Downloading a private document (pay stub, tax slip) also requires a key allowed to read sensitive information.", "operationId": "getEDMDocument", "parameters": [ { "name": "document", "in": "path", "description": "ID of the document", "required": true, "schema": { "type": "integer" }, "example": "123" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:read" ] } ], "x-group": "partners" } }, "/api/v2/edm/documents/{entityType}/{entityId}/all": { "get": { "tags": [ "EDMDocuments" ], "summary": "Get a zip of all EDM document", "description": "Download zip file containing all EDM documents of a entity. Requires the scope.", "operationId": "getEDMDocumentOfEntity", "parameters": [ { "name": "entityType", "in": "path", "description": "Name of the entity object", "required": true, "schema": { "type": "string" }, "example": "employee" }, { "name": "entityId", "in": "path", "description": "ID of the entity object", "required": true, "schema": { "type": "integer" }, "example": "610" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/order" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentMassDownloadCodeResponseSchema" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:read" ] } ], "x-group": "partners" } }, "/api/v2/edm/documents/{document}/preview": { "get": { "tags": [ "EDMDocuments" ], "summary": "Preview document", "description": "Fetch a document id and a JWT to be used in the document preview component. Requires the scope. Downloading a private document (pay stub, tax slip) also requires a key allowed to read sensitive information.", "operationId": "previewEDMDocument", "parameters": [ { "name": "document", "in": "path", "description": "ID of the document", "required": true, "schema": { "type": "integer" }, "example": "123" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "properties": { "document_id": { "description": "The id of the document to be used in the preview.", "type": "string", "example": "7KPT9W08N41N86D3QMGK4X277W" }, "token": { "description": "The JWT token to be used for authentication in the preview.", "type": "string", "format": "jwt", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:read" ] } ], "x-group": "partners" } }, "/api/v2/edm/documents/{document}": { "delete": { "tags": [ "EDMDocuments" ], "summary": "Delete an EDM Document.", "description": "Delete an EDM Document. Requires the scope.", "operationId": "destroyEDMDocument", "parameters": [ { "name": "document", "in": "path", "description": "ID of the document", "required": true, "schema": { "type": "integer" }, "example": "123" } ], "responses": { "204": { "description": "Successful operation" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Entity not found" }, "405": { "description": "Could not delete" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:destroy" ] } ], "x-group": "partners" }, "patch": { "tags": [ "EDMDocuments" ], "summary": "Update an EDM Document.", "description": "Update an EDM Document. Requires the scope.", "operationId": "updateEDMDocument", "parameters": [ { "name": "document", "in": "path", "description": "ID of the document", "required": true, "schema": { "type": "integer" }, "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEDMDocumentRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/EDMDocumentResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:write" ] } ], "x-group": "partners" } }, "/api/v2/edm/documents/duplicate-check": { "get": { "tags": [ "EDMDocuments" ], "summary": "Duplicate check", "description": "Check if an EDMDocument already exists with the same name. Requires the scope.", "operationId": "duplicateCheckEDMDocument", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/BaseEmployeeResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:read" ] } ], "x-group": "partners" } }, "/api/v2/edm/folders/{entityType}/{entityId}": { "get": { "tags": [ "EDMFolders" ], "summary": "Get a list of EDM folders of a given entity", "description": "Retrieve a list of EDM folders for a given entity. Requires the scope.", "operationId": "getEDMFolderList", "parameters": [ { "name": "entityType", "in": "path", "description": "Name of the entity object: employee, company-employees, etc.", "required": true, "schema": { "type": "string", "enum": [ "company-employees", "employee" ] }, "example": "employee" }, { "name": "entityId", "in": "path", "description": "ID of the entity object: can be either the actual ID or the UUID (if the entity type enforces UUID). For example, for an employee entity it uses an ID, and the company-employees uses an UUID.", "required": true, "schema": { "type": "string" }, "example": "610" }, { "name": "name", "in": "query", "description": "Filter by a folder name.", "required": false, "schema": { "type": "string" }, "example": "human resources" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Successful operation" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "EDMFolders" ], "summary": "Store a new EDM Folder.", "description": "Store a new EDM Folder. Requires the scope.", "operationId": "storeEDMFolder", "parameters": [ { "name": "entityType", "in": "path", "description": "Name of the entity object: employee, company-employees, etc.", "required": true, "schema": { "type": "string", "enum": [ "company-employees", "employee" ] }, "example": "employee" }, { "name": "entityId", "in": "path", "description": "ID of the entity object: can be either the actual ID or the UUID (if the entity type enforces UUID). For example, for an employee entity it uses an ID, and the company-employees uses an UUID.", "required": true, "schema": { "type": "string" }, "example": "610" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreEDMFolderRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/EDMFolderResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Entity not found" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:folder:write" ] } ], "x-group": "partners" } }, "/api/v2/edm/folders/{folder}": { "delete": { "tags": [ "EDMFolders" ], "summary": "Delete an EDM Folder.", "description": "Delete an EDM Folder. Requires the scope.", "operationId": "destroyEDMFolder", "parameters": [ { "name": "folder", "in": "path", "description": "ID of the folder", "required": true, "schema": { "type": "integer" }, "example": "123" } ], "responses": { "204": { "description": "Successful operation" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Entity not found" }, "405": { "description": "Could not delete" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:folder:destroy" ] } ], "x-group": "partners" }, "patch": { "tags": [ "EDMFolders" ], "summary": "Update an EDM Folder.", "description": "Update an EDM Folder. Requires the scope.", "operationId": "updateEDMFolder", "parameters": [ { "name": "folder", "in": "path", "description": "ID of the folder", "required": true, "schema": { "type": "integer" }, "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEDMFolderRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/EDMFolderResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [ "*" ] }, { "partners": [ "edm:folder:write" ] } ], "x-group": "partners" } }, "/api/v2/employees/custom-fields": { "get": { "tags": [ "Custom Fields" ], "summary": "Get all custom fields", "description": "Retrieve the list of all custom fields. Requires the scope.
Custom field are used in the employee profile to define additional informations about the employees.
They can, also, be used to more granularly define some user permissions.", "operationId": "getCustomFields", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldResource" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "passport": [] }, { "partners": [ "custom-fields:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "Custom Fields" ], "summary": "Create a custom field", "description": "Create a new custom field with options. Requires the scope.", "operationId": "postCustomFields", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomFieldRequest" } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldResource" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "passport": [] }, { "partners": [ "custom-fields:write" ] } ], "x-group": "partners" } }, "/api/v2/employees/custom-fields/{custom_field_id}": { "put": { "tags": [ "Custom Fields" ], "summary": "Update a custom field", "description": "Update custom field and options. Requires the scope.", "operationId": "putCustomFields", "parameters": [ { "name": "custom_field_id", "in": "path", "description": "The Custom field ID", "required": true, "schema": { "type": "integer" }, "example": "93" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomFieldRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldResource" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "passport": [] }, { "partners": [ "custom-fields:write" ] } ], "x-group": "partners" } }, "/api/v2/employees": { "get": { "tags": [ "Employees" ], "summary": "List the employees of the company.", "description": "Retrieve a paginated list of employees. By default, only active employees are returned, but you can add the parameter inactive=1 in the URL to fetch the inactive employees as well. Requires the scope. Pagination on this endpoint differs from the other list endpoints in two ways: when neither limit nor per_page is sent, an API key receives up to 1500 employees per page instead of the usual 30, and limit=-1 is capped at 1500 rather than disabling pagination. Both parameters are capped at 1500, and per_page takes precedence when both are sent.", "operationId": "getEmployeeList", "parameters": [ { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Multiple related models can be embedded", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "province", "jobStatus" ] } }, "example": "_embed[]=country" }, { "name": "inactive", "in": "query", "description": "Whether to include inactive employees in the response. Inactive employees are omitted by default. Setting it to 1 lifts that restriction rather than replacing it, so the result is a superset of the default list: it returns the active employees as well as the inactive ones.", "required": false, "schema": { "type": "boolean" }, "example": "1" }, { "name": "code", "in": "query", "description": "Returns only the employees whose code contains the given value.", "required": false, "schema": { "type": "string" }, "example": "007" }, { "name": "first_name", "in": "query", "description": "Returns only the employees whose first name contains the given value.", "required": false, "schema": { "type": "string" }, "example": "James" }, { "name": "last_name", "in": "query", "description": "Returns only the employees whose last name contains the given value.", "required": false, "schema": { "type": "string" }, "example": "Bond" }, { "name": "full_name", "in": "query", "description": "Returns only the employees whose full name contains the given value.", "required": false, "schema": { "type": "string" }, "example": "James Bond" }, { "name": "all", "in": "query", "description": "Returns only the employees whose code, first name, last name or full name contains the given value. The match is partial and case insensitive. It also spans four related entities, so a value can match the working site, department or position name, and the union name when the company uses unions. It does not search the city.", "required": false, "schema": { "type": "string" }, "example": "james bo" }, { "name": "personal_email", "in": "query", "description": "Returns only the employees whose personal email contains the given value.", "required": false, "schema": { "type": "string" }, "example": "james.bond@gmail.com" }, { "name": "corporate_email", "in": "query", "description": "Returns only the employees whose corporate email contains the given value.", "required": false, "schema": { "type": "string" }, "example": "james.bond@folkshr.com" }, { "name": "ended_at", "in": "query", "description": "Returns only the employees whose end date is exactly the given value.
Note that you need the `inactive` filter set to true to retrieve inactive employees.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2009-12-29" }, { "name": "ended_at_gte", "in": "query", "description": "Returns only the employees whose end date is greater or exactly the given value.
Note that you need the `inactive` filter set to true to retrieve inactive employees.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2009-12-29" }, { "name": "ended_at_lte", "in": "query", "description": "Returns only the employees whose end date is less or exactly the given value.
Note that you need the `inactive` filter set to true to retrieve inactive employees.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2009-12-29" }, { "name": "returned_at", "in": "query", "description": "Returns only the employees whose return date is exactly the given value.
Note that you need the `inactive` filter set to true to retrieve inactive employees.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2009-12-29" }, { "name": "returned_at_gte", "in": "query", "description": "Returns only the employees whose return date is greater or exactly the given value.
Note that you need the `inactive` filter set to true to retrieve inactive employees.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2009-12-29" }, { "name": "returned_at_lte", "in": "query", "description": "Returns only the employees whose return date is less or exactly the given value.
Note that you need the `inactive` filter set to true to retrieve inactive employees.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2009-12-29" }, { "name": "created_at_gte", "in": "query", "description": "Returns only the employees that were created after or exactly on given date.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2024-04-01" }, { "name": "created_at_lte", "in": "query", "description": "Returns only the employees that were created before or exactly on given date.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2024-04-01" }, { "name": "updated_at_gte", "in": "query", "description": "Returns only the employees that were created or last updated after or exactly on given date.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2024-04-01" }, { "name": "updated_at_lte", "in": "query", "description": "Returns only the employees that were created or last updated before or exactly on given date.", "required": false, "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2024-04-01" }, { "name": "per_page", "in": "query", "description": "DEPRECATED. Use the `limit` parameter instead. Takes precedence over `limit` when both are sent, and is capped at 1500.", "required": false, "deprecated": true, "schema": { "type": "integer" }, "example": "50" }, { "name": "limit", "in": "query", "description": "The number of employees per pagination page. If omitted, an API key receives 1500 per page, not the 30 that the other list endpoints default to. A value above 1500 is capped at 1500, and unlike the other list endpoints `-1` does not disable pagination here: it is also rewritten to 1500.", "required": false, "schema": { "type": "integer" }, "example": "50" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/ExternalEmployeeResource" } }, "meta": { "title": "meta", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MetaResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "partners": [ "employees:read" ], "passport": [ "employees:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "Employees" ], "summary": "Add a new employee", "description": "Save a new employee for your company. Requires the scope.
", "operationId": "storeEmployee", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreEmployeeRequest" } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalEmployeeResource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "partners": [ "employees:write" ] } ], "x-group": "partners" } }, "/api/v2/employees/{employee}": { "get": { "tags": [ "Employees" ], "summary": "Show a specific employee", "description": "Return the informations regarding one employee. Requires the scope. Inactive and active employees are returned.", "operationId": "showEmployee", "parameters": [ { "name": "employee", "in": "path", "description": "The employee ID", "required": true, "schema": { "type": "integer" }, "example": 186415 }, { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Multiple related models can be embedded", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "absences", "company", "corporateProfiles", "country", "customFields", "disciplines", "emergencyLink", "externalIds", "languages", "overtimes", "province", "jobStatus", "union", "user", "secondEmergencyLink", "supervisor" ] } }, "example": "_embed[]=country" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ExternalEmployeeResource" } ] } }, "type": "object" } } } }, "404": { "description": "Employee not found" } }, "security": [ { "partners": [ "employees:read" ] } ], "x-group": "partners" }, "put": { "tags": [ "Employees" ], "summary": "Update an Employee", "description": "Update information regarding an employee. Requires the scope.", "operationId": "updateEmployee", "parameters": [ { "name": "employee", "in": "path", "description": "The ID of the employee", "required": true, "schema": { "type": "integer" }, "example": 123 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmployeeRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalEmployeeResource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "partners": [ "employees:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Employees" ], "summary": "Delete an employee", "description": "Delete information regarding an employee. Requires the .", "operationId": "deleteEmployee", "parameters": [ { "name": "employee", "in": "path", "description": "The employee ID", "required": true, "schema": { "type": "integer" }, "example": 186415 } ], "responses": { "204": { "description": "Success" } }, "security": [ { "partners": [ "employees:destroy" ] } ], "x-group": "partners" } }, "/api/v2/employees/{employee}/custom-fields/{customField}/custom-value": { "post": { "tags": [ "Employees" ], "summary": "Create or update the value of the specified custom field for an employee.", "description": "Create or update the value of a custom field for an employee.\nThis endpoint is protected by the role `custom-fields:write`.", "operationId": "3f64c2fa3439a8401f94debb4825d63a", "parameters": [ { "name": "employee", "in": "path", "description": "ID of the employee", "required": true, "schema": { "type": "integer" } }, { "name": "customField", "in": "path", "description": "ID of the custom field", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "value": { "description": "The value that will be create for the custom field. Do not use when the `value` attribute is present.", "type": "string" }, "values": { "description": "An array of values, with their actual string representation from the `value` attribute returned by the endpoint `getCustomFields`. Useful when you want to assign multiple values at once to a dropdown field. Only available when the custom field has a dropdown type. Do not use when the `value` attribute is present.", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Successful operation. The shape of `data` depends on the type of the custom field referenced in the path, not on the attribute used in the request body: a dropdown field returns an array of values (one per selected option), any other type returns a single object. Clients must handle both.", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "oneOf": [ { "title": "Dropdown custom field", "description": "Returned when the custom field is a dropdown.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValueResource" } }, { "title": "Any other custom field type", "description": "Returned for every non-dropdown custom field.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CustomFieldValueResource" } ] } ] } }, "type": "object" } } } }, "400": { "description": "Invalid date format", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid date format" } }, "type": "object" } } } } }, "security": [ { "passport": [] }, { "partners": [ "custom-fields:write" ] } ], "x-group": "partners" } }, "/api/v2/employees/{employee}/custom-fields/{customField}/custom-value/{customValue}": { "put": { "tags": [ "Employees" ], "summary": "Update the value of the specified custom field for an employee.", "description": "Update the value of a custom field for an employee.\nThis endpoint is protected by the role `custom-fields:write`.", "operationId": "e0e74f516ff662b05f1e3d0a05acfa8e", "parameters": [ { "name": "employee", "in": "path", "description": "ID of the employee", "required": true, "schema": { "type": "integer" } }, { "name": "customField", "in": "path", "description": "ID of the custom field", "required": true, "schema": { "type": "integer" } }, { "name": "customValue", "in": "path", "description": "ID of the employee - custom field mapping value to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "value": { "description": "The value to update", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful update", "content": { "application/json": { "schema": { "properties": { "employee_id": { "type": "integer" }, "custom_employee_field_id": { "type": "integer" }, "selected_value": { "type": "integer" }, "value": { "type": "string" }, "corporate_profile_id": { "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Invalid date format", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid date format" } }, "type": "object" } } } } }, "security": [ { "passport": [] }, { "partners": [ "custom-fields:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Employees" ], "summary": "Delete the value of the specified custom field for an employee.", "description": "Delete the value of a custom field for an employee.\nThis endpoint is protected by the role `custom-fields:destroy`.", "operationId": "7e4461013e09ace25bd3706b86b2eb9d", "parameters": [ { "name": "employee", "in": "path", "description": "ID of the employee", "required": true, "schema": { "type": "integer" } }, { "name": "customField", "in": "path", "description": "ID of the custom field", "required": true, "schema": { "type": "integer" } }, { "name": "customValue", "in": "path", "description": "ID of the employee - custom field mapping value to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Successful delete" }, "404": { "description": "Value not found" } }, "security": [ { "passport": [] }, { "partners": [ "custom-fields:destroy" ] } ], "x-group": "partners" } }, "/api/v2/employees/{employee}/image": { "post": { "tags": [ "Employees" ], "summary": "Add a new employee image and delete the old one if it exists.", "description": "Save a new image for the employee. Requires the scope and edit attachment permission
", "operationId": "storeEmployeeImage", "parameters": [ { "name": "employee", "in": "path", "description": "The ID of the employee", "required": true, "schema": { "type": "integer" }, "example": 123 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreEmployeeImageRequest" } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalEmployeeResource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "partners": [ "employees:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Employees" ], "summary": "Delete an employee image", "description": "Delete the image of an employee. Requires the .", "operationId": "deleteEmployeeImage", "parameters": [ { "name": "employee", "in": "path", "description": "The employee ID", "required": true, "schema": { "type": "integer" }, "example": 186415 } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "partners": [ "employees:write" ] } ], "x-group": "partners" } }, "/api/v2/employees/{employeeId}/profile-notes": { "get": { "tags": [ "Employees" ], "summary": "List employee profile notes", "description": "Paginated list of profile notes for a given employee. Requires the scope.", "operationId": "listEmployeeProfileNotes", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 42 }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "date", "title" ] }, "example": "date" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "example": "desc" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeProfileNoteResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "partners": [ "employees:read" ], "passport": [ "employees:read" ] } ], "x-group": "partners" }, "post": { "tags": [ "Employees" ], "summary": "Create a new employee profile note. Requires the scope.", "operationId": "storeEmployeeProfileNote", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EmployeeProfileNoteStoreRequest" } } } }, "responses": { "201": { "description": "Successfully created", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmployeeProfileNoteResource" } ] } }, "type": "object" } } } }, "404": { "description": "Not found" }, "403": { "description": "Forbidden" } }, "security": [ { "partners": [ "employees:write" ], "passport": [ "employees:write" ] } ], "x-group": "partners" } }, "/api/v2/employees/{employeeId}/profile-notes/{profileNoteId}": { "delete": { "tags": [ "Employees" ], "summary": "Delete an employee profile note. Requires the scope.", "operationId": "deleteEmployeeProfileNote", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "profileNoteId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Successfully deleted" }, "404": { "description": "Not found" }, "403": { "description": "Forbidden" } }, "security": [ { "partners": [ "employees:destroy" ], "passport": [ "employees:destroy" ] } ], "x-group": "partners" }, "patch": { "tags": [ "Employees" ], "summary": "Update an existing employee profile note. Requires the scope.", "operationId": "updateEmployeeProfileNote", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "profileNoteId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EmployeeProfileNoteUpdateRequest" } } } }, "responses": { "200": { "description": "Successfully updated", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmployeeProfileNoteResource" } ] } }, "type": "object" } } } }, "404": { "description": "Not found" }, "403": { "description": "Forbidden" } }, "security": [ { "partners": [ "employees:write" ], "passport": [ "employees:write" ] } ], "x-group": "partners" } }, "/api/v2/absences": { "get": { "tags": [ "Absences" ], "summary": "Get all absences", "description": "Retrieve the list of all absences. Requires the scope.", "operationId": "getAbsences", "parameters": [ { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Employees are included by default. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "reason", "updatedByUser", "createdByUser", "attachments" ] } }, "example": "_embed[]=reason" }, { "name": "inactive_employees", "in": "query", "description": "Returns absence for inactive employee when set to 1, absence for inactive employees are omitted otherwise", "schema": { "type": "boolean" }, "example": "0" }, { "name": "approved_at", "in": "query", "description": "Returns only the absences that were approved exactly on the given Date. Use with the 'pending=0' filter to return only approved absences", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "approved_at_gte", "in": "query", "description": "Returns only the absences that were approved after or on the given Date. Use with the 'pending=0' filter to return only approved absences", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "approved_at_lte", "in": "query", "description": "Returns only the absences that were approved before or on the given Date. Use with the 'pending=0' filter to return only approved absences", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "created_at", "in": "query", "description": "Returns only the absences that were created exactly on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "created_at_gte", "in": "query", "description": "Returns only the absences that were created after or on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "created_at_lte", "in": "query", "description": "Returns only the absences that were created before or on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "started_at", "in": "query", "description": "Returns only the absences that started exactly on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "started_at_gte", "in": "query", "description": "Returns only the absences that started after or on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "started_at_lte", "in": "query", "description": "Returns only the absences that started before or on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "ended_at", "in": "query", "description": "Returns only the absences that ended exactly on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-15" }, { "name": "ended_at_gte", "in": "query", "description": "Returns only the absences that ended after or on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-15" }, { "name": "ended_at_lte", "in": "query", "description": "Returns only the absences that ended before or on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-15" }, { "name": "updated_at", "in": "query", "description": "Returns only the absences whose last update date is exactly the given value", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-02-02" }, { "name": "updated_at_gte", "in": "query", "description": "Returns only the absences whose last update date is after or on the given value", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-02-02" }, { "name": "updated_at_lte", "in": "query", "description": "Returns only the absences whose last update date is before or on the given value", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-02-02" }, { "name": "duration", "in": "query", "description": "Returns only the absences whose duration is exaclty the given value", "schema": { "type": "string" }, "example": "5" }, { "name": "duration_gte", "in": "query", "description": "Returns only the absences whose duration is greater or equals to the given value", "schema": { "type": "string" }, "example": "5" }, { "name": "duration_lte", "in": "query", "description": "Returns only the absences whose duration is less or equals to the given value", "schema": { "type": "string" }, "example": "5" }, { "name": "notes", "in": "query", "description": "Returns only the absences whose note contain the given text", "schema": { "type": "string" }, "example": "accordées" }, { "name": "reason.text", "in": "query", "description": "Returns only absence whose reason contain the given text", "schema": { "type": "string" }, "example": "training" }, { "name": "sickDaysBank", "in": "query", "description": "Returns only the absences which impact the sick bank or not, depending on the value", "schema": { "type": "boolean" }, "example": "1" }, { "name": "paidAbsence", "in": "query", "description": "Returns only the absences that should be paid or not, depending on the value", "schema": { "type": "boolean" }, "example": "1" }, { "name": "pending", "in": "query", "description": "Returns only absences that are pending or not, depending on the value", "schema": { "type": "boolean" }, "example": "1" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/order" }, { "name": "sort_by", "in": "query", "description": "Sort absences by the given column", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "started_at", "ended_at" ] }, "example": "created_at" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/AbsenceResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [] }, { "partners": [ "absences:read" ] } ], "x-group": "partners" } }, "/api/v2/absences/{absence_id}": { "get": { "tags": [ "Absences" ], "summary": "Show a specific absence", "description": "Return the informations regarding one absence. Requires scope.", "operationId": "showAbsence", "parameters": [ { "name": "absence_id", "in": "path", "description": "The absence ID", "required": true, "schema": { "type": "integer" }, "example": "93" }, { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "employee", "reason", "updatedByUser", "createdByUser", "attachments" ] } }, "example": "_embed[]=reason" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AbsenceResource" } ] } }, "type": "object" } } } }, "404": { "description": "Absence not found" }, "403": { "description": "Forbidden" }, "401": { "description": "Unauthenticated" } }, "security": [ { "passport": [] }, { "partners": [ "absences:read" ] } ], "x-group": "partners" }, "put": { "tags": [ "Absences" ], "summary": "Update an Absence", "description": "Update informations regarding an absence. Requires scope.", "operationId": "updateAbsence", "parameters": [ { "name": "absence_id", "in": "path", "description": "The absence ID", "required": true, "schema": { "type": "integer" }, "example": "186415" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAbsenceRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AbsenceResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "absences:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Absences" ], "summary": "Delete a specific absence", "description": "Delete the specified absence. Requires the scope.", "operationId": "deleteAbsence", "parameters": [ { "name": "absence_id", "in": "path", "description": "ID of the absence to delete", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [] }, { "partners": [ "absences:destroy" ] } ], "x-group": "partners" } }, "/api/v2/absences/control/store": { "post": { "tags": [ "Absences" ], "summary": "Add a new absence entry", "description": "Save a new absence (entry). Requires the scope.
If the created absence span over multiple years, then the absence period will be split into multiple periods, one for each year, and multiple absences will be created.", "operationId": "storeControlAbsence", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAbsenceControlRequest" } } } }, "responses": { "200": { "description": "Successful operation. Note, if the created absences span over multiple years, then multiple absences would be created. Hense, why an array is returned.", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/AbsenceResource" } }, "link": { "title": "link", "description": "Redirect link to the absence page. Returned only by the creation endpoints. Note the key is singular.", "properties": { "redirect": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "absences:write" ] } ], "x-group": "partners" } }, "/api/v2/absences/reasons": { "get": { "tags": [ "Absences" ], "summary": "Get a list of absences reasons.", "description": "Retrieve all the absence reasons. Requires the scope. When creating a new Absence, a reason ID is needed. This route can be used to fetch which reason are accessible in the company", "operationId": "getAbsenceReasons", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/AbsenceReasonResource" } } }, "type": "object" } } }, "links": { "GetAbsenceReasonById": { "operationId": "updateAbsence", "requestBody": "$response.body#/data/0/id", "description": "The `id` value returned int eh response can be used as `absence_reason_id` when creating / updating an absence" } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [] }, { "partners": [ "absences:read" ] } ], "x-group": "partners" } }, "/api/v2/absences/{absence_id}/status": { "get": { "tags": [ "Absences Status" ], "summary": "Get the status of an absence", "description": "Return the status of the specified absence. Requires the scope.", "operationId": "showAbsenceStatus", "parameters": [ { "name": "absence_id", "in": "path", "description": "ID of the absence to show", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "The absence status. Returned as a bare JSON string, not an object.", "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "example": "accepted" } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [] }, { "partners": [ "absences:status:read" ] } ], "x-group": "partners" }, "patch": { "tags": [ "Absences Status" ], "summary": "Update the status of a absence", "description": "Update the status of the specified absence. Requires the scope.", "operationId": "updateAbsenceStatus", "parameters": [ { "name": "absence_id", "in": "path", "description": "ID of the absence to update", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "title": "status", "description": "Status of the absence", "type": "string", "example": "declined" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "absences:status:write" ] } ], "x-group": "partners" } }, "/api/v2/balances/{employee_id}/{module}": { "get": { "tags": [ "Balance" ], "summary": "Get the balance for a given employee and module", "description": "Return the balances as well as the normal work hours for a given employee and module. Requires the scope.
Depending on the module, there can be multiple balance code. Here is a table describing all possible codes
\n### Possible codes\n| module | code | description |\n| --- | --- | --- |\n| vacation | `vacation` | The balance for vacation with the type 'vacation' |\n| vacation | `personal` | The balance for all vacations with the type 'personal' |\n| absence | `absence` | The balance for the absences that does not affect the sick days bank |\n| absence | `sickLeave` | The balance for the absences that affects the sick days bank |\n| overtime | `overtime` | There is no difference in the overtime module. All overtime balance have the code 'overtime' |\n\n### Possible types\n| module | type | description |\n| --- | --- | --- |\n| vacation | `used` | The sum of all vacations approved within the year |\n| vacation | `pending` | The sum of all vacation requests that are yet to be approved within the year |\n| absence | `used` | The sum of all absences approved within the year |\n| absence | `pending` | The sum of all absence requests that are yet to be approved within the year |\n| overtime | `banked` | The sum of all overtime majorated hours that have been added to the bank. Those are hours made past the normal works hours |\n| overtime | `used` | The sum of all overtime majorated hours that have been used within the year. Those are hours taken as off time. |\n| overtime | `lastYear` | The sum of all the overtime majorated hours that were accumulated in the previous year, but not taken. |\n| overtime | `remaining` | This is the balance for the current year. It equals to the following equation: `(lastYear + banked) - used = remaining` |\n ", "operationId": "getBalance", "parameters": [ { "name": "employee_id", "in": "path", "description": "ID of the employee", "required": true, "schema": { "type": "integer" }, "example": "93" }, { "name": "module", "in": "path", "description": "Name of the module. The plural forms (absences, vacations, overtimes) are accepted as aliases of the singular values.", "required": true, "schema": { "type": "string", "enum": [ "vacation", "absence", "overtime" ] }, "example": "vacation" }, { "name": "year", "in": "query", "description": "Year of the balances", "schema": { "type": "integer" }, "example": "2019" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "balances": { "title": "balances", "description": "Array of the balances", "type": "array", "items": { "properties": { "module": { "title": "module", "description": "The module of the balance", "type": "string", "example": "vacation" }, "year": { "title": "year", "description": "The year of the balance", "type": "integer", "example": 30 }, "type": { "title": "type", "description": "The type of the balance.
This is module specific and is used to identify what type of balance is returned. See the table above for more informations.", "type": "string", "example": "used" }, "code": { "title": "code", "description": "The code of the balance. This is module specific and is used to identify different balance in the same module.
See the table above for more informations.", "type": "string", "example": "personal" }, "value": { "title": "value", "description": "The value of the balance.", "type": "number", "example": 5 } }, "type": "object" } }, "normal_work_hours": { "title": "normal_work_hours", "description": "The daily normal works hours for the employee", "type": "number", "example": "8" } }, "type": "object" } } } }, "422": { "description": "The module is invalid", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The module must be one of: absence, vacation, overtime." }, "errors": { "properties": { "module": { "type": "array", "items": { "type": "string", "example": "The module must be one of: absence, vacation, overtime." } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "passport": [] }, { "partners": [ "balances:read" ] } ], "x-group": "partners" } }, "/api/v2/overtimes": { "get": { "tags": [ "Overtimes" ], "summary": "Get all overtimes", "description": "Retrieve the list of all overtimes. Requires the scope.", "operationId": "getOvertime", "parameters": [ { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Employees are included by default. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "type", "updatedByUser", "createdByUser", "attachments" ] } }, "example": "_embed[]=type" }, { "name": "inactive_employees", "in": "query", "description": "Returns overtimes for inactive employee when set to 1, absence for inactive employees are omitted otherwise", "schema": { "type": "boolean" }, "example": "0" }, { "name": "approved_at", "in": "query", "description": "Returns only the overtimes that were approved exactly on the given Date. Use with the 'pending=0' filter to return only approved overtimes", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "approved_at_gte", "in": "query", "description": "Returns only the overtimes that were approved after or on the given Date. Use with the 'pending=0' filter to return only approved overtimes", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "approved_at_lte", "in": "query", "description": "Returns only the overtimes that were approved before or on the given Date. Use with the 'pending=0' filter to return only approved overtimes", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "created_at", "in": "query", "description": "Returns only the overtimes that were created exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "created_at_gte", "in": "query", "description": "Returns only the overtimes that were created after or exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "created_at_lte", "in": "query", "description": "Returns only the overtimes that were created before or exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "date", "in": "query", "description": "Returns only the overtimes that were ask for a specific date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "date_gte", "in": "query", "description": "Returns only the overtimes that were ask for a date after or exactly on the given value", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "date_lte", "in": "query", "description": "Returns only the overtimes that were ask for a date before or exactly on the given value", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "updated_at", "in": "query", "description": "Returns only the overtimes that were updated exactly on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-02-02" }, { "name": "updated_at_gte", "in": "query", "description": "Returns only the overtimes that were updated after or exactly on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-02-02" }, { "name": "updated_at_lte", "in": "query", "description": "Returns only the overtimes that were updated before or exactly on the given date", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-02-02" }, { "name": "hours", "in": "query", "description": "Returns only the overtimes with a duration that is exactly the given value", "schema": { "type": "string" }, "example": "5" }, { "name": "hours_gte", "in": "query", "description": "Returns only the overtimes with a duration greater or equals to the given value", "schema": { "type": "string" }, "example": "5" }, { "name": "hours_lte", "in": "query", "description": "Returns only the overtimes with a duration shorter or equals to the given value", "schema": { "type": "string" }, "example": "5" }, { "name": "notes", "in": "query", "description": "Returns only the overtimes with notes containing the given value", "schema": { "type": "string" }, "example": "accordées" }, { "name": "multiplier", "in": "query", "description": "Returns only the overtimes for a given multiplier. For example, a double overtime would have the multiplier '2', while a normal overtime would have the value'1'.", "schema": { "type": "string", "enum": [ "1", "1.5", "2" ] }, "example": "1" }, { "name": "pending", "in": "query", "description": "Returns only the overtimes that are pending, or not, depending on the given value", "schema": { "type": "boolean" }, "example": "1" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/order" }, { "name": "sort_by", "in": "query", "description": "Sort overtime by the given column", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "date", "majorated_hours", "pending" ] }, "example": "created_at" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/OvertimeResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:read" ] } ], "x-group": "partners" } }, "/api/v2/overtimes/control/store": { "post": { "tags": [ "Overtimes" ], "summary": "Add a new overtime entry", "description": "Save a new overtime (entry). Requires the scope.", "operationId": "storeControlOvertime", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OvertimeStoreControlRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OvertimeResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:write" ] } ], "x-group": "partners" } }, "/api/v2/overtimes/{overtime_id}": { "get": { "tags": [ "Overtimes" ], "summary": "Show a specific overtime", "description": "Return the informations regarding one overtime. Requires the scope.", "operationId": "showOvertime", "parameters": [ { "name": "overtime_id", "in": "path", "description": "The overtime ID", "required": true, "schema": { "type": "integer" }, "example": "93" }, { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Unlike the list endpoint, the employee is NOT included by default here and must be requested with `_embed[]=employee`. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "employee", "type", "updatedByUser", "createdByUser", "attachments" ] } }, "example": "_embed[]=type" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OvertimeResource" } ] } }, "type": "object" } } } }, "404": { "description": "Overtime not found" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:read" ] } ], "x-group": "partners" }, "put": { "tags": [ "Overtimes" ], "summary": "Update an Overtime", "description": "Update informations regarding an overtime. Requires the scope. When restricted_by_timesheet is true, only notes may change: changing employee_id, type_id, date, hours, multiplier or transfert_to_timesheet returns 422.", "operationId": "updateOvertime", "parameters": [ { "name": "overtime_id", "in": "path", "description": "The overtime ID", "required": true, "schema": { "type": "integer" }, "example": "186415" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOvertimeRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OvertimeResource" } ] } }, "type": "object" } } } }, "422": { "description": "Validation error, or the request is restricted by the timesheet" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Overtimes" ], "summary": "Delete a specific overtime", "description": "Delete the specified overtime. Requires the scope. A request the timesheet generated (restricted_by_timesheet = true) is deleted from the timesheet and cannot be deleted here.", "operationId": "deleteOvertime", "parameters": [ { "name": "overtime_id", "in": "path", "description": "ID of the overtime to delete", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden, or the request is restricted by the timesheet" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:destroy" ] } ], "x-group": "partners" } }, "/api/v2/overtimes/multipliers": { "get": { "tags": [ "Overtimes" ], "summary": "Gets the possible multipliers", "description": "Return the possible multipliers available in the current company.", "operationId": "getMultipliers", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "number", "example": "1.5" } } } } } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:read" ] } ], "x-group": "partners" } }, "/api/v2/overtimes/{overtime_id}/status": { "get": { "tags": [ "Overtimes" ], "summary": "Get the status of an overtime", "description": "Return the status of the specified overtime. Requires the scope.", "operationId": "showOvertimeStatus", "parameters": [ { "name": "overtime_id", "in": "path", "description": "ID of the overtime to show", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "The overtime status. Returned as a bare JSON string, not an object.", "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "example": "accepted" } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:status:read" ] } ], "x-group": "partners" }, "patch": { "tags": [ "Overtimes" ], "summary": "Update the status of a absence", "description": "Update the status of the specified overtime. Requires the scope.", "operationId": "updateOvertimeStatus", "parameters": [ { "name": "overtime_id", "in": "path", "description": "ID of the overtime to update", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "title": "status", "description": "Status of the overtime", "type": "string", "example": "declined" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:status:write" ] } ], "x-group": "partners" } }, "/api/v2/overtimes/types": { "get": { "tags": [ "Overtimes" ], "summary": "Get a list of overtime types", "description": "Retrieve all the overtime types", "operationId": "getOvertimeTypes", "parameters": [ { "name": "type_text", "in": "query", "description": "Returns only the overtime type whose french or english name contain a given value", "schema": { "type": "string" }, "example": "Exam Day" }, { "name": "type_code", "in": "query", "description": "Returns only overtime whose code contain a given value.", "schema": { "type": "string" }, "example": "Exam Day" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/OvertimeTypeResource" } } }, "type": "object" } } }, "links": { "createOvertime": { "operationId": "storeControlOvertime", "requestBody": "$response.body#/data/0/id", "description": "The `id` value returned in the response can be used as `type_id` when creating an overtime" }, "updateOvertime": { "operationId": "updateOvertime", "requestBody": "$response.body#/data/0/id", "description": "The `id` value returned in the response can be used as `type_id` when updating an overtime" } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [] }, { "partners": [ "overtimes:read" ] } ], "x-group": "partners" } }, "/api/v2/vacations": { "get": { "tags": [ "Vacations" ], "summary": "Get all vacations", "description": "Retrieve the list of all vacations. Requires the scope.", "operationId": "getVacations", "parameters": [ { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Employees are included by default. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "type", "updatedByUser", "createdByUser", "attachments" ] } }, "example": "_embed[]=type" }, { "name": "inactive_employees", "in": "query", "description": "Returns vacations for inactive employee when set to 1, vacations for inactive employees are omitted otherwise", "schema": { "type": "boolean" }, "example": "0" }, { "name": "started_at", "in": "query", "description": "Returns only the vacations that started exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "started_at_gte", "in": "query", "description": "Returns only the vacations that started after or exactly on the given Date.", "schema": { "type": "string" }, "example": "2020-05-01" }, { "name": "started_at_lte", "in": "query", "description": "Returns only the vacations that started before or exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-01" }, { "name": "ended_at", "in": "query", "description": "Returns only the vacations that ended exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-15" }, { "name": "ended_at_gte", "in": "query", "description": "Returns only the vacations that ended after or exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-15" }, { "name": "ended_at_lte", "in": "query", "description": "Returns only the vacations that ended before or exactly on the given Date.", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-05-15" }, { "name": "notes", "in": "query", "description": "Returns only the vacations whose notes contain the given value", "schema": { "type": "string" }, "example": "accordées" }, { "name": "pending", "in": "query", "description": "Returns only the vacations that are pending or not, depending on the value", "schema": { "type": "boolean" }, "example": "0" }, { "name": "paid", "in": "query", "description": "Returns only the vacations that are paid or not, depending on the value", "schema": { "type": "boolean" }, "example": "1" }, { "name": "duration", "in": "query", "description": "Returns only the vacations whose duration is exactly the given value.", "schema": { "type": "string" }, "example": "14" }, { "name": "duration_gte", "in": "query", "description": "Returns only the vacations whose duration is greater or exactly the given value.", "schema": { "type": "string" }, "example": "14" }, { "name": "duration_lte", "in": "query", "description": "Returns only the vacations whose duration is less or exactly the given value.", "schema": { "type": "string" }, "example": "14" }, { "name": "approved_at", "in": "query", "description": "Returns only the vacations that were approved exactly on the given Date. Use with the 'pending=0' filter to return only approved vacations", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "approved_at_gte", "in": "query", "description": "Returns only the vacations that were approved after or exactly on the given Date. Use with the 'pending=0' filter to return only approved vacations", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "name": "approved_at_lte", "in": "query", "description": "Returns only the vacations that were approved before or exactly on the given Date. Use with the 'pending=0' filter to return only approved vacations", "schema": { "type": "string", "format": "YYYY-MM-DD" }, "example": "2020-04-20" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/order" }, { "name": "sort_by", "in": "query", "description": "Sort vacations by the given column", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "started_at", "ended_at" ] }, "example": "created_at" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/VacationInDepthResource" } }, "link": { "title": "link", "description": "Redirect link to the vacation page. Returned only by the creation endpoints. Note the key is singular.", "properties": { "redirect": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:read" ] } ], "x-group": "partners" } }, "/api/v2/vacations/control/store": { "post": { "tags": [ "Vacations" ], "summary": "Add a new vacation entry", "description": "Save a new vacation (entry). Requires the scope.
If the created vacation span over multiple years, then the vacation period will be split into multiple periods, one for each year, and multiple vacations will be created.", "operationId": "storeControlVacation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreVacationControlRequest" } } } }, "responses": { "201": { "description": "Successful operation. Note, if the created vacation span over multiple years, then multiple vacations would be created. Hense, why an array is returned.", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/VacationInDepthResource" } }, "link": { "title": "link", "description": "Redirect link to the vacation page. Returned only by the creation endpoints. Note the key is singular.", "properties": { "redirect": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:write" ] } ], "x-group": "partners" } }, "/api/v2/vacations/{vacation_id}": { "get": { "tags": [ "Vacations" ], "summary": "Get a specific vacation", "description": "Return informations regarding the specified vacation. Requires the scope.", "operationId": "showVacation", "parameters": [ { "name": "_embed[]", "in": "query", "description": "The related model to be included in the response. Unlike the list endpoint, the employee is NOT included by default here and must be requested with `_embed[]=employee`. Multiple related models can be embedded", "schema": { "type": "array", "items": { "type": "string", "enum": [ "employee", "type", "updatedByUser", "createdByUser", "attachments" ] } }, "example": "_embed[]=type" }, { "name": "vacation_id", "in": "path", "description": "ID of the vacation to show", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/VacationInDepthResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:read" ] } ], "x-group": "partners" }, "put": { "tags": [ "Vacations" ], "summary": "Update a specific vacation", "description": "Update informations regarding the specified vacation. Requires the scope.", "operationId": "updateVacation", "parameters": [ { "name": "vacation_id", "in": "path", "description": "ID of the vacation to update", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmployeeVacationRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/VacationInDepthResource" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:write" ] } ], "x-group": "partners" }, "delete": { "tags": [ "Vacations" ], "summary": "Delete a specific vacation", "description": "Delete the specified vacation. Requires the scope.", "operationId": "deleteVacation", "parameters": [ { "name": "vacation_id", "in": "path", "description": "ID of the vacation to delete", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:destroy" ] } ], "x-group": "partners" } }, "/api/v2/vacations/{vacation_id}/status": { "get": { "tags": [ "Vacations Status" ], "summary": "Get the status of a vacation", "description": "Return the status of the specified vacation. Requires the scope.", "operationId": "showVacationStatus", "parameters": [ { "name": "vacation_id", "in": "path", "description": "ID of the vacation to show", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "The vacation status. Returned as a bare JSON string, not an object.", "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "example": "accepted" } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:status:read" ] } ], "x-group": "partners" }, "patch": { "tags": [ "Vacations Status" ], "summary": "Update the status of a vacation", "description": "Update the status of the specified vacation. Requires the scope.", "operationId": "updateVacationStatus", "parameters": [ { "name": "vacation_id", "in": "path", "description": "ID of the vacation to update", "required": true, "schema": { "type": "integer" }, "example": "5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "title": "status", "description": "Status of the vacation", "type": "string", "example": "declined" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:status:write" ] } ], "x-group": "partners" } }, "/api/v2/vacations/types": { "get": { "tags": [ "Vacations" ], "summary": "Get a list of vacation types", "description": "Retrieve all the vacation types. Requires the scope.", "operationId": "getVacationTypes", "parameters": [ { "name": "name", "in": "query", "description": "Returns only the vacation types whose name, either french or english, contain the given value", "schema": { "type": "string" }, "example": "personal" }, { "name": "code", "in": "query", "description": "Returns only the vacation types whose code is exactly the given value", "schema": { "type": "string" }, "example": "parental" }, { "name": "countable", "in": "query", "description": "Returns only the vacation types that are countable, or not, depending on the value.", "schema": { "type": "boolean" }, "example": "0" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "title": "data", "type": "array", "items": { "$ref": "#/components/schemas/VacationTypeResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "passport": [] }, { "partners": [ "vacations:read" ] } ], "x-group": "partners" } } }, "components": { "schemas": { "StoreDepartmentRequest": { "required": [ "description", "description_fr" ], "properties": { "code": { "title": "code", "description": "The department code. HTML markup and entities are removed; the value is stored as literal text.", "type": "string", "maxLength": 50, "example": "VNC" }, "description": { "title": "description", "description": "Name of the department in english. HTML markup and entities are removed; the value is stored as literal text.", "type": "string", "maxLength": 300, "example": "Research and development" }, "description_fr": { "title": "description_fr", "description": "Name of the department in french. HTML markup and entities are removed; the value is stored as literal text.", "type": "string", "maxLength": 300, "example": "Recherche et développement" }, "benefice_marginal": { "title": "Remittance", "description": "Remittance of the department", "type": "number", "example": "10" }, "overtime_min": { "title": "overtime_min", "description": "Min. amount before overtime for the department", "type": "number", "example": "40" }, "week_hours": { "title": "week_hours", "description": "Weekly work hours for this department", "type": "number", "example": "35" }, "super_id": { "title": "super_id", "description": "The supervisor to be assigned directly to the department", "type": "integer", "example": "10" }, "supervisors": { "title": "supervisors", "description": "A list of supervisors to be assign to this department and some working sites.", "type": "array", "items": { "properties": { "working_site_id": { "title": "Working site ID of the supervisor", "type": "integer", "example": "10" }, "supervisor_id": { "title": "Supervisor employee id", "type": "integer", "example": "30" } }, "type": "object" } } }, "type": "object" }, "UpdateDepartmentRequest": { "required": [ "description", "description_fr" ], "properties": { "code": { "title": "code", "description": "Code. HTML markup and entities are removed; the value is stored as literal text.", "type": "string", "maxLength": 50, "example": "VNC" }, "description": { "title": "description_en", "description": "Name of the department in english. HTML markup and entities are removed; the value is stored as literal text.", "type": "string", "maxLength": 300, "example": "Research and development" }, "description_fr": { "title": "description_fr", "description": "Name of the department in french. HTML markup and entities are removed; the value is stored as literal text.", "type": "string", "maxLength": 300, "example": "Recherche et développement" }, "benefice_marginal": { "title": "Remittance", "description": "Remittance of the department", "type": "number", "example": "10" }, "overtime_min": { "title": "overtime_min", "description": "Min. amount before overtime for this department", "type": "number", "example": "40" }, "week_hours": { "title": "week_hours", "description": "Weekly work hours for this department", "type": "integer", "example": "35" }, "super_id": { "title": "super_id", "description": "The supervisor to be assigned directly to the department", "type": "integer", "example": "10" }, "supervisors": { "title": "supervisors", "description": "A list of supervisors to be assign to this department and some working sites.", "type": "array", "items": { "properties": { "working_site_id": { "title": "Working site ID of the supervisor", "type": "integer", "example": "10" }, "supervisor_id": { "title": "Supervisor employee id", "type": "integer", "example": "30" } }, "type": "object" } } }, "type": "object" }, "DepartmentResource": { "properties": { "id": { "title": "id", "description": "Department's id", "type": "integer", "example": "33" }, "description_fr": { "title": "description_fr", "description": "Department's name in french", "type": "string", "example": "Opérateur" }, "description_en": { "title": "description_en", "description": "Department's name in english", "type": "string", "example": "Operator" }, "code": { "title": "code", "description": "Department's code", "type": "string", "example": "OP_1" }, "week_hours": { "title": "week_hours", "description": "The normal working hours per week for the department", "type": "integer", "example": "35" }, "benefice_marginal": { "title": "Remittance", "description": "Department's remittance value", "type": "string", "example": "35", "nullable": true }, "overtime_min": { "title": "overtime_min", "description": "Department's minimum hours for overtime", "type": "string", "example": "35" }, "supervisor": { "title": "supervisor", "description": "The supervisor directly associated to the department. Required to be embeded using `_embed[]=supervisor`", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BaseSupervisorResource" } ] }, "working_sites_supervisors": { "title": "working_sites_supervisors", "description": "A list of supervisor assigned to the department for each working site. Required to be embeded using `_embed[]=workingSitesSupervisors`", "type": "array", "items": { "$ref": "#/components/schemas/DepartmentSupervisorResource" } } }, "type": "object" }, "DepartmentSupervisorResource": { "properties": { "department_id": { "title": "department_id", "description": "The id of the assigned department", "type": "integer", "example": "10" }, "working_site_id": { "title": "working_site_id", "description": "The id of the assigned working site", "type": "integer", "example": "10" }, "supervisor_id": { "title": "supervisor_id", "description": "The id of the assigned supervisor", "type": "integer", "example": "10" }, "department": { "title": "department", "description": "The assigned department, in the same shape as DepartmentResource. Only returned when the relation is embedded. Not declared as a reference because DepartmentResource points back to this schema, and the circular reference crashes the partner document generation.", "type": "object", "nullable": true }, "supervisor": { "title": "supervisor", "description": "The assigned supervisor. Only returned when the relation is embedded.", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BaseSupervisorResource" } ] }, "working_site": { "title": "working_site", "description": "The assigned working site. Only returned when the relation is embedded.", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WorkingSiteResource" } ] } }, "type": "object" }, "PositionStoreRequest": { "properties": { "benefice_marginal": { "title": "Remittance", "description": "Remittance of the position", "type": "integer", "example": "10" }, "description": { "title": "description", "description": "Name of the position in english. Required if description_fr is empty.", "type": "string", "example": "Project manager" }, "description_fr": { "title": "description_fr", "description": "Name of the position in french. Required if description is empty.", "type": "string", "example": "Chargé de projet" }, "overtime_min": { "title": "overtime_min", "description": "Min. amount before overtime for this position", "type": "integer", "example": "40" }, "code": { "title": "code", "description": "Code", "type": "string", "example": "VNC" }, "week_hours": { "title": "week_hours", "description": "Weekly work hours for this position", "type": "integer", "example": "35" } }, "type": "object" }, "PositionUpdateRequest": { "properties": { "benefice_marginal": { "title": "Remittance", "description": "Remittance of the position", "type": "integer", "example": "10" }, "description": { "title": "description", "description": "Name of the position in english. Required if description_fr is empty.", "type": "string", "example": "Project manager" }, "description_fr": { "title": "description_fr", "description": "Name of the position in french. Required if description is empty.", "type": "string", "example": "Chargé de projet" }, "overtime_min": { "title": "overtime_min", "description": "Min. amount before overtime for this position", "type": "integer", "example": "40" }, "code": { "title": "code", "description": "Code", "type": "string", "example": "VNC" }, "week_hours": { "title": "week_hours", "description": "Weekly work hours for this position", "type": "integer", "example": "35" } }, "type": "object" }, "PositionResource": { "description": "Class PositionResource.", "properties": { "id": { "title": "id", "description": "Position's id", "type": "integer", "example": "33" }, "description_fr": { "title": "description_fr", "description": "Position's name in french", "type": "string", "example": "Opérateur" }, "description": { "title": "description", "description": "Position's name in english", "type": "string", "example": "Operator" }, "description_en": { "title": "description_en", "description": "Position's name in english. Used for backward compatibility", "type": "string", "example": "Operator" }, "code": { "title": "code", "description": "Position's code", "type": "string", "example": "OP_1" }, "overtime_min": { "title": "overtime_min", "description": "Position's overtime threshold.", "type": "integer", "example": "40" }, "benefice_marginal": { "title": "Remittance", "description": "Position's remittance", "type": "string", "example": "20", "nullable": true }, "week_hours": { "title": "week_hours", "description": "Position's weekly work hours", "type": "integer", "example": "35" } }, "type": "object" }, "UnionResource": { "title": "Union Resource", "properties": { "id": { "title": "ID", "description": "Union's ID", "type": "integer", "example": 234 }, "code": { "title": "Code", "description": "Union's code", "type": "string", "example": "ST" }, "name_en": { "title": "English Name", "description": "Union's name in english", "type": "string", "example": "Workers Union" }, "name_fr": { "title": "French Name", "description": "Union's name in french", "type": "string", "example": "Syndicat des Travailleurs" } }, "type": "object" }, "StoreWorkingSiteRequest": { "required": [ "description", "description_fr" ], "properties": { "description": { "title": "description", "description": "Name of the working site in english", "type": "string", "example": "Vancouver Offices" }, "description_fr": { "title": "description_fr", "description": "Name of the working site in french", "type": "string", "example": "Bureaux de Vancouver" }, "code": { "title": "code", "description": "Code", "type": "string", "example": "VNC" }, "benefice_marginal": { "title": "Remittance", "description": "Remittance of the working site", "type": "number", "example": "10" }, "overtime_min": { "title": "overtime_min", "description": "Min. amount before overtime for this working site", "type": "number", "example": "40" }, "week_hours": { "title": "week_hours", "description": "Weekly work hours for this working site", "type": "number", "example": "35" } }, "type": "object" }, "UpdateWorkingSiteRequest": { "required": [ "description", "description_fr" ], "properties": { "benefice_marginal": { "title": "Remittance", "description": "Remittance of the working site", "type": "integer", "example": "10" }, "description": { "title": "description", "description": "Name of the working site in english", "type": "string", "example": "Vancouver Offices" }, "description_fr": { "title": "description_fr", "description": "Name of the working site in french", "type": "string", "example": "Bureaux de Vancouver" }, "overtime_min": { "title": "overtime_min", "description": "Min. amount before overtime for this working site", "type": "integer", "example": "40" }, "code": { "title": "code", "description": "Code", "type": "string", "example": "VNC" }, "week_hours": { "title": "week_hours", "description": "Weekly work hours for this working site", "type": "integer", "example": "35" } }, "type": "object" }, "WorkingSiteResource": { "title": "Working Site Resource", "properties": { "id": { "title": "id", "description": "The working Site's id", "type": "integer", "example": 33 }, "description_fr": { "title": "description_fr", "description": "The working Site's name in french", "type": "string", "example": "Ottawa - Quartier Général" }, "description_en": { "title": "description_en", "description": "The working Site's name in english", "type": "string", "example": "Ottawa - Headquarters" }, "code": { "title": "code", "description": "The working Site's code", "type": "string", "example": "HQ_1" }, "overtime_min": { "title": "overtime_min", "description": "The number of hours before additional hours are considered overtime", "type": "string", "example": "40" }, "benefice_marginal": { "title": "Remittance", "description": "The working Site's Remittance", "type": "string", "example": "20" }, "week_hours": { "title": "week_hours", "description": "The working Site's normal weekly hours", "type": "number", "example": 35 } }, "type": "object" }, "AttachmentsResource": { "description": "Class AttachmentsResource.", "properties": { "id": { "title": "ID", "description": "ID of the Attachment", "type": "integer", "example": "624" }, "origine_name": { "title": "origine_name", "description": "Original name of the file", "type": "string", "example": "badr.pdf" }, "random_name": { "title": "random_name", "description": "A randomly generated name for the file.", "type": "string", "example": "upload_HluQB9" }, "custom_name": { "title": "custom_name", "description": "A custom name for the file, set by a user", "type": "string", "example": "wikipedia_badr.pdf" }, "byte_size": { "title": "byte_size", "description": "Size of the file, in bytes", "type": "integer", "example": "651320" }, "created_at": { "title": "created_at", "description": "Creation date of the file in our database", "type": "string", "example": "2020-05-08" }, "updated_at": { "title": "updated_at", "description": "Date of the last update of the informations file", "type": "string", "example": "2021-06-25" }, "entity_id": { "title": "entity_id", "description": "ID of the entity tied to this file", "type": "integer", "example": "575" }, "updated_by": { "$ref": "#/components/schemas/UpdaterResource" }, "file_type": { "title": "file_type", "description": "Type of the file", "type": "string", "example": "pdf" } }, "type": "object" }, "AttachmentMassDownloadCodeResponseSchema": { "properties": { "download_url": { "description": "The url to use to download the zip file.", "type": "string", "example": "https://api.folkshr.app/api/v2/files/download/someDownloadCode" }, "expires_at": { "description": "A timestamp that indicate when the url will expire.", "type": "integer", "example": "1756483336" } }, "type": "object" }, "AttachmentsSchema": { "properties": { "attachments": { "title": "attachments", "description": "Attachments related to the model. Required to be embeded using `_embed[]=attachments`", "type": "array", "items": { "$ref": "#/components/schemas/AttachmentsResource" }, "x-embedable": "attachments" } }, "type": "object" }, "BaseEmployeeResource": { "properties": { "id": { "title": "ID", "description": "Employee's ID", "type": "integer", "example": 186415 }, "first_name": { "title": "First name", "description": "Employee's first name", "type": "string", "example": "James" }, "last_name": { "title": "Last name", "description": "Employee's last name", "type": "string", "example": "Bond" }, "full_name": { "title": "Full name", "description": "Employee's full name", "type": "string", "example": "James Bond" }, "code": { "title": "Code", "description": "Employee's code", "type": "string", "example": "007" }, "corporate_email": { "title": "Corporate email", "description": "Employee's corporate email", "type": "string", "example": "james.bond@company.com", "nullable": true }, "image": { "title": "Image", "description": "Employee's profile image URL", "type": "string", "example": "https://host/path/to/the/image", "nullable": true }, "image_thumbnail": { "title": "Image thumbnail", "description": "A smaller version of the employee image (256px wide)", "type": "string", "example": "https://host/path/to/the/image_256", "nullable": true }, "started_at": { "title": "Started at", "description": "Employee's hiring date", "type": "string", "format": "date", "example": "2023-09-25", "nullable": true }, "ended_at": { "title": "Ended at", "description": "Employee's end date", "type": "string", "format": "date", "example": "2009-12-29", "nullable": true }, "returned_at": { "title": "Returned at", "description": "Employee's return date", "type": "string", "format": "date", "example": "2012-05-21", "nullable": true }, "inactivated_at": { "title": "Inactivated at", "description": "Employee's inactivation date", "type": "string", "format": "date-time", "example": "2014-01-01T00:00:00Z", "nullable": true }, "active": { "title": "Active", "description": "Employee's active/inactive status", "type": "boolean", "example": true }, "company_id": { "title": "Company ID", "description": "Employee's company ID", "type": "integer", "example": 444 }, "is_supervisor": { "title": "Is supervisor", "description": "Whether the employee is a supervisor", "type": "boolean", "example": false }, "is_current_user_has_access": { "title": "Is current user has access", "description": "Whether the current user has access to this employee. Only present when with_is_current_user_has_access is requested.", "type": "boolean", "example": true, "nullable": true }, "personal_email": { "title": "Personal email", "description": "Employee's personal email. Only present when the user passes the view-personal-info gate.", "type": "string", "example": "jamesy@hotmail.com", "nullable": true }, "position": { "title": "Position", "description": "Employee's position", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PositionResource" } ] }, "department": { "title": "Department", "description": "Employee's department", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DepartmentResource" } ] }, "working_site": { "title": "Working site", "description": "Employee's working site", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WorkingSiteResource" } ] }, "union": { "title": "Union", "description": "Employee's union", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/UnionResource" } ] }, "province": { "title": "Province", "description": "Employee's province", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProvinceResource" } ] }, "country": { "title": "Country", "description": "Employee's country", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CountryResource" } ] }, "supervisor": { "title": "Supervisor", "description": "Employee's supervisor", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BaseSupervisorResource" } ] }, "norms": { "title": "Norms", "description": "Employee's norms", "type": "array", "items": { "$ref": "#/components/schemas/V2NormResource" } } }, "type": "object" }, "CreatorResource": { "properties": { "id": { "title": "id", "description": "The actor ID", "type": "integer", "example": 10 }, "first_name": { "title": "first_name", "description": "The actor first name", "type": "string", "example": "Jon" }, "last_name": { "title": "last_name", "description": "The actor last name", "type": "string", "example": "Doe" }, "full_name": { "title": "full_name", "description": "The actor full name", "type": "string", "example": "Doe" }, "initials": { "title": "initials", "description": "The actor initials, if applicable", "type": "string", "example": "JD" }, "image": { "title": "image", "description": "The actor image, if applicable", "type": "string", "example": "https://some.url/my_avatar.jpg" }, "external": { "title": "Is external actor", "description": "Whether the actor is external ( an api partner for example) or internal ( a user of the app for example).", "type": "boolean", "example": false } }, "type": "object" }, "DepositTypeResource": { "title": "DepositTypeResource", "description": "Deposit type resource", "properties": { "id": { "title": "id", "description": "Deposit type's id", "type": "integer", "example": "9" }, "name_fr": { "title": "Name Fr", "description": "Deposit type's name in french", "type": "string", "example": "Carte de crédit" }, "name_en": { "title": "Name en", "description": "Deposit type's name in english", "type": "string", "example": "Credit card" }, "code": { "title": "Code", "description": "Deposit type's code", "type": "string", "example": "123" } }, "type": "object" }, "MetaResource": { "properties": { "per_page": { "title": "Per page", "description": "The limit of elements per page.", "type": "integer", "example": 30 }, "current_page": { "title": "Current page", "description": "The current dataset page index.", "type": "integer", "example": 2 }, "from": { "title": "From", "description": "Represents the index of the first element of the dataset for the current page.", "type": "integer", "example": 31 }, "to": { "title": "To", "description": "Represents the index of the last element of the dataset for the current page.", "type": "integer", "example": 60 }, "total": { "title": "Total", "description": "The total number of elements in the dataset.", "type": "integer", "example": 85 }, "last_page": { "title": "Last page", "description": "The last dataset page index.", "type": "integer", "example": 3 }, "links": { "title": "Links", "description": "A list of URLs for each possible pages.", "type": "array", "items": { "properties": { "url": { "title": "Url", "description": "The page URL.", "type": "string", "example": "https://api.folkshr.app/api/v2/employees?page=3" }, "label": { "title": "Label", "description": "The page label.", "type": "string", "example": "Next" }, "active": { "title": "Active", "description": "True if the URL correspond to the current page URL.", "type": "string", "example": false } }, "type": "object" } }, "path": { "title": "Path", "description": "The current enpoint URL.", "type": "string", "example": "https://api.folkshr.app/api/v2/employees" } }, "type": "object" }, "PaymentMethodResource": { "title": "PaymentMethodResource", "description": "Payment method resource", "properties": { "id": { "title": "id", "description": "Payment method's id", "type": "integer", "example": "9" }, "name_fr": { "title": "Name Fr", "description": "Payment method's name in french", "type": "string", "example": "Carte de crédit" }, "name_en": { "title": "Name en", "description": "Payment method's name in english", "type": "string", "example": "Credit card" }, "code": { "title": "Code", "description": "Payment method's code", "type": "string", "example": "123" } }, "type": "object" }, "ProfileLanguageResource": { "title": "ProfileLanguageResource", "properties": { "abbreviation": { "title": "Abbreviation", "description": "ISO 6391 Code of the language", "type": "string", "example": "fr" }, "name": { "title": "Name", "description": "The name of the language", "type": "object" } }, "type": "object" }, "UpdaterResource": { "properties": { "id": { "title": "id", "description": "The actor ID", "type": "integer", "example": 10 }, "first_name": { "title": "first_name", "description": "The actor first name", "type": "string", "example": "Jon" }, "last_name": { "title": "last_name", "description": "The actor last name", "type": "string", "example": "Doe" }, "full_name": { "title": "full_name", "description": "The actor full name", "type": "string", "example": "Doe" }, "initials": { "title": "initials", "description": "The actor initials, if applicable", "type": "string", "example": "JD" }, "image": { "title": "image", "description": "The actor image, if applicable", "type": "string", "example": "https://some.url/my_avatar.jpg" }, "external": { "title": "Is external actor", "description": "Whether the actor is external ( an api partner for example) or internal ( a user of the app for example).", "type": "boolean", "example": false } }, "type": "object" }, "BaseSupervisorResource": { "title": "BaseSupervisorResource", "properties": { "id": { "title": "ID", "description": "Employee's ID", "type": "integer", "example": 1 }, "first_name": { "title": "First Name", "description": "Employee's first name", "type": "string", "example": "John" }, "last_name": { "title": "Last Name", "description": "Employee's last name", "type": "string", "example": "Doe" }, "full_name": { "title": "Full Name", "description": "Employee's first and last name, joined by a space", "type": "string", "example": "John Doe" }, "active": { "title": "active", "description": "Whether the employee is active or not", "type": "boolean", "example": true }, "code": { "title": "Code", "description": "Employee's code", "type": "string", "example": "EMP001" }, "image": { "title": "Profile Picture", "description": "Employee's profile picture URL", "type": "string", "example": "https://example.com/profile.jpg", "nullable": true }, "image_thumbnail": { "title": "Profile Picture Thumbnail", "description": "Employee's profile picture thumbnail URL", "type": "string", "example": "https://example.com/profile_thumb.jpg", "nullable": true }, "position": { "$ref": "#/components/schemas/PositionResource" } }, "type": "object" }, "StoreEDMDocumentRequest": { "properties": { "attachments[]": { "title": "attachments", "description": "An array of EDM Document to create", "type": "array", "items": { "description": "The document file", "type": "string", "format": "binary" } }, "folder_id": { "title": "folder id", "description": "ID of the folder to save document in", "type": "integer", "example": 3, "nullable": true } }, "type": "object" }, "StoreEDMFolderRequest": { "properties": { "name": { "title": "name", "description": "Name of the folder", "type": "string", "example": "Folder1" } }, "type": "object" }, "UpdateEDMDocumentRequest": { "properties": { "name": { "title": "name", "description": "Name of the document", "type": "string", "example": "document.pdf" }, "is_shared": { "title": "is shared", "description": "If the document is shared or not", "type": "boolean", "example": true } }, "type": "object" }, "UpdateEDMFolderRequest": { "properties": { "name": { "title": "name", "description": "Name of the folder", "type": "string", "example": "folder1" } }, "type": "object" }, "EDMDocumentResource": { "description": "Class EDMDocumentResource.", "properties": { "id": { "title": "ID", "description": "ID of the EDM Document", "type": "integer", "example": "624" }, "name": { "title": "name", "description": "Name of the EDM Document", "type": "string", "example": "file.pdf" }, "is_shared": { "title": "is shared", "description": "If the EDM Document is shared or not", "type": "boolean", "example": false }, "is_manageable": { "title": "is manageable", "description": "If we can edit or delete the EDM Document", "type": "boolean", "example": false }, "content": { "title": "content", "description": "Content of the EDM Document", "properties": { "type": { "title": "type", "description": "Type of the EDM Document content", "type": "string", "example": "App\\Domains\\ElectronicDocumentManagement\\Models\\EDMDocumentAttachmentContent" }, "id": { "title": "ID", "description": "ID of the EDM Document content", "type": "integer", "example": "123" }, "data": { "title": "Data", "description": "Data of the EDM Document content" } }, "type": "object" }, "created_by": { "$ref": "#/components/schemas/CreatorResource" }, "updated_by": { "$ref": "#/components/schemas/UpdaterResource" }, "created_at": { "title": "created_at", "description": "Creation date of the EDM Document in our database", "type": "string", "example": "2020-05-08" }, "updated_at": { "title": "updated_at", "description": "Date of the last update of the EDM Document", "type": "string", "example": "2021-06-25" } }, "type": "object" }, "EDMFolderResource": { "description": "Class EDMFolderResource.", "properties": { "id": { "title": "ID", "description": "ID of the EDM Folder", "type": "integer", "example": "624" }, "name": { "title": "name", "description": "Name of the EDM Folder", "type": "string", "example": "file.pdf" }, "documents": { "title": "documents", "description": "Documents in the EDM Folder", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/EDMDocumentResource" } ] } }, "created_at": { "title": "created_at", "description": "Creation date of the EDM Folder in our database", "type": "string", "example": "2020-05-08" }, "updated_at": { "title": "updated_at", "description": "Date of the last update of the EDM Folder", "type": "string", "example": "2021-06-25" } }, "type": "object" }, "EmployeeProfileNoteStoreRequest": { "title": "EmployeeProfileNoteStoreRequest", "required": [ "title", "notes" ], "properties": { "date": { "title": "date", "description": "The profile note date.", "type": "string", "format": "date", "example": "2025-07-18" }, "title": { "title": "title", "description": "The profile note title.", "type": "string", "example": "Lorem ipsum" }, "notes": { "title": "notes", "description": "The profile note content.", "type": "string", "example": "Lorem ipsum dolor sit amet, consectetur adipiscing elit." }, "attachments": { "title": "attachments", "description": "Attachments related to the profile note.", "type": "array", "items": { "$ref": "#" } } }, "type": "object" }, "EmployeeProfileNoteUpdateRequest": { "title": "EmployeeProfileNoteUpdateRequest", "properties": { "date": { "title": "date", "description": "The profile note date.", "type": "string", "format": "date", "example": "2025-07-18" }, "title": { "title": "title", "description": "The profile note title.", "type": "string", "example": "Lorem ipsum" }, "notes": { "title": "notes", "description": "The profile note content.", "type": "string", "example": "Lorem ipsum dolor sit amet, consectetur adipiscing elit." }, "attachments": { "title": "attachments", "description": "Attachments related to the profile note.", "type": "array", "items": { "$ref": "#" } } }, "type": "object" }, "StoreCustomFieldRequest": { "properties": { "employee_id": { "title": "employee_id", "description": "The internal reference to the associated employee.
Use this only if you want to apply the custom field to a single employee only.", "type": "string", "example": "45682" }, "corporate_profile_id": { "title": "corporate_profile_id", "description": "The internal reference to the associated corporate profile.
Use this only if you want to apply the custom field to a single corporate profile only. ", "type": "string", "example": "1243457" }, "name_en": { "title": "Name English", "description": "Custom field name in English", "type": "string", "example": "Number of Children" }, "name_fr": { "title": "Name French", "description": "Custom field name in French", "type": "string", "example": "Nombre d'enfants" }, "category": { "title": "Category", "description": "Category of the custom field", "type": "string", "enum": [ "corporative", "personal", "remuneration" ], "example": "corporative" }, "type": { "title": "Type", "description": "Type of the custom field", "type": "string", "enum": [ "dropdown", "text", "date" ], "example": "dropdown" }, "is_salary": { "title": "Is salary", "description": "Wether the field is salary", "type": "boolean", "example": "false" }, "used_in_headcount": { "title": "Is used in headcount", "description": "Wether the field is used for headcount", "type": "boolean", "example": "false" }, "used_in_nethris_integration": { "title": "Is used in nethris integration", "description": "Wether the field is used for pay system integration", "type": "boolean", "example": "false" }, "is_used_as_user_role": { "title": "Is used as user role", "description": "Is the custom field used to give access to some employees.", "type": "boolean", "example": "false" }, "options": { "title": "options", "description": "List of options for the custom field, if the type is 'dropdown'", "type": "array", "items": { "properties": { "code": { "title": "code", "description": "The code of the custom field option", "type": "string", "example": "singleChild" }, "value": { "title": "value", "description": "The value of the custom field option", "type": "string", "example": "1" } }, "type": "object" } } }, "type": "object" }, "StoreEmployeeImageRequest": { "title": "StoreEmployeeImageRequest", "required": [ "file" ], "properties": { "file": { "title": "file", "description": "An image file to use as employee image", "type": "string", "format": "binary" } }, "type": "object" }, "StoreEmployeeRequest": { "description": "Validation runs on the internal column names, not on the field names documented here, so the\nkeys inside a 422 `errors` object are the internal ones. The request body itself is unchanged:\nsend the documented names. Use this table to map an error key back to the field you sent.\n\n| Field you send | Key returned in 422 errors |\n|---|---|\n| `firstName` | `first_name` |\n| `lastName` | `last_name` |\n| `employeeNumber` | `code` |\n| `startDate` | `started_at` |\n| `workingSiteCode` | `working_site_code` |\n| `workingSiteId` | `working_site_id` |\n| `departmentCode` | `department_code` |\n| `departmentId` | `department_id` |\n| `positionCode` | `position_code` |\n| `positionId` | `position_id` |\n| `countryCode` | `country_code` |\n| `provinceCode` | `province_code` |\n| `employmentProvinceCode` | `employment_province_code` |\n| `companyNumber` | `company_number` |\n| `gender` | `sex` |\n| `birthDate` | `birthday` |\n| `addressLine1` | `address` |\n| `addressLine2` | `address_line2` |\n| `addressLine3` | `address_line3` |\n| `postalCode` | `zip_code` |\n| `phoneNumber` | `phone` |\n| `secondaryPhoneNumber` | `second_phone` |\n| `personalEmail` | `personal_email` |\n| `socialInsuranceNumber` | `social_insurance_number` |\n| `comments` | `notes` |\n| `emergencyContactName` | `emergency_contact` |\n| `emergencyContactLinkCode` | `emergency_link` |\n| `emergencyContactPhone` | `emergency_phone` |\n| `secondEmergencyContactName` | `second_emergency_contact` |\n| `secondEmergencyContactPhone` | `second_emergency_phone` |\n| `secondEmergencyContactLinkCode` | `second_emergency_link` |\n| `jobTypeCode` | `employee_status_type_id` |\n| `recognitionDate` | `recognized_at` |\n| `endDate` | `ended_at` |\n| `endDateType` | `ended_at_type` |\n| `layoffType` | `layoff_type` |\n| `returnDate` | `returned_at` |\n| `corporateEmail` | `corporate_email` |\n| `corporatePhoneNumber` | `work_phone` |\n| `corporatePhoneNumberExtension` | `work_phone_ext` |\n| `salaryType` | `salary_type` |\n| `annualSalary` | `annual_salary` |\n| `salaryStep` | `salary_step_id` |\n| `hoursPerPay` | `hours_per_pay` |\n", "required": [ "firstName", "lastName", "employeeNumber", "startDate" ], "properties": { "firstName": { "title": "First name", "description": "First name of the employee", "type": "string", "maximum": 100, "example": "Folksy" }, "lastName": { "title": "Last name", "description": "Last name of the employee", "type": "string", "maximum": 100, "example": "Folks" }, "employeeNumber": { "title": "employee number", "description": "Unique identifier in the company.", "type": "string", "maximum": 50, "example": "123 234 345222" }, "startDate": { "title": "start date", "description": "The start date of the employee, in the company", "type": "string", "format": "YYYY-MM-DD", "example": "2020-01-01" }, "endDate": { "title": "end date", "description": "Populate this field to make an employee inactive. The employee will be considered active is this field is blank or not sent.", "type": "string", "format": "YYYY-MM-DD", "example": "2024-01-01" }, "returnDate": { "title": "return date", "description": "Populate this field to make an employee active. This field have priority over the endDate field, if populated endDate will be considered blank.", "type": "string", "format": "YYYY-MM-DD", "example": "2024-06-01" }, "endDateType": { "title": "end date type", "description": "Allowed values: 'permanent', 'temporary'", "type": "string", "enum": [ "permanent", "temporary" ] }, "layoffType": { "title": "layoff type", "description": "This field is only useful when endDateType is set to 'temporary'. It will be considered blank if endDate is blank, endDateType value is 'permanent' or returnDate is not blank. Valid values are: 'layoff', 'parental', 'disability', 'work_accident'.", "type": "string", "enum": [ "layoff", "parental", "disability", "work_accident" ] }, "workingSiteCode": { "title": "working site code", "description": "The code of a working site to which the employee will be assigned.
You can get the list of all working sites using the [Working sites Index request](#/Working Sites/getWorkingSites).", "type": "string", "example": "123-A" }, "departmentCode": { "title": "department code", "description": "The code of a department to which the employee will be assigned.
You can get the list of all departments using the [Departments Index Request](#/Departments/getDepartments).", "type": "string", "example": "dept-a" }, "positionCode": { "title": "position code", "description": "The code of a position to which the employee will be assigned.
You can get the list of all positions using the [Position Index Request](#/Positions/getPositions).", "type": "string", "example": "104-4" }, "workingSiteId": { "title": "working site id", "description": "The ID of a working site to which the employee will be assigned.
You can get the list of all working sites using the [Working sites Index request](#/Working Sites/getWorkingSites).", "type": "integer", "example": 123 }, "departmentId": { "title": "department id", "description": "The ID of a department to which the employee will be assigned.
You can get the list of all departments using the [Departments Index Request](#/Departments/getDepartments).", "type": "integer", "example": 456 }, "positionId": { "title": "position id", "description": "The ID of a position to which the employee will be assigned.
You can get the list of all positions using the [Position Index Request](#/Positions/getPositions).", "type": "integer", "example": 789 }, "city": { "title": "city", "description": "City of residence.", "type": "string", "example": "Quebec City" }, "addressLine1": { "title": "adress line 1", "description": "First line of employee's address", "type": "string", "example": "123 Fake street" }, "addressLine2": { "title": "adress line 2", "description": "Second line of employee's address", "type": "string", "example": "Apartment 101" }, "addressLine3": { "title": "adress line 3", "description": "Third line of employee's address", "type": "string", "example": "Quebec City Canada, A1A 1A1" }, "postalCode": { "title": "postal code", "description": "Postal code / Zip code", "type": "string", "example": "A1A 1A1" }, "countryCode": { "title": "country code", "description": "ISO 3166-1 alpha-2 country code. See [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) for a list of valid ISO 3166-1 alpha-2 codes.", "type": "string", "example": "CA" }, "provinceCode": { "title": "province code", "description": "ISO 3166-2 subdivision code. See [here](https://en.wikipedia.org/wiki/ISO_3166-2) for a list of valid ISO 3166-2 codes.", "type": "string", "example": "QC" }, "employmentProvinceCode": { "title": "employment province code", "description": "ISO 3166-2 subdivision code for the employment province. Only the provinces of Canada are accepted. See [here](https://en.wikipedia.org/wiki/ISO_3166-2) for a list of valid ISO 3166-2 codes.", "type": "string", "example": "QC" }, "phoneNumber": { "title": "phone number", "description": "Employee's personal phone number.", "type": "string", "maximum": 100, "example": "100 200 3000" }, "secondaryPhoneNumber": { "title": "second phone number", "description": "Employee's personal backup phone number. Eg. land line.", "type": "string", "maximum": 100, "example": "100 200 3001" }, "companyNumber": { "title": "company number", "description": "Pay system number. This field should be used only if your company is configured with a pay system. If so, it will be used with the employeeNumber field as the unique identifier.", "type": "string", "example": "45PN" }, "personalEmail": { "title": "personal email", "description": "Employee's personal email address.", "type": "string", "maximum": 100, "example": "example@domain.com" }, "corporateEmail": { "title": "work email", "description": "Employee's professional email address.", "type": "string", "maximum": 100, "example": "example@domain.com" }, "corporatePhoneNumber": { "title": "work phone number", "description": "Employee's professional phone number.", "type": "string", "maximum": 50, "example": "200 200 3001" }, "corporatePhoneNumberExtension": { "title": "work phone number extension", "description": "Employee's professional phone number extension.", "type": "string", "maximum": 50, "example": "9" }, "socialInsuranceNumber": { "title": "social insurance number", "description": "Employee's social insurance number.", "type": "string", "example": "123 456 798" }, "emergencyContactName": { "title": "emergency contact's name", "description": "Employee's first emergency contact's name.", "type": "string", "maximum": 100, "example": "Bart Simpson" }, "emergencyContactLinkCode": { "title": "emergency contact's link code", "description": "Relationship of the first emergency contact. See the table below for the ID to use for each type of relationship.
\n Spousal: `1`
\n Brother: `2`
\n Sister: `3`
\n Father: `4`
\n Mother: `5`
\n Son: `6`
\n Daughter: `7`
\n Friend: `8`
\n Other: `9`
\n ", "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ] }, "emergencyContactPhone": { "title": "emergency contact's phone number", "description": "Employee's emergency contact's phone number", "type": "string", "maximum": 100, "example": "100 200 3002" }, "secondEmergencyContactName": { "title": "second emergency contact's name", "description": "Employee's second emergency contact's name.", "type": "string", "maximum": 100, "example": "Lisa Simpson" }, "secondEmergencyContactLinkCode": { "title": "emergency contact's link code", "description": "Relationship of the second emergency contact.See the table below for the ID to use for each type of relationship.
\n Spousal: `1`
\n Brother: `2`
\n Sister: `3`
\n Father: `4`
\n Mother: `5`
\n Son: `6`
\n Daughter: `7`
\n Friend: `8`
\n Other: `9`
\n ", "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ] }, "secondEmergencyContactPhone": { "title": "second emergency contact's phone number", "description": "Employee's second emergency contact's phone number", "type": "string", "maximum": 100, "example": "100 200 3003" }, "gender": { "title": "gender", "description": "Allowed values: 'F', 'M'", "type": "string", "enum": [ "F", "M" ] }, "jobTypeCode": { "title": "job type code", "description": "The Job status of the Employee. See below for a list of the possible values:
\n Occasional: `1`
\n Part-time: `2`
\n Full-time: `3`
\n Seasonal: `4`
\n Contractual: `5`
\n Internship: `6`
\n Contractor: `7`
\n Temporary: `8`
\n On call/Full time: `9`
\n Early Retirement: `10`
\n Probation: `11`
\n Supernumerary: `12`
\n Contractual - Full-time: `13`
\n Contractual - Part-time: `14`
\n Maternity / Parental Leave: `15`
\n Disability: `16`
\n Casual Relief: `17`
\n Student: `18`
\n External Consultant: `19`
\n CDI full-time: `20`
\n CDI part-time: `21`
\n CDD full-time: `22`
\n CDD part-time: `23`
\n Temporary Foreign Worker: `24`
\n ", "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24 ] }, "languages": { "title": "languages", "description": "List of languages (ISO 639-1 codes) spoken by the employee. See [here](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for a list of valid ISO 639-1 codes.", "type": "array", "items": { "type": "string", "example": "fr" } }, "recognitionDate": { "title": "Recognition date", "description": "The Recognition date of the employee", "type": "string", "format": "YYYY-MM-DD", "example": "2020-01-01" }, "salaryType": { "title": "Salary type", "description": "Employee salary type. Allowed values: 'hourlyRate', 'perPay'", "type": "string", "enum": [ "hourlyRate", "perPay" ], "example": "hourlyRate" }, "hoursPerPay": { "title": "Hours per pay", "description": "How many hours is there per pay, for the employee", "type": "number", "example": "80" }, "birthDate": { "title": "Birthday", "description": "The employee's birth date", "type": "string", "format": "YYYY-MM-DD", "example": "1999-01-01" }, "salary": { "title": "salary", "description": "Employee's salary", "type": "number", "example": "55" }, "annualSalary": { "title": "annual salary", "description": "Employee's annual salary", "type": "number", "example": "110000" }, "salaryStep": { "title": "salary step", "description": "Employee's salary step", "type": "number", "example": "4" }, "externalIds": { "title": "externalIds", "description": "Employee's external IDs from third party integrations. Only available when the company is configured with a supported integration.", "type": "object", "additionalProperties": { "type": "string", "example": "6377f2a3-4e7c-4a05-9097-5b6baf5e3c82" } }, "payroll": { "title": "Payroll", "description": "Payroll system information.", "properties": { "clientNumber": { "description": "The number of the payroll system of the employee. Note, this is not the ID of the system, but the number of the system.", "type": "string", "example": "PM123456" }, "payGroup": { "description": "The pay group of the employee. Note, this is not the ID of the pay group, but the number of the Pay Group.", "type": "string", "example": "PG005678" }, "businessNumber": { "description": "The Business Number of the employee. Note, this is not the ID of the business number, but the number of the business number. This value is only shown used then the company has the Payworks Payroll.", "type": "string", "example": "98765" }, "bankAccount": { "description": "The bank account information of the employee.", "properties": { "account": { "description": "The bank account number.", "type": "string", "example": "12345" }, "transit": { "description": "The bank account transit number.", "type": "string", "example": "345" }, "institution": { "description": "The bank account institution number.", "type": "string", "example": "98765" } }, "type": "object" } }, "type": "object" }, "comments": { "title": "comments", "description": "Employee's comments", "type": "string", "maxLength": 1000, "example": "His name is bond. James bond." } }, "type": "object" }, "UpdateCustomFieldRequest": { "properties": { "name_en": { "title": "Name English", "description": "Custom field name in English", "type": "string", "example": "Number of Children" }, "name_fr": { "title": "Name French", "description": "Custom field name in French", "type": "string", "example": "Nombre d'enfants" }, "category": { "title": "Category", "description": "Category of the custom field", "type": "string", "enum": [ "corporative", "personal", "remuneration" ], "example": "corporative" }, "type": { "title": "Type", "description": "Type of the custom field", "type": "string", "enum": [ "dropdown", "text", "date" ], "example": "dropdown" }, "is_salary": { "title": "Is salary", "description": "Wether the field is salary", "type": "boolean", "example": "true" }, "used_in_headcount": { "title": "Is used in headcount", "description": "Wether the field is used for headcount", "type": "boolean", "example": "true" }, "used_in_nethris_integration": { "title": "Is used in nethris integration", "description": "Wether the field is used for pay system integration", "type": "boolean", "example": "true" }, "is_used_as_user_role": { "title": "Is used as user role", "description": "Is the custom field used to give access to some employees.", "type": "boolean", "example": "false" }, "options": { "title": "options", "description": "List of options for the custom field, if the type is 'dropdown'", "type": "array", "items": { "properties": { "code": { "title": "code", "description": "The code of the custom field option", "type": "string", "example": "singleChild" }, "value": { "title": "value", "description": "The value of the custom field option", "type": "string", "example": "1" } }, "type": "object" } } }, "type": "object" }, "UpdateEmployeeRequest": { "description": "Validation runs on the internal column names, not on the field names documented here, so the\nkeys inside a 422 `errors` object are the internal ones. The request body itself is unchanged:\nsend the documented names. Use this table to map an error key back to the field you sent.\n\n| Field you send | Key returned in 422 errors |\n|---|---|\n| `firstName` | `first_name` |\n| `lastName` | `last_name` |\n| `employeeNumber` | `code` |\n| `startDate` | `started_at` |\n| `workingSiteCode` | `working_site_code` |\n| `workingSiteId` | `working_site_id` |\n| `departmentCode` | `department_code` |\n| `departmentId` | `department_id` |\n| `positionCode` | `position_code` |\n| `positionId` | `position_id` |\n| `countryCode` | `country_code` |\n| `provinceCode` | `province_code` |\n| `employmentProvinceCode` | `employment_province_code` |\n| `companyNumber` | `company_number` |\n| `gender` | `sex` |\n| `birthDate` | `birthday` |\n| `addressLine1` | `address` |\n| `addressLine2` | `address_line2` |\n| `addressLine3` | `address_line3` |\n| `postalCode` | `zip_code` |\n| `phoneNumber` | `phone` |\n| `secondaryPhoneNumber` | `second_phone` |\n| `personalEmail` | `personal_email` |\n| `socialInsuranceNumber` | `social_insurance_number` |\n| `comments` | `notes` |\n| `emergencyContactName` | `emergency_contact` |\n| `emergencyContactLinkCode` | `emergency_link` |\n| `emergencyContactPhone` | `emergency_phone` |\n| `secondEmergencyContactName` | `second_emergency_contact` |\n| `secondEmergencyContactPhone` | `second_emergency_phone` |\n| `secondEmergencyContactLinkCode` | `second_emergency_link` |\n| `jobTypeCode` | `employee_status_type_id` |\n| `recognitionDate` | `recognized_at` |\n| `endDate` | `ended_at` |\n| `endDateType` | `ended_at_type` |\n| `layoffType` | `layoff_type` |\n| `returnDate` | `returned_at` |\n| `corporateEmail` | `corporate_email` |\n| `corporatePhoneNumber` | `work_phone` |\n| `corporatePhoneNumberExtension` | `work_phone_ext` |\n| `salaryType` | `salary_type` |\n| `annualSalary` | `annual_salary` |\n| `salaryStep` | `salary_step_id` |\n| `hoursPerPay` | `hours_per_pay` |\n\nOn this endpoint thirteen of the fields above are mapped only when the API key has the Personal\nInformation parameter: `gender`, `birthDate`, `addressLine1`, `postalCode`, `phoneNumber`,\n`secondaryPhoneNumber`, `personalEmail`, `emergencyContactName`, `emergencyContactLinkCode`,\n`emergencyContactPhone`, `secondEmergencyContactName`, `secondEmergencyContactPhone` and\n`secondEmergencyContactLinkCode`. Without that parameter they are ignored rather than rejected, so the\nrequest still succeeds and those values are silently not applied. Note `addressLine2` and\n`addressLine3` are not gated this way and are always applied.\n", "required": [ "firstName", "lastName", "employeeNumber", "startDate" ], "properties": { "firstName": { "title": "First name", "description": "First name of the employee", "type": "string", "maximum": 100, "example": "Folksy" }, "lastName": { "title": "Last name", "description": "Last name of the employee", "type": "string", "maximum": 100, "example": "Folks" }, "startDate": { "title": "start date", "description": "The start date of the employee, in the company", "type": "string", "format": "YYYY-MM-DD", "example": "2020-01-01" }, "employeeNumber": { "title": "employee number", "description": "Unique identifier in the company.", "type": "string", "maximum": 50, "example": "123 234 345222" }, "endDate": { "title": "end date", "description": "yyyy-mm-dd format. Populate this field to make an employee inactive. The employee will be considered active is this field is blank or not sent.", "type": "string", "format": "YYYY-MM-DD", "example": "2024-01-01" }, "returnDate": { "title": "return date", "description": "yyyy-mm-dd format. Populate this field to make an employee active. This field have priority over the endDate field, if populated endDate will be considered blank.", "type": "string", "format": "YYYY-MM-DD", "example": "2024-06-01" }, "endDateType": { "title": "end date type", "description": "Allowed values: 'permanent', 'temporary'", "type": "string", "enum": [ "permanent", "temporary" ] }, "layoffType": { "title": "layoff type", "description": "This field is only useful when endDateType is set to 'temporary'. It will be considered blank if endDate is blank, endDateType value is 'permanent' or returnDate is not blank. Valid values are: 'layoff', 'parental', 'disability', 'work_accident'.", "type": "string", "enum": [ "layoff", "parental", "disability", "work_accident" ] }, "workingSiteCode": { "title": "working site code", "description": "The code of a working site to which the employee will be assigned.
You can get the list of all working sites using the [Working sites Index request](#/Working Sites/getWorkingSites).", "type": "string", "example": "123-A" }, "departmentCode": { "title": "department code", "description": "The code of a department to which the employee will be assigned.
You can get the list of all departments using the [Departments Index Request](#/Departments/getDepartments).", "type": "string", "example": "dept-a" }, "positionCode": { "title": "position code", "description": "The code of a position to which the employee will be assigned.
You can get the list of all positions using the [Position Index Request](#/Positions/getPositions).", "type": "string", "example": "104-4" }, "workingSiteId": { "title": "working site id", "description": "The ID of a working site to which the employee will be assigned.
You can get the list of all working sites using the [Working sites Index request](#/Working Sites/getWorkingSites).", "type": "integer", "example": 123 }, "departmentId": { "title": "department id", "description": "The ID of a department to which the employee will be assigned.
You can get the list of all departments using the [Departments Index Request](#/Departments/getDepartments).", "type": "integer", "example": 456 }, "positionId": { "title": "position id", "description": "The ID of a position to which the employee will be assigned.
You can get the list of all positions using the [Position Index Request](#/Positions/getPositions).", "type": "integer", "example": 789 }, "city": { "title": "city", "description": "City of residence.", "type": "string", "example": "Quebec City" }, "addressLine1": { "title": "adress line 1", "description": "First line of employee's address", "type": "string", "example": "123 Fake street" }, "addressLine2": { "title": "adress line 2", "description": "Second line of employee's address", "type": "string", "example": "Apartment 101" }, "addressLine3": { "title": "adress line 3", "description": "Third line of employee's address", "type": "string", "example": "Quebec City Canada, A1A 1A1" }, "postalCode": { "title": "postal code", "description": "Postal code / Zip code", "type": "string", "example": "A1A 1A1" }, "countryCode": { "title": "country code", "description": "ISO 3166-1 alpha-2 country code. See [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) for a list of valid ISO 3166-1 alpha-2 codes.", "type": "string", "example": "CA" }, "provinceCode": { "title": "province code", "description": "ISO 3166-2 subdivision code. See [here](https://en.wikipedia.org/wiki/ISO_3166-2) for a list of valid ISO 3166-2 codes.", "type": "string", "example": "QC" }, "employmentProvinceCode": { "title": "employment province code", "description": "ISO 3166-2 subdivision code for the employment province. Only the provinces of Canada are accepted. See [here](https://en.wikipedia.org/wiki/ISO_3166-2) for a list of valid ISO 3166-2 codes.", "type": "string", "example": "QC" }, "phoneNumber": { "title": "phone number", "description": "Employee's personal phone number.", "type": "string", "maximum": 100, "example": "100 200 3000" }, "secondaryPhoneNumber": { "title": "second phone number", "description": "Employee's personal backup phone number. Eg. land line.", "type": "string", "maximum": 100, "example": "100 200 3001" }, "companyNumber": { "title": "company number", "description": "Pay system number. This field should be used only if your company is configured with a pay system. If so, it will be used with the employeeNumber field as the unique identifier.", "type": "string", "example": "45PN" }, "personalEmail": { "title": "personal email", "description": "Employee's personal email address.", "type": "string", "maximum": 100, "example": "example@domain.com" }, "corporateEmail": { "title": "work email", "description": "Employee's professional email address.", "type": "string", "maximum": 100, "example": "example@domain.com" }, "corporatePhoneNumber": { "title": "work phone number", "description": "Employee's professional phone number.", "type": "string", "maximum": 50, "example": "200 200 3001" }, "corporatePhoneNumberExtension": { "title": "work phone number extension", "description": "Employee's professional phone number extension.", "type": "string", "maximum": 50, "example": "9" }, "socialInsuranceNumber": { "title": "social insurance number", "description": "Employee's social insurance number.", "type": "string", "example": "123 456 798" }, "emergencyContactName": { "title": "emergency contact's name", "description": "Employee's first emergency contact's name.", "type": "string", "maximum": 100, "example": "Bart Simpson" }, "emergencyContactLinkCode": { "title": "emergency contact's link code", "description": "Relationship of the first emergency contact. See the table below for the ID to use for each type of relationship.
\n Spousal: `1`
\n Brother: `2`
\n Sister: `3`
\n Father: `4`
\n Mother: `5`
\n Son: `6`
\n Daughter: `7`
\n Friend: `8`
\n Other: `9`
\n Send `null` explicitly to clear the relationship; omitting the field leaves it unchanged.\n ", "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "example": 6, "nullable": true }, "emergencyContactPhone": { "title": "emergency contact's phone number", "description": "Employee's emergency contact's phone number", "type": "string", "maximum": 100, "example": "100 200 3002" }, "secondEmergencyContactName": { "title": "second emergency contact's name", "description": "Employee's second emergency contact's name.", "type": "string", "maximum": 100, "example": "Lisa Simpson" }, "secondEmergencyContactLinkCode": { "title": "emergency contact's link code", "description": "Relationship of the second emergency contact.See the table below for the ID to use for each type of relationship.
\n Spousal: `1`
\n Brother: `2`
\n Sister: `3`
\n Father: `4`
\n Mother: `5`
\n Son: `6`
\n Daughter: `7`
\n Friend: `8`
\n Other: `9`
\n Send `null` explicitly to clear the relationship; omitting the field leaves it unchanged.\n ", "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "example": 7, "nullable": true }, "secondEmergencyContactPhone": { "title": "second emergency contact's phone number", "description": "Employee's second emergency contact's phone number", "type": "string", "maximum": 100, "example": "100 200 3003" }, "gender": { "title": "gender", "description": "Allowed values: 'F', 'M'", "type": "string", "enum": [ "F", "M" ] }, "jobTypeCode": { "title": "job type code", "description": "The Job status of the Employee. See below for a list of the possible values:
\n Occasional: `1`
\n Part-time: `2`
\n Full-time: `3`
\n Seasonal: `4`
\n Contractual: `5`
\n Internship: `6`
\n Contractor: `7`
\n Temporary: `8`
\n On call/Full time: `9`
\n Early Retirement: `10`
\n Probation: `11`
\n Supernumerary: `12`
\n Contractual - Full-time: `13`
\n Contractual - Part-time: `14`
\n Maternity / Parental Leave: `15`
\n Disability: `16`
\n Casual Relief: `17`
\n Student: `18`
\n External Consultant: `19`
\n CDI full-time: `20`
\n CDI part-time: `21`
\n CDD full-time: `22`
\n CDD part-time: `23`
\n Temporary Foreign Worker: `24`
\n ", "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24 ] }, "languages": { "title": "languages", "description": "List of languages (ISO 639-1 codes) spoken by the employee. See [here](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for a list of valid ISO 639-1 codes.", "type": "array", "items": { "type": "string", "example": "fr" } }, "recognitionDate": { "title": "Recognition date", "description": "The Recognition date of the employee", "type": "string", "format": "YYYY-MM-DD", "example": "2020-01-01" }, "salaryType": { "title": "Salary type", "description": "Employee salary type. Allowed values: 'hourlyRate', 'perPay'", "type": "string", "enum": [ "hourlyRate", "perPay" ], "example": "hourlyRate" }, "hoursPerPay": { "title": "Hours per pay", "description": "How many hours is there per pay, for the employee", "type": "number", "example": 80 }, "birthDate": { "title": "Birthday", "description": "The employee's birth date", "type": "string", "format": "YYYY-MM-DD", "example": "1999-01-01" }, "salary": { "title": "salary", "description": "Employee's salary", "type": "number", "example": 55 }, "annualSalary": { "title": "annual salary", "description": "Employee's annual salary", "type": "number", "example": 110000 }, "salaryStep": { "title": "salary step", "description": "Employee's salary step", "type": "number", "example": 4 }, "externalIds": { "title": "externalIds", "description": "Employee's external IDs from third party integrations. Only available when the company is configured with a supported integration.", "type": "object", "additionalProperties": { "type": "string", "example": "6377f2a3-4e7c-4a05-9097-5b6baf5e3c82" } }, "payroll": { "title": "Payroll", "description": "Payroll system information.", "properties": { "clientNumber": { "description": "The number of the payroll system of the employee. Note, this is not the ID of the system, but the number of the system.", "type": "string", "example": "PM123456" }, "payGroup": { "description": "The pay group of the employee. Note, this is not the ID of the pay group, but the number of the Pay Group.", "type": "string", "example": "PG005678" }, "businessNumber": { "description": "The Business Number of the employee. Note, this is not the ID of the business number, but the number of the business number. This value is only shown used then the company has the Payworks Payroll.", "type": "string", "example": "98765" }, "bankAccount": { "description": "The bank account information of the employee.", "properties": { "account": { "description": "The bank account number.", "type": "string", "example": "12345" }, "transit": { "description": "The bank account transit number.", "type": "string", "example": "345" }, "institution": { "description": "The bank account institution number.", "type": "string", "example": "98765" } }, "type": "object" } }, "type": "object" }, "comments": { "title": "comments", "description": "Employee's comments", "type": "string", "maxLength": 1000, "example": "His name is bond. James bond." } }, "type": "object" }, "CustomFieldOptionResource": { "properties": { "value": { "title": "value", "description": "Value of the option", "type": "string", "example": "Various" }, "code": { "title": "code", "description": "Code of the option", "type": "string", "example": "007" } }, "type": "object" }, "CustomFieldResource": { "title": "CustomFieldResource", "description": "Class CustomFieldResource", "properties": { "id": { "title": "id", "description": "ID of the custom field", "type": "integer", "example": "1" }, "name_en": { "title": "name_en", "description": "English name of the custom field", "type": "string", "example": "Position" }, "name_fr": { "title": "name_fr", "description": "French name of the custom field", "type": "string", "example": "Position" }, "category": { "title": "category", "description": "Category of the custom field", "type": "string", "enum": [ "corporative", "personal", "remuneration" ], "example": "corporate" }, "type": { "title": "type", "description": "Type of the custom field", "type": "string", "enum": [ "date", "dropdown", "text" ], "example": "text" }, "is_salary": { "title": "is_salary", "description": "Is the custom field used as salary", "type": "boolean", "example": "false" }, "is_used_in_headcount": { "title": "is_used_in_headcount", "description": "Is the custom field used in headcount. Returned as the string `1` or `0`, not an integer.", "type": "string", "example": "1" }, "is_used_in_nethris_integration": { "title": "is_used_in_nethris_integration", "description": "Is the custom field used in the Nethris integration. Returned as the string `1` or `0`.", "type": "string", "example": "0" }, "is_used_as_user_role": { "title": "is_used_as_user_role", "description": "Is the custom field used to give access to some employees. Returned as the string `1` or `0`, not an integer.", "type": "string", "example": "0" }, "options": { "title": "options", "description": "List of options for the custom field, if the type is 'dropdown'", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldOptionResource" } } }, "type": "object" }, "CustomFieldValueResource": { "title": "CustomFieldValueResource", "properties": { "id": { "title": "ID", "description": "ID of the custom field value", "type": "integer", "example": 1 }, "custom_employee_field_id": { "title": "Custom Employee Field ID", "description": "ID of the custom employee field", "type": "integer", "example": 2 }, "employee_id": { "title": "Employee ID", "description": "ID of the employee", "type": "integer", "example": 3 }, "corporate_profile_id": { "title": "Corporate Profile ID", "description": "ID of the corporate profile", "type": "integer", "example": 4, "nullable": true }, "value": { "title": "Value", "description": "The value of the custom field", "type": "string", "example": "Some value", "nullable": true }, "selected_value": { "title": "Selected Value", "description": "The selected value for dropdown custom fields", "type": "string", "example": "Option 1", "nullable": true } }, "type": "object" }, "EmergencyContactRelationshipResource": { "title": "EmergencyContactRelationshipResource", "properties": { "fr": { "title": "French title", "description": "The french name of the relationship", "type": "string", "example": "Époux" }, "en": { "title": "English title", "description": "The english name of the relationship", "type": "string", "example": "Spouse" } }, "type": "object" }, "EmergencyContactResource": { "title": "EmergencyContactResource", "properties": { "name": { "title": "Name", "description": "The name of the emergency contact", "type": "string", "example": "Folksy" }, "phone": { "title": "Phone", "description": "The phone of the emergency contact", "type": "string", "example": "418 555 5555" }, "relationship": { "title": "Relationship", "description": "Relationship to the emergency contact", "type": "object" } }, "type": "object" }, "EmployeeProfileNoteResource": { "properties": { "id": { "title": "id", "description": "The profile note ID.", "type": "integer", "example": 10 }, "date": { "title": "date", "description": "The profile note date.", "type": "string", "format": "date", "example": "2025-07-18" }, "title": { "title": "title", "description": "The profile note title.", "type": "string", "example": "Lorem ipsum" }, "notes": { "title": "notes", "description": "The profile note content.", "type": "string", "example": "Lorem ipsum dolor sit amet, consectetur adipiscing elit." }, "created_at": { "title": "created_at", "description": "The profile note creation date.", "type": "string", "format": "date", "example": "2025-07-18 12:00:00" }, "updated_at": { "title": "updated_at", "description": "The profile note update date.", "type": "string", "format": "date", "example": "2025-07-18 12:12:05" }, "updated_by": { "$ref": "#/components/schemas/UpdaterResource" }, "attachments": { "title": "attachments", "description": "Attachments related to the profile note.", "type": "array", "items": { "$ref": "#/components/schemas/AttachmentsResource" } } }, "type": "object" }, "EmployeeResource": { "title": "EmployeeResource", "description": "Employee resource", "properties": { "id": { "title": "id", "description": "Employee's id", "type": "integer", "example": "186415" }, "first_name": { "title": "first_name", "description": "Employee's first name", "type": "string", "example": "James" }, "last_name": { "title": "last_name", "description": "Employee's last name", "type": "string", "example": "Bond" }, "gender": { "title": "gender", "description": "Employee's gender. Can be 'M' or 'F'.", "type": "string", "enum": [ "F", "M" ], "example": "F" }, "code": { "title": "code", "description": "Employee's code", "type": "string", "example": "007" }, "personal_email": { "title": "personal_email", "description": "Employee's personal email", "type": "string", "example": "jamesy@hotmail.com" }, "image": { "title": "image", "description": "Employee's image", "type": "string", "example": "https://host/path/to/the/image" }, "image_thumbnail": { "title": "image_thumbnail", "description": "A smaller version of the employee image, used when the full image is not needed. The thumbnail has a width of 256 pixels.", "type": "string", "example": "https://host/path/to/the/image_256" }, "primaryPhone": { "title": "primaryPhone", "description": "Employee's primary phone number", "type": "string", "example": "+1 123 456-7890" }, "secondaryPhone": { "title": "secondaryPhone", "description": "Employee's secondary phone number", "type": "string", "example": "+1 123 456-7890" }, "addressLine1": { "title": "addressLine1", "description": "Employee's address (line 1)", "type": "string", "example": "1122 Wood street" }, "addressLine2": { "title": "addressLine3", "description": "Employee's address (line 2)", "type": "string", "example": "App. 20" }, "addressLine3": { "title": "addressLine3", "description": "Employee's address (line 3)", "type": "string", "example": "Building 2" }, "city": { "title": "city", "description": "Employee's city", "type": "string", "example": "Quebec city" }, "postalCode": { "title": "postalCode", "description": "Employee's postal code/zip code", "type": "string", "example": "A1B 2C3" }, "birthDate": { "title": "birthDate", "description": "Employee's birth date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "ended_at": { "title": "ended_at", "description": "Employee's ended_at date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "started_at": { "title": "started_at", "description": "Employee's hiring date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "returned_at": { "title": "returned_at", "description": "Employee's returned date", "type": "string", "format": "YYYY-MM-DD", "example": "2012-05-21" }, "inactivated_at": { "title": "inactivated_at", "description": "Employee's inactivated date", "type": "string", "format": "YYYY-MM-DD hh:ii:ss", "example": "2014-01-01 00:00:00" }, "active": { "title": "Is active", "description": "Employee's active/inactive status in the system.", "type": "boolean", "example": "true" }, "company_id": { "title": "company_id", "description": "Employee's company ID", "type": "integer", "example": "444" }, "languages": { "title": "languages", "description": "Employee's languages", "type": "array", "items": { "$ref": "#/components/schemas/ProfileLanguageResource" }, "example": "[{'abbreviation': 'fr', 'name': {'fr': 'Français', 'en': 'English'}}]" }, "emergency_contacts": { "title": "Emergency contacts", "description": "Employee's emergency contacts", "type": "array", "items": { "$ref": "#/components/schemas/EmergencyContactResource" } } }, "type": "object" }, "V2NormResource": { "title": "V2NormResource", "properties": { "id": { "description": "Norm ID", "type": "integer", "example": 1 }, "year": { "description": "Year", "type": "integer", "example": 2026 }, "vacation": { "description": "Vacation days", "type": "number", "format": "float", "example": 20 }, "absence": { "description": "Absence days", "type": "number", "format": "float", "example": 5 }, "work_ethic": { "description": "Work ethic days", "type": "number", "format": "float", "example": 0 }, "accident": { "description": "Accident days", "type": "number", "format": "float", "example": 0 }, "performance": { "description": "Performance days", "type": "number", "format": "float", "example": 0 }, "overtime": { "description": "Overtime hours", "type": "number", "format": "float", "example": 0 }, "overtime_min_hour": { "description": "Overtime minimum hours", "type": "number", "format": "float", "example": 0 }, "personal": { "description": "Personal days", "type": "number", "format": "float", "example": 3 }, "sick_days": { "description": "Sick days", "type": "number", "format": "float", "example": 0 }, "last_year_vacation": { "description": "Last year vacation days", "type": "number", "format": "float", "example": 2 }, "last_year_personal": { "description": "Last year personal days", "type": "number", "format": "float", "example": 0 }, "last_year_absence": { "description": "Last year absence days", "type": "number", "format": "float", "example": 0 }, "last_year_sick_days": { "description": "Last year sick days", "type": "number", "format": "float", "example": 0 }, "employee_id": { "description": "Employee ID", "type": "integer", "example": 1 }, "employee": { "description": "Employee", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmployeeResource" } ] } }, "type": "object" }, "EmbeddedEmployeePartnerResource": { "title": "Embedded Employee Partner resource", "description": "The employee partner resource used when an employee is embedded in another resource", "properties": { "id": { "title": "id", "description": "Employee's id", "type": "integer", "example": "186415" }, "first_name": { "title": "first_name", "description": "Employee's first name", "type": "string", "example": "James" }, "last_name": { "title": "last_name", "description": "Employee's last name", "type": "string", "example": "Bond" }, "gender": { "title": "gender", "description": "Employee's gender. Can be 'M' or 'F'.", "type": "string", "enum": [ "F", "M" ], "example": "F" }, "code": { "title": "code", "description": "Employee's code", "type": "string", "example": "007" }, "personalEmail": { "title": "personalEmail", "description": "Employee's personal email", "type": "string", "example": "jamesy@hotmail.com" }, "image": { "title": "image", "description": "Employee's image", "type": "string", "example": "test.jpg" }, "phoneNumber": { "title": "phoneNumber", "description": "Employee's primary phone number", "type": "string", "example": "+1 123 456-7890" }, "secondaryPhoneNumber": { "title": "secondaryPhoneNumber", "description": "Employee's secondary phone number", "type": "string", "example": "+1 123 456-7890" }, "addressLine1": { "title": "addressLine1", "description": "Employee's address (line 1)", "type": "string", "example": "1122 Wood street" }, "addressLine2": { "title": "addressLine2", "description": "Employee's address (line 2)", "type": "string", "example": "App. 20" }, "addressLine3": { "title": "addressLine3", "description": "Employee's address (line 3)", "type": "string", "example": "Building 2" }, "city": { "title": "city", "description": "Employee's city", "type": "string", "example": "Quebec city" }, "postalCode": { "title": "postalCode", "description": "Employee's postal code/zip code", "type": "string", "example": "A1B 2C3" }, "birthDate": { "title": "birthDate", "description": "Employee's birth date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "ended_at": { "title": "ended_at", "description": "Employee's termination date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "started_at": { "title": "started_at", "description": "Employee's hiring date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "returned_at": { "title": "returned_at", "description": "Employee's return date", "type": "string", "format": "YYYY-MM-DD", "example": "2012-05-21" }, "inactivated_at": { "title": "inactivated_at", "description": "Employee's deletion date", "type": "string", "format": "YYYY-MM-DD hh:ii:ss", "example": "2014-01-01 00:00:00" }, "company_id": { "title": "company_id", "description": "Employee's company ID", "type": "integer", "example": "444" } }, "type": "object" }, "CountryPartnerResource": { "description": "Class CountryPartnerResource.", "properties": { "abbreviation": { "title": "abbreviation", "description": "The abbreviation for the country", "type": "string", "example": "CA" }, "name": { "title": "name", "description": "The names of the country", "properties": { "fr": { "title": "fr", "description": "The french name of the country", "type": "string", "example": "Royaume Unis" }, "en": { "title": "en", "description": "The english name of the country", "type": "string", "example": "United Kingdom" } }, "type": "object" } }, "type": "object" }, "CustomFieldPartnerResource": { "title": "CustomFieldResource", "properties": { "id": { "title": "ID", "description": "ID of the custom field", "type": "integer", "example": "1" }, "name": { "title": "Name", "description": "The name of the custom field", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TranslatableNameSchema" } ] }, "integration": { "title": "Integration", "description": "Integration used with this custom field", "type": "string", "example": "Prextra" }, "category": { "title": "Category", "description": "Category of the custom field", "type": "string", "enum": [ "corporative", "personal" ], "example": "corporative" }, "type": { "title": "Type", "description": "Type of the custom field", "type": "string", "enum": [ "text", "date", "dropdown" ], "example": "text" }, "isSalary": { "title": "Is salary", "description": "Whether the custom field is used in salary calculation", "type": "boolean", "example": "false" }, "value": { "title": "Value", "description": "The value of the custom field ", "type": "string", "example": "some value" }, "value_id": { "title": "Value Id", "description": "The ID of the value for the custom field ", "type": "integer", "example": 145 }, "options": { "description": "Options", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldOptionResource" } } }, "type": "object" }, "DepartmentPartnerResource": { "properties": { "id": { "title": "ID", "description": "ID of the department", "type": "integer", "example": "42" }, "name": { "title": "name", "description": "Name of the department in English and French", "properties": { "fr": { "title": "French name", "description": "Department name in French", "type": "string", "example": "Opérateur" }, "en": { "title": "English name", "description": "Department name in English", "type": "string", "example": "Operator" } }, "type": "object" }, "code": { "title": "code", "description": "Department code", "type": "string", "example": "OP_1" }, "hoursPerWeek": { "title": "hoursPerWeek", "description": "Normal working hours per week for the department", "type": "integer", "example": 35 }, "overtimeThreshold": { "title": "overtimeThreshold", "description": "Department's minimum hours for overtime", "type": "integer", "example": 40 }, "remittance": { "title": "remittance", "description": "Department's remittance value", "type": "integer", "example": 35 } }, "type": "object" }, "EmergencyContactPartnerResource": { "title": "EmergencyContactResource", "description": "Class EmergencyContactPartnerResource.", "properties": { "name": { "title": "Name", "description": "The name of the emergency contact", "type": "string", "example": "Folksy" }, "phone": { "title": "Phone", "description": "The phone of the emergency contact", "type": "string", "example": "418 555 5555" } }, "type": "object" }, "ExternalEmployeeResource": { "title": "EmployeeResource", "properties": { "id": { "title": "id", "description": "Employee's id", "type": "integer", "example": "2" }, "employeeNumber": { "title": "number", "description": "Employee's number", "type": "string", "example": "007" }, "firstName": { "title": "firstName", "description": "Employee's first name", "type": "string", "example": "James" }, "lastName": { "title": "lastName", "description": "Employee's last name", "type": "string", "example": "Bond" }, "gender": { "title": "gender", "description": "Employee's gender. Can be 'M' or 'F'. You need the Personal Information parameter to see this data.", "type": "string", "enum": [ "F", "M" ], "example": "M" }, "languages": { "title": "languages", "description": "Employee's languages. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=languages`.", "type": "array", "items": { "$ref": "#/components/schemas/LanguagePartnerResource" } }, "startDate": { "title": "startDate", "description": "Employee's starting date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "birthDate": { "title": "birthDate", "description": "Employee's birth date. You need the Personal Information parameter to see this data.", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "addressLine1": { "title": "addressLine1", "description": "Employee's address (line 1). You need the Personal Information parameter to see this data.", "type": "string", "example": "1122 Wood street" }, "addressLine2": { "title": "addressLine3", "description": "Employee's address (line 2). You need the Personal Information parameter to see this data.", "type": "string", "example": "App. 20" }, "addressLine3": { "title": "addressLine3", "description": "Employee's address (line 3). You need the Personal Information parameter to see this data.", "type": "string", "example": "Building 2" }, "city": { "title": "city", "description": "Employee's city", "type": "string", "example": "Quebec city" }, "country": { "title": "country", "description": "Employee's country. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=country`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CountryPartnerResource" } ] }, "province": { "title": "province", "description": "Employee's province/state/region. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=province`.", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProvincePartnerResource" } ] }, "employmentProvince": { "title": "employmentProvince", "description": "Employee's province/state/region for payroll purposes. Only returned when the company is configured with a payroll system, on both the list and the detail endpoint. This field is driven by the payroll integration, not by `_embed`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProvincePartnerResource" } ] }, "postalCode": { "title": "postalCode", "description": "Employee's postal code/zip code. You need the Personal Information parameter to see this data.", "type": "string", "example": "A1B 2C3" }, "phoneNumber": { "title": "phoneNumber", "description": "Employee's primary phone number. You need the Personal Information parameter to see this data.", "type": "string", "example": "+1 123 456-7890" }, "secondaryPhoneNumber": { "title": "secondaryPhoneNumber", "description": "Employee's secondary phone number. You need the Personal Information parameter to see this data.", "type": "string", "example": "+1 123 456-7890" }, "socialInsuranceNumber": { "title": "socialInsuranceNumber", "description": "Employee's social insurance number. You need the Sensitive Information parameter to see this data.", "type": "string", "example": "123 456 789" }, "profileImage": { "title": "profileImage", "description": "Link to the employee's profile image", "type": "string", "example": "https://host.com/path/to/the/image" }, "profileImageThumbnail": { "title": "profileImageThumbnail", "description": "Link to the employee's profile image thumbnail, which is a 256px wide copy of the original image.", "type": "string", "example": "https://host.com/path/to/the/image/thumbnail" }, "experience": { "title": "experience", "description": "Employee's recognised experience", "type": "number", "example": 1.5 }, "corporateEmail": { "title": "corporateEmail", "description": "Employee's corporate email address", "type": "string", "example": "james.bond@mi6.co.uk" }, "personalEmail": { "title": "personalEmail", "description": "Employee's personal email address. You need the Personal Information parameter to see this data.", "type": "string", "example": "james.bond@aol.com" }, "corporatePhoneNumber": { "title": "corporatePhoneNumber", "description": "Employee's work phone number", "type": "string", "example": "+1 987 555-5555" }, "corporatePhoneNumberExtension": { "title": "corporatePhoneNumberExtension", "description": "Employee's work phone extension", "type": "string", "example": "113", "nullable": true }, "supervisor": { "title": "supervisor", "description": "Employee's supervisor. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=supervisor`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SupervisorPartnerResource" } ] }, "recognitionDate": { "title": "recognitionDate", "description": "Employee's recognition date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-01-04" }, "endDate": { "title": "endDate", "description": "Employee's departure date", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29" }, "endDateType": { "title": "endDateType", "description": "Employee's departure type", "type": "string", "enum": [ "permanent", "temporary" ], "example": "temporary", "nullable": true }, "layoffType": { "title": "layoffType", "description": "Employee's layoff type (if departureType id temporary)", "type": "string", "enum": [ "layoff", "parental", "disability", "work_accident", "sabbatical" ], "example": "parental", "nullable": true }, "returnDate": { "title": "returnDate", "description": "Employee's return date", "type": "string", "format": "YYYY-MM-DD", "example": "2012-05-21" }, "dailyWorkHours": { "title": "dailyWorkHours", "description": "Employee's daily work hours", "type": "number", "example": "7.5" }, "weeklyWorkHours": { "title": "weeklyWorkHours", "description": "Employee's weekly work hours", "type": "number", "example": "37.5" }, "position": { "title": "position", "description": "Employee's position. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=position`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PositionPartnerResource" } ] }, "department": { "title": "department", "description": "Employee's department. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=department`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/DepartmentPartnerResource" } ] }, "workingSite": { "title": "workingSite", "description": "Employee's working site. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=workingSite`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WorkingSitePartnerResource" } ] }, "union": { "title": "union", "description": "Employee's union. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=union`.", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/UnionPartnerResource" } ] }, "jobStatus": { "title": "jobStatus", "description": "Employee's job status. Not included by default on either endpoint — request it with `_embed[]=jobStatus`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/JobStatusPartnerResource" } ] }, "salary": { "title": "salary", "description": "Employee's salary. You need the Sensitive Information parameter to see this data", "type": "number", "example": 965.62 }, "salaryType": { "title": "salaryType", "description": "Employee's salary type. You need the Sensitive Information parameter to see this data", "type": "string", "example": "perPay" }, "hoursPerPay": { "title": "hoursPerPay", "description": "Employee's hours per pay", "type": "number", "example": 37.5 }, "annualSalary": { "title": "annualSalary", "description": "Employee's annual salary.You need the Sensitive Information parameter to see this data.", "type": "number", "example": 50212.51 }, "salaryEffectiveDate": { "title": "salaryEffectiveDate", "description": "Employee's salary effective date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-01-01" }, "comments": { "title": "comments", "description": "Employee's comments", "type": "string", "example": "His name is bond. James bond." }, "creationDate": { "title": "creationDate", "description": "Employee's creation date", "type": "string", "format": "YYYY-MM-DD hh:ii:ss", "example": "2024-01-01 00:00:00" }, "totalSeniority": { "title": "totalSeniority", "description": "Employee's seniority", "type": "number", "example": "3.2" }, "emergencyContacts": { "title": "emergencyContacts", "description": "Employee's emergency contacts. You need the Personal Information parameter to see this data.", "type": "array", "items": { "$ref": "#/components/schemas/EmergencyContactPartnerResource" } }, "customFields": { "title": "customFields", "description": "Employee's custom fields. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=customFields`.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldPartnerResource" } }, "referenceId": { "title": "referenceId", "description": "Employee's reference ID. Always null: no column backs this field, so it is kept only for backward compatibility and should not be relied on.", "type": "string", "nullable": true }, "externalIds": { "title": "externalIds", "description": "Employee's external IDs from third party integrations. Only available when the company is configured with a supported integration.", "type": "object", "additionalProperties": { "type": "string", "example": "6377f2a3-4e7c-4a05-9097-5b6baf5e3c82" } }, "voilaFields": { "title": "voilaFields", "description": "Employee's Voila custom field values. Only returned when the company is configured with Evolia time and attendance. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=voilaFieldValues`.", "type": "array", "items": { "$ref": "#/components/schemas/VoilaFieldsPartnerResource" } }, "companyNumber": { "title": "companyNumber", "description": "Employee's payroll company number. Only returned when the company is configured with the Deluxe payroll.", "type": "string", "example": "PM123456", "nullable": true }, "startDateDeluxe": { "title": "startDateDeluxe", "description": "Employee's start date in the payroll system. Only returned when the company is configured with the Deluxe payroll.", "type": "string", "format": "YYYY-MM-DD", "example": "2009-12-29", "nullable": true }, "allianceClass": { "title": "allianceClass", "description": "Employee's Alliance SC class. Only returned when the company is configured with the Alliance SC insurance. Always `null` — the backing column is not exposed by the `employees` database view.", "type": "string", "nullable": true }, "allianceDivision": { "title": "allianceDivision", "description": "Employee's Alliance SC division. Only returned when the company is configured with the Alliance SC insurance. Always `null` — the backing column is not exposed by the `employees` database view.", "type": "string", "nullable": true }, "allianceId": { "title": "allianceId", "description": "Employee's Alliance SC identifier. Only returned when the company is configured with the Alliance SC insurance. Always `null` — the backing column is not exposed by the `employees` database view.", "type": "string", "nullable": true }, "lastUpdateDate": { "title": "lastUpdateDate", "description": "Employee's last update date", "type": "string", "format": "YYYY-MM-DD hh:ii:ss", "example": "2022-01-01 00:00:00" }, "payroll": { "title": "Payroll", "description": "Payroll system information. Only returned when the company is configured with a payroll system, on both the list and the detail endpoint.", "properties": { "clientNumber": { "description": "The number of the payroll system of the employee. Note, this is not the ID of the system, but the number of the system.", "type": "string", "example": "PM123456" }, "payGroup": { "description": "The pay group of the employee. Note, this is not the ID of the pay group, but the number of the Pay Group.", "type": "string", "example": "PG005678" }, "businessNumber": { "description": "The Business Number of the employee. Note, this is not the ID of the business number, but the number of the business number. This value is only shown used then the company has the Payworks Payroll.", "type": "string", "example": "98765" }, "bankAccount": { "description": "The bank account information of the employee. You need the Sensitive Information parameter to see this data.", "properties": { "account": { "description": "The bank account number.", "type": "string", "example": "12345" }, "transit": { "description": "The bank account transit number.", "type": "string", "example": "345" }, "institution": { "description": "The bank account institution number.", "type": "string", "example": "98765" } }, "type": "object" } }, "type": "object" }, "salaryRate": { "title": "salaryRate", "description": "Employee's salary rate. You need the Sensitive Information parameter to see this data.
NOTE: If the field 'hours_per_pay' is either null or has the value 0, then the salaryRate will be null", "type": "number", "example": "30.12" }, "salaryCustomFields": { "title": "salaryCustomFields", "description": "Employee's salary custom fields. You need the Sensitive Information parameter to see this data. Included by default on the list endpoint; on `GET /api/v2/employees/{employee}` request it with `_embed[]=customFields`.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldPartnerResource" } }, "paymentMethod": { "title": "paymentMethod", "description": "Employee's payment method. You need the Sensitive Information parameter to see this data. Not included by default on either endpoint — request it with `_embed[]=paymentMethod`.", "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodResource" } }, "depositType": { "title": "depositType", "description": "Employee's deposit type. You need the Sensitive Information parameter to see this data. Not included by default on either endpoint — request it with `_embed[]=depositType`.", "type": "array", "items": { "$ref": "#/components/schemas/DepositTypeResource" } } }, "type": "object" }, "JobStatusPartnerResource": { "properties": { "id": { "title": "id", "description": "The ID of the job status", "type": "integer", "example": "30" }, "name": { "title": "name", "description": "The names of the job status", "properties": { "fr": { "title": "fr", "description": "The french name of the job status", "type": "string", "example": "Temps plein" }, "en": { "title": "en", "description": "The english name of the job status", "type": "string", "example": "Full-time" } }, "type": "object" } }, "type": "object" }, "LanguagePartnerResource": { "title": "LanguageResource", "properties": { "abbreviation": { "title": "Abbreviation", "description": "ISO 6391 Code of the language", "type": "string", "example": "fr" }, "name": { "title": "Name", "description": "The name of the language", "properties": { "fr": { "title": "French version of the language", "type": "string", "example": "Français" }, "en": { "title": "English version of the language", "type": "string", "example": "French" } }, "type": "object" } }, "type": "object" }, "PositionPartnerResource": { "properties": { "id": { "title": "ID", "description": "ID of the position", "type": "integer", "example": "42" }, "name": { "title": "name", "description": "Name of the position in English and French", "properties": { "fr": { "title": "French name", "description": "Position name in French", "type": "string", "example": "Opérateur" }, "en": { "title": "English name", "description": "Position name in English", "type": "string", "example": "Operator" } }, "type": "object" }, "code": { "title": "code", "description": "Position code", "type": "string", "example": "OP_1" }, "hoursPerWeek": { "title": "hoursPerWeek", "description": "Normal working hours per week for the position", "type": "integer", "example": 35 }, "overtimeThreshold": { "title": "overtimeThreshold", "description": "Position's minimum hours for overtime", "type": "integer", "example": 40 } }, "type": "object" }, "ProvincePartnerResource": { "description": "Class ProvincePartnerResource.", "properties": { "abbreviation": { "title": "abbreviation", "description": "The abbreviation for the Province or state", "type": "string", "example": "QC" }, "name": { "title": "name", "description": "The names of the Province or state", "properties": { "fr": { "title": "fr", "description": "The french name of the province or state", "type": "string", "example": "Québec" }, "en": { "title": "en", "description": "The english name of the province or state", "type": "string", "example": "Quebec" } }, "type": "object" } }, "type": "object" }, "SupervisorPartnerResource": { "properties": { "id": { "title": "id", "description": "The ID of the supervisor", "type": "number", "example": "10" }, "firstName": { "title": "firstName", "description": "the first name of the supervisor", "type": "string", "example": "M" }, "lastName": { "title": "firstName", "description": "The last name of the supervisor", "type": "string", "example": "???" }, "number": { "title": "number", "description": "The code of the supervisor", "type": "string", "example": "MI6 #1", "deprecated": true }, "code": { "title": "code", "description": "The code of the supervisor", "type": "string", "example": "MI6 #1" } }, "type": "object" }, "UnionPartnerResource": { "title": "Union Partner Resource", "properties": { "id": { "title": "ID", "description": "Union's ID", "type": "integer", "example": 234 }, "name": { "title": "Name", "description": "Union's name in different languages", "properties": { "fr": { "title": "French Name", "description": "Union's name in French", "type": "string", "example": "Syndicat des Travailleurs" }, "en": { "title": "English Name", "description": "Union's name in English", "type": "string", "example": "Workers Union" } }, "type": "object" }, "code": { "title": "Code", "description": "Union's code", "type": "string", "example": "ST" } }, "type": "object" }, "VoilaFieldsPartnerResource": { "title": "Voila Fields Partner Resource", "description": "Resource for Voila fields associated with a partner", "properties": { "id": { "title": "ID", "description": "The ID of the field", "type": "string", "example": "e7c0d88a-f559-4fb5-86a5-37cfa507322f" }, "name": { "title": "Name", "description": "The name of the field in different languages", "properties": { "fr": { "type": "string", "example": "Nom du champ" }, "en": { "type": "string", "example": "Field name" } }, "type": "object" }, "value": { "title": "Value", "description": "The value of the field", "type": "string", "example": "Field value" }, "code": { "title": "Code", "description": "The code of the field", "type": "string", "example": "FIELD_CODE" } }, "type": "object" }, "WorkingSitePartnerResource": { "title": "Working Site Partner Resource", "properties": { "id": { "title": "ID", "description": "Working Site's ID", "type": "integer", "example": 42 }, "name": { "title": "Name", "description": "Working Site's name in different languages", "properties": { "fr": { "title": "French Name", "description": "Working Site's name in French", "type": "string", "example": "Ottawa - Quartier Général" }, "en": { "title": "English Name", "description": "Working Site's name in English", "type": "string", "example": "Ottawa - Headquarters" } }, "type": "object" }, "code": { "title": "Code", "description": "Working Site's code", "type": "string", "example": "HQ_1" }, "hoursPerWeek": { "title": "Hours Per Week", "description": "Working Site's normal weekly hours", "type": "number", "example": 35 }, "overtimeThreshold": { "title": "Overtime Threshold", "description": "The number of hours before additional hours are considered overtime", "type": "number", "example": 40 }, "remittance": { "title": "Remittance", "description": "Working Site's remittance percentage", "type": "number", "example": 20 } }, "type": "object" }, "StoreAbsenceControlRequest": { "description": "Class StoreAbsenceControlRequest.", "required": [ "absence_reason_id", "started_at", "ended_at", "sick_days_bank", "paid_absence", "distribution", "employee_id" ], "properties": { "absence_reason_id": { "title": "absence_reason_id", "description": "ID of absence reason. A list of the possible absence reasons can be fetched from the [Absence Reason Endpoint](#/Absences/getAbsenceReasons).", "type": "integer", "example": "1" }, "started_at": { "title": "started_at", "description": "absence start date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-07-01" }, "ended_at": { "title": "ended_at", "description": "absence end date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-07-15" }, "approved_at": { "title": "approved_at", "description": "absence approbation date. Optional, but it must not be empty when the key is sent.", "type": "string", "format": "YYYY-MM-DD", "example": "2021-06-25" }, "paid_absence": { "title": "paid_absence", "description": "Is the absence a paid one?", "type": "boolean", "example": "1" }, "sick_days_bank": { "title": "sick_days_bank", "description": "Is the absence impute the sick days bank?", "type": "boolean", "example": "1" }, "distribution": { "title": "distribution", "description": "Absence distribution span. This contains the amount of hours or days taken by the absence, for each day of the period between the started_at and the ended_at property.
It is required to have an equal amount of elements in the property as days in the absence. A value of 0 indicate a day where no absence was taken.", "type": "string", "example": "8,8,8,8,7.5" }, "notes": { "title": "notes", "description": "absences notes", "type": "string", "example": "To approve" }, "employee_id": { "title": "employee_id", "description": "ID of the employee", "type": "integer", "example": "5" } }, "type": "object" }, "UpdateAbsenceRequest": { "description": "Class UpdateAbsenceRequest.", "required": [ "employee_id", "absence_reason_id", "started_at", "ended_at", "paid_absence", "distribution" ], "properties": { "employee_id": { "title": "employee_id", "description": "ID of the employee", "type": "integer", "example": "8" }, "absence_reason_id": { "title": "absence_reason_id", "description": "ID of absence reason. A list of the possible absence reasons can be fetched from the [Absence Reason Endpoint](#/Absences/getAbsenceReasons).", "type": "integer", "example": "2" }, "started_at": { "title": "started_at", "description": "Absence start date", "type": "string", "format": "YYYY-MM-DD", "example": "2020-05-01" }, "ended_at": { "title": "ended_at", "description": "Absence end date", "type": "string", "format": "YYYY-MM-DD", "example": "2020-05-15" }, "paid_absence": { "title": "paid_absence", "description": "Whether the absence is a paid one", "type": "boolean", "example": "1" }, "sick_days_bank": { "title": "sick_days_bank", "description": "Whether the absence should affect the sick days bank.", "type": "boolean", "example": "1" }, "distribution": { "title": "distribution", "description": "Absence distribution span. This contains the amount of hours or days taken by the absence, for each day of the period between the started_at and the ended_at property.
It is required to have an equal amount of elements in the property as days in the absence. A value of 0 indicate a day where no absence was taken.", "type": "string", "example": "8,8,8,8,7.5,7.5,8" }, "notes": { "title": "notes", "description": "Absence notes", "type": "string", "example": "To approve" } }, "type": "object" }, "AbsenceReasonResource": { "title": "Absence Reason Resource", "properties": { "id": { "title": "id", "description": "ID of the absence reason", "type": "integer", "example": "1" }, "text": { "title": "text", "description": "English name of the absence reason", "type": "string", "example": "Vacation" }, "text_fr": { "title": "text_fr", "description": "French name of the absence reason", "type": "string", "example": "Vacances" }, "company_id": { "title": "company_id", "description": "Company ID that the absence reason is attached to. Null for the reasons shared across every company.", "type": "integer", "example": "123", "nullable": true }, "is_displayed": { "title": "is_displayed", "description": "Whether the reason should be selectable by the user or not.", "type": "boolean", "example": "true" } }, "type": "object" }, "AbsenceResource": { "title": "Absence Resource", "properties": { "id": { "title": "id", "description": "Absence's id", "type": "integer", "example": "33" }, "employee": { "title": "employee", "description": "The employee related to the absence.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmbeddedEmployeePartnerResource" } ] }, "reason": { "title": "reason", "description": "The reason of the absence. Required to be embeded using `_embed[]=reason`", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AbsenceReasonResource" } ], "x-embedable": "reason" }, "started_at": { "title": "started_at", "description": "Date of absence start", "type": "string", "example": "2021-02-18" }, "ended_at": { "title": "ended_at", "description": "Date of absence end", "type": "string", "format": "YYYY-MM-DD", "example": "2021-02-18" }, "inactivated_at": { "title": "inactivated_at", "description": "Date of deletion of the absence. All absences are soft deleted.", "type": "string", "example": "0000-00-00 00:00:00" }, "approved_at": { "title": "approved_at", "description": "Date of the approval", "type": "string", "format": "YYYY-MM-DD", "example": "2021-02-18" }, "duration": { "title": "duration", "description": "The total duration of the absence in days or in hours, depending on the 'unit' property", "type": "string", "example": "60" }, "distribution": { "title": "distribution", "description": "A list of number, separated by commas, that indicate how many hours / days are used for each day from the start date of the absence to the end date", "type": "string", "example": "8,8,8,0,0,8,8,8" }, "unit": { "title": "unit", "description": "The unit used to define the duration and distribution of the absence. It is the same for all absences of the same company", "type": "string", "enum": [ "hours", "days" ], "example": "hours" }, "notes": { "title": "notes", "description": "Additional notes", "type": "string", "example": "Snowy road" }, "sick_days_bank": { "title": "sick_days_bank", "description": "Sick days bank", "type": "boolean", "example": true }, "paid_absence": { "title": "paid_absence", "description": "Is it a paid absence", "type": "boolean", "example": true }, "pending": { "title": "pending", "description": "Is approval pending", "type": "boolean", "example": false }, "created_at": { "title": "created_at", "description": "Date of the creation", "type": "string", "format": "YYYY-MM-DDTHH:mm:ss.SSSSSZ", "example": "2021-02-19T00:55:29.000000Z" }, "updated_at": { "title": "updated_at", "description": "Date of last modification", "type": "string", "format": "YYYY-MM-DDTHH:mm:ss.SSSSSZ", "example": "2021-02-19T00:55:29.000000Z" }, "updated_by": { "title": "updated_by", "description": "The last user to have updated the model. Required to be embeded using `_embed[]=updatedByUser`", "type": "object", "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/UpdaterResource" } ], "x-embedable": "updatedByUser" }, "created_by": { "title": "created_by", "description": "The user that created the model. Required to be embeded using `_embed[]=createdByUser`", "type": "object", "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/CreatorResource" } ], "x-embedable": "createdByUser" }, "updated_by_user": { "$ref": "#/components/schemas/UpdatedByUserSchema/properties/updated_by_user" }, "created_by_user": { "$ref": "#/components/schemas/CreatedByUserSchema/properties/created_by_user" }, "attachments": { "$ref": "#/components/schemas/AttachmentsSchema/properties/attachments" } }, "type": "object" }, "OvertimeStoreControlRequest": { "required": [ "employee_id", "hours", "date", "type_id" ], "properties": { "employee_id": { "title": "employee_id", "description": "ID of employee", "type": "integer", "example": "5" }, "hours": { "title": "hours", "description": "The duration of the overtime, in hours", "type": "number", "minimum": 0, "example": "2.5" }, "date": { "title": "date", "description": "The date when the overtime take place", "type": "string", "format": "date", "example": "2021-05-28" }, "type_id": { "title": "type_id", "description": "The ID of the overtime type. Please refer to the [OvertimeTypeIndex request](#/Overtimes/getOvertimeTypes) for possible type Ids.", "type": "integer", "example": "3" }, "multiplier": { "title": "multiplier", "description": "Value of each overtime hour. Not all overtime values are permitted for all companies. Please refer to the [OvertimeMultiplierIndex request](#/Overtimes/getMultipliers) for a list of permitted values.", "type": "number", "example": "1.5" }, "approbation_date": { "title": "approbation_date", "description": "Date of approval", "type": "string", "format": "date", "example": "2021-03-04" }, "transfert_to_timesheet": { "title": "transfert_to_timesheet", "description": "Whether the value should be transferred to timesheet", "type": "boolean", "example": "1" }, "notes": { "title": "notes", "description": "Some notes to leave with the overtime", "type": "string", "maxLength": 1000, "example": "I've made more hours than expected this week." } }, "type": "object" }, "UpdateOvertimeRequest": { "required": [ "type_id", "date", "hours" ], "properties": { "employee_id": { "title": "employee_id", "description": "ID of the employee", "type": "integer", "example": "8" }, "hours": { "title": "hours", "description": "The duration of the overtime, in hours.", "type": "number", "minimum": 0, "example": "2.5" }, "date": { "title": "date", "description": "The date when the overtime take place", "type": "string", "format": "date", "example": "2023-04-05" }, "type_id": { "title": "type_id", "description": "Type of overtime. The ID of the overtime type. Please refer to the [OvertimeTypeIndex request](#/Overtimes/getOvertimeTypes) for possible type Ids.", "type": "integer", "example": "2" }, "multiplier": { "title": "multiplier", "description": "Value of each overtime hour. Not all overtime values are permitted for all companies. Please refer to the [OvertimeMultiplierIndex request](#/Overtimes/getMultipliers) for a list of permitted values.", "type": "number", "example": "1.5" }, "approbation_date": { "title": "approbation_date", "description": "Date of approval", "type": "string", "format": "date", "example": "2021-05-30" }, "transfert_to_timesheet": { "title": "transfert_to_timesheet", "description": "Whether the value should be transferred to timesheet", "type": "boolean", "example": "1" }, "notes": { "title": "notes", "description": "Some notes to leave with the overtime", "type": "string", "maxLength": 1000, "example": "I've made more hours than expected this week." } }, "type": "object" }, "StoreVacationControlRequest": { "required": [ "vacation_type_id", "started_at", "ended_at", "distribution", "employee_id" ], "properties": { "vacation_type_id": { "title": "vacation_type_id", "description": "The ID of the vacation type. All possible vacations type can be fetched from the [VacationTypeIndex Request]()", "type": "integer", "example": "1" }, "started_at": { "title": "started_at", "description": "The vacation start date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-07-01" }, "ended_at": { "title": "ended_at", "description": "The vacation end date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-07-15" }, "approved_at": { "title": "approved_at", "description": "Vacation approbation date. Optional, but it must not be empty when the key is sent.", "type": "string", "format": "YYYY-MM-DD", "example": "2021-06-25" }, "paid_vacation": { "title": "paid_vacation", "description": "Is the vacation a paid one? Required only when the requested vacation type has the code `Personal`; optional for every other type.", "type": "boolean", "example": "1" }, "distribution": { "title": "distribution", "description": "Vacation distribution span. This contains the amount of hours or days taken by the vacation, for each day of the period between the started_at and the ended_at property.
It is required to have an equal amount of elements in the property as days in the vacation. A value of 0 indicate a day when no vacation was taken.", "type": "string", "example": "8,8,8,8,7.5" }, "notes": { "title": "notes", "description": "Vacations notes", "type": "string", "example": "To approve" }, "employee_id": { "title": "employee_id", "description": "ID of the employee", "type": "integer", "example": "5" }, "attachment_to_create": { "type": "string", "format": "binary", "nullable": true } }, "type": "object" }, "UpdateEmployeeVacationRequest": { "description": "Class UpdateEmployeeVacationRequest.", "required": [ "employee_id", "vacation_type_id", "started_at", "ended_at", "paid_vacation", "distribution" ], "properties": { "employee_id": { "title": "employee_id", "description": "ID of the employee", "type": "integer", "example": "8" }, "vacation_type_id": { "title": "vacation_type_id", "description": "The ID of the vacation type. All possible vacations type can be fetched from the [VacationTypeIndex Request]()", "type": "integer", "example": "2" }, "started_at": { "title": "started_at", "description": "The vacation start date", "type": "string", "format": "YYYY-MM-DD", "example": "2020-05-01" }, "ended_at": { "title": "ended_at", "description": "The vacation end date", "type": "string", "format": "YYYY-MM-DD", "example": "2020-05-15" }, "paid_vacation": { "title": "paid_vacation", "description": "Whether the vacation is a paid one", "type": "boolean", "example": "1" }, "distribution": { "title": "distribution", "description": "Vacation distribution span. This contains the amount of hours or days taken by the vacation, for each day of the period between the started_at and the ended_at property.
It is required to have an equal amount of elements in the property as days in the vacation. A value of 0 indicate a day where no vacation was taken.", "type": "string", "example": "8,8,8,8,7.5,7.5,8" }, "notes": { "title": "notes", "description": "Vacation notes", "type": "string", "example": "To approve" } }, "type": "object" }, "OvertimeResource": { "description": "Class OvertimeResource.", "properties": { "id": { "title": "id", "description": "The overtime unique ID", "type": "integer", "example": "33" }, "date": { "title": "date", "description": "The overtime date", "type": "string", "format": "YYYY-MM-DD", "example": "2023-04-04" }, "hours": { "title": "hours", "description": "The duration of the overtime, in hours", "type": "string", "example": "5.5" }, "majorated_hours": { "title": "majorated_hours", "description": "The duration of the overtime, in hours multiplied by the multiplier. This is the true value, in hours, of the overtime. Rounded to two decimals and returned as a JSON number.", "type": "number", "example": 5.5 }, "multiplier": { "title": "multiplier", "description": "How the overtime's hours needs to be multiplied to get the total value of the overtime, in hours.", "type": "string", "example": "1.5" }, "notes": { "title": "notes", "description": "the overtime's notes", "type": "string", "example": "Extra hours for busy day" }, "transfert_to_timesheet": { "title": "transfert_to_timesheet", "description": "Whether the overtime should be transferred to timesheet", "type": "string", "example": "1" }, "generated_by_timesheet": { "title": "generated_by_timesheet", "description": "Is overtime generated by the timesheet", "type": "string", "example": "0" }, "restricted_by_timesheet": { "title": "restricted_by_timesheet", "description": "True when the request was generated by a timesheet distribution and the company uses the Folks timesheet. Only the comment and the attachments may then be modified, and the request cannot be deleted.", "type": "boolean", "example": true }, "pending": { "title": "pending", "description": "Is overtime pending approval", "type": "boolean", "example": true }, "approved_at": { "title": "approved_at", "description": "Date of overtime's approval", "type": "string", "format": "YYYY-MM-DD", "example": "2023-05-05" }, "inactivated_at": { "title": "inactivated_at", "description": "Date of overtime's deletion", "type": "string", "format": "YYYY-MM-DD", "example": "2023-05-06" }, "created_at": { "title": "created_at", "description": "Date of overtime's creation", "type": "string", "format": "YYYY-MM-DD hh:mm:ss", "example": "2021-05-04 10:00:00" }, "updated_at": { "title": "updated_at", "description": "Date of last update", "type": "string", "format": "YYYY-MM-DD hh:mm:ss", "example": "2021-05-05 10:00:00" }, "type": { "title": "type", "description": "The type of overtime. Required to be embeded using `_embed[]=type`", "type": "object", "example": "Undefined Bank Hours", "allOf": [ { "$ref": "#/components/schemas/OvertimeTypeResource" } ] }, "employee": { "title": "employee", "description": "The employee related to the overtime.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmbeddedEmployeePartnerResource" } ] }, "updated_by_user": { "$ref": "#/components/schemas/UpdatedByUserSchema/properties/updated_by_user" }, "created_by_user": { "$ref": "#/components/schemas/CreatedByUserSchema/properties/created_by_user" }, "attachments": { "$ref": "#/components/schemas/AttachmentsSchema/properties/attachments" } }, "type": "object" }, "OvertimeTypeResource": { "description": "Class OvertimeTypeResource.", "properties": { "id": { "title": "id", "description": "ID of the overtime type", "type": "integer", "example": "1" }, "code": { "title": "code", "description": "Codename of the overtime type", "type": "string", "example": "Banked Hours" }, "name_en": { "title": "name_en", "description": "English name of the overtime type", "type": "string", "example": "Banked Hours" }, "name_fr": { "title": "name_fr", "description": "French name of the overtime type", "type": "string", "example": "Temps accumulé" }, "is_mappable": { "title": "is_mappable", "description": "Is the type mappable ?", "type": "string", "example": "1" }, "is_increasing": { "title": "is_increasing", "description": "Is the type increasing ?", "type": "boolean", "example": "true" }, "is_last_year_bank": { "title": "is_last_year_bank", "description": "Is the last year bank ?", "type": "boolean", "example": "false" }, "is_limited_to_24h": { "title": "is_limited_to_24h", "description": "Could we go over 24h for this type ?", "type": "boolean", "example": "false" }, "has_multiplier": { "title": "has_multiplier", "description": "Has the type some multipliers ? (1, 1.5, 2)", "type": "boolean", "example": "true" }, "is_displayed": { "title": "is_displayed", "description": "Is the overtime type displayed ?", "type": "boolean", "example": "true" } }, "type": "object" }, "VacationInDepthResource": { "description": "Class VacationInDepthResource.", "properties": { "id": { "title": "id", "description": "Vacation's id", "type": "integer", "example": "33" }, "employee": { "title": "employee", "description": "The employee related to the vacation.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmbeddedEmployeePartnerResource" } ] }, "type": { "title": "type", "description": "The type of the vacation. Required to be embeded using `_embed[]=type`", "type": "object", "allOf": [ { "$ref": "#/components/schemas/VacationTypeResource" } ], "x-embedable": "reason" }, "started_at": { "title": "started_at", "description": "Vacation start date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-07-01" }, "ended_at": { "title": "ended_at", "description": "Vacation end date", "type": "string", "format": "YYYY-MM-DD", "example": "2021-07-15" }, "notes": { "title": "notes", "description": "Vacation notes", "type": "string", "example": "To approve" }, "pending": { "title": "pending", "description": "Whether the vacation approval is pending", "type": "boolean", "example": "true" }, "paid_vacation": { "title": "paid_vacation", "description": "Wheter the vacation is a paid one", "type": "boolean", "example": "true" }, "duration": { "title": "duration", "description": "The total duration of the vacations in days or in hours, depending on the 'unit' property", "type": "string", "example": "15" }, "distribution": { "title": "distribution", "description": "A list of number, separated by commas, that indicate how many hours / days are used for each day from the start date of the vacation to the end date", "type": "string", "example": "8,8,8,8,8,8,8,8,8,8,8" }, "unit": { "title": "unit", "description": "The unit used to define the duration and distribution of the vacation. It is the same for all vacations of the same company", "type": "string", "enum": [ "hours", "days" ], "example": "hours" }, "inactivated_at": { "title": "inactivated_at", "description": "Vacation soft-deleted date", "type": "string", "format": "YYYY-MM-DD hh:mm:ss", "example": "2021-08-25 00:00:00" }, "approved_at": { "title": "approved_at", "description": "Vacation approval date", "type": "string", "example": "2021-06-25" }, "updated_at": { "title": "updated_at", "description": "Last update date", "type": "string", "example": "2018-09-05T20:14:53.000000Z" }, "created_at": { "title": "created_at", "description": "The vacation creation date", "type": "string", "example": "2018-09-05T20:14:53.000000Z" }, "updated_by_user": { "$ref": "#/components/schemas/UpdatedByUserSchema/properties/updated_by_user" }, "created_by_user": { "$ref": "#/components/schemas/CreatedByUserSchema/properties/created_by_user" }, "attachments": { "$ref": "#/components/schemas/AttachmentsSchema/properties/attachments" } }, "type": "object" }, "VacationTypeResource": { "description": "Class VacationTypeResource.", "properties": { "id": { "title": "id", "description": "ID of the vacation type", "type": "integer", "example": "1" }, "name_en": { "title": "name_en", "description": "English name of the vacation type", "type": "string", "example": "Vacation" }, "name_fr": { "title": "name_fr", "description": "French name of the vacation type", "type": "string", "example": "Vacances" }, "code": { "title": "code", "description": "Codename of the vacation type", "type": "string", "example": "vacation" }, "is_countable": { "title": "is_countable", "description": "Whether the vacation type is countable. Returned as the string `1` or `0`, not a boolean.", "type": "string", "example": "1" }, "is_displayed": { "title": "is_displayed", "description": "Show if the current resource is displayed or hidden", "type": "boolean", "example": "true" } }, "type": "object" }, "CountryResource": { "title": "CountryResource", "properties": { "id": { "title": "id", "description": "Country's id", "type": "integer", "example": "151" }, "abbreviation": { "title": "abbreviation", "description": "Country's abbreviation", "type": "string", "example": "BE" }, "name_fr": { "title": "name_fr", "description": "Country's name in french", "type": "string", "example": "Belgique" }, "name_en": { "title": "name_en", "description": "Country's name in english", "type": "string", "example": "Belgium" } }, "type": "object" }, "ProvinceResource": { "title": "ProvinceResource", "properties": { "id": { "title": "id", "description": "The province Id", "type": "integer", "example": "1" }, "name_fr": { "title": "French name", "description": "The province name in french", "type": "string", "example": "Québec" }, "name_en": { "title": "English name", "description": "The province name in english", "type": "string", "example": "Quebec" }, "abbreviation": { "title": "abbreviation", "description": "The abbreviation of the province", "type": "string", "example": "QC" }, "tvh": { "title": "TVH", "description": "The percentage of taxes for provincial taxes", "type": "number", "example": "10" }, "country": { "title": "County", "description": "The country of the province", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CountryResource" } ] } }, "type": "object" }, "CreatedByUserSchema": { "title": "createdByUser", "description": "Reference the user that created the model", "properties": { "created_by_user": { "title": "created_by_user", "description": "The user that created the model. Required to be embeded using `_embed[]=createdByUser`", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CreatorResource" } ], "x-embedable": "createdByUser" } }, "type": "object" }, "TranslatableNameSchema": { "properties": { "fr": { "title": "French", "description": "French version of the name.", "type": "string", "example": "Nom français" }, "en": { "title": "English", "description": "English version of the name.", "type": "string", "example": "english name" } }, "type": "object" }, "UpdatedByUserSchema": { "title": "UpdatedByUser", "description": "Reference the user that updated the model", "properties": { "updated_by_user": { "title": "updated_by_user", "description": "The last user to have updated the model. Required to be embeded using `_embed[]=updatedByUser`", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UpdaterResource" } ], "x-embedable": "updatedByUser" } }, "type": "object" } }, "parameters": { "page": { "name": "page", "in": "query", "description": "The current pagination page to fetch.", "required": false, "schema": { "type": "integer" }, "example": 3 }, "limit": { "name": "limit", "in": "query", "description": "The amount of data to be returned per pagination page. If omitted, the default value is 30. Use -1 to disable pagination all together. Note that -1 also changes the response shape: the whole result set is returned without the `meta` pagination block.", "required": false, "schema": { "type": "integer" }, "example": 100 }, "order": { "name": "order", "in": "query", "description": "The order of the sort_by parameter. The values are sorted ASC by default.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "example": "desc" } }, "securitySchemes": { "partners": { "type": "oauth2", "description": "OAuth 2.0 flow for externals partners", "flows": { "clientCredentials": { "tokenUrl": "/oauth/token", "refreshUrl": "/token/refresh", "scopes": { "absences:read": "access absences for company", "absences:write": "create or update absences for company", "absences:destroy": "delete absence for company", "absences:status:read": "access status for a given absence", "absences:status:write": "update status for a given absence", "overtimes:read": "access overtimes for company", "overtimes:write": "create or update overtimes for company", "overtimes:destroy": "delete overtime for company", "overtimes:status:read": "access status for a given overtime", "overtimes:status:write": "update status for a given overtime", "vacations:read": "access vacations for company", "vacations:write": "create or update vacation for company", "vacations:destroy": "delete vacation for company", "vacations:status:read": "access status for a given vacation", "vacations:status:write": "update status for a given vacation", "balances:read": "access balances for an employee", "custom-fields:read": "access custom fields for a company", "custom-fields:write": "create or update custom fields for an employee", "custom-fields:destroy": "delete custom field value for an employee", "admin:read": "Read access for departments, positions and working sites of the company. This is an alternative to the per-resource read scopes: the three list and show endpoints accept either admin:read or their own departments:read, positions:read or workingSites:read scope, so a token carrying only admin:read can read all three. The endpoint documentation names the per-resource scope, which is the preferred one for new integrations.", "positions:read": "read access for positions", "positions:write": "write access for positions", "positions:destroy": "destroy access for positions", "departments:read": "read access for departments", "departments:write": "write access for departments", "departments:destroy": "destroy access for departments", "workingSites:read": "read access for working sites", "workingSites:write": "write access for working sites", "workingSites:destroy": "destroy access for working sites", "employees:read": "access employees for company", "employees:write": "create or update employee for company", "employees:destroy": "delete employee for company", "edm:read": "access edm documents and folders for company", "edm:write": "create or update edm documents for company", "edm:destroy": "delete edm documents for company", "edm:folder:write": "create or update edm folders for company", "edm:folder:destroy": "delete edm folders for company" } } } } } }, "tags": [ { "name": "Authentication", "description": "API Endpoints for Authentication" }, { "name": "Employees", "description": "API Endpoints for Employees" }, { "name": "Absences", "description": "API Endpoints for Absences" }, { "name": "Vacations", "description": "API Endpoints for Vacations" }, { "name": "Overtimes", "description": "API Endpoints for Overtimes" }, { "name": "Custom Fields", "description": "API Endpoints for Custom Fields" }, { "name": "Departments", "description": "Departments" }, { "name": "Positions", "description": "Positions" }, { "name": "Working Sites", "description": "Working Sites" }, { "name": "EDMDocuments", "description": "EDMDocuments" }, { "name": "EDMFolders", "description": "EDMFolders" }, { "name": "Absences Status", "description": "Absences Status" }, { "name": "Balance", "description": "Balance" }, { "name": "Vacations Status", "description": "Vacations Status" } ], "security": [ { "partners": [ "absences:read", "absences:write", "absences:destroy", "absences:status:read", "absences:status:write", "overtimes:read", "overtimes:write", "overtimes:destroy", "overtimes:status:read", "overtimes:status:write", "vacations:read", "vacations:write", "vacations:destroy", "vacations:status:read", "vacations:status:write", "balances:read", "custom-fields:read", "custom-fields:write", "custom-fields:destroy", "admin:read", "positions:read", "positions:write", "positions:destroy", "departments:read", "departments:write", "departments:destroy", "workingSites:read", "workingSites:write", "workingSites:destroy", "employees:read", "employees:write", "employees:destroy", "edm:read", "edm:write", "edm:destroy", "edm:folder:write", "edm:folder:destroy" ] } ] }