--- updatedAt: 2026-05-14T14:32:15.000Z agentTools: projectIndex: https://docs.oysterhr.com/v0.1/llms.txt --- # Retrieve monthly cost estimates for an employment Retrieve monthly cost estimates for an employment # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Endpoints", "version": "v0.1" }, "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "employmentCostEstimate": { "type": "object", "properties": { "engagement": { "type": "object", "properties": { "id": { "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "id", "countryCode" ] }, "grossSalaryAmount": { "type": "object", "$ref": "#/components/schemas/amount" }, "mandatoryCosts": { "type": "object", "nullable": true, "properties": { "totalAmount": { "type": "object", "$ref": "#/components/schemas/amount" }, "constituents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string", "nullable": true, "description": "Machine-readable key for a variable compensation (for example SIGN_ON_BONUS). Null for cost lines that are not variable compensations, such as benefits and taxes. Not unique: the same label can exist under both BONUS and ALLOWANCE, and several compensations can share a label, so combine it with `category`. Match on this rather than on `name`, which is display copy and may change. Statutory variable compensations are listed here and not in `additionalCosts`." }, "category": { "type": "string", "enum": [ "SOCIAL_SECURITY", "ACCRUAL", "ALLOWANCE", "EMPLOYER_BENEFIT", "BONUS", "BENEFIT" ] }, "amount": { "type": "object", "$ref": "#/components/schemas/amount" } }, "required": [ "name", "label", "category", "amount" ] } } }, "required": [ "totalAmount", "constituents" ] }, "additionalCosts": { "type": "object", "nullable": true, "properties": { "totalAmount": { "type": "object", "$ref": "#/components/schemas/amount" }, "constituents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string", "nullable": true, "description": "Machine-readable key for a variable compensation (for example SIGN_ON_BONUS). Null for cost lines that are not variable compensations, such as benefits and taxes. Not unique: the same label can exist under both BONUS and ALLOWANCE, and several compensations can share a label, so combine it with `category`. Match on this rather than on `name`, which is display copy and may change." }, "frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "BIANNUAL", "YEARLY", "ONE_TIME" ] }, "guaranteed": { "type": "boolean" }, "prorated": { "type": "boolean" }, "category": { "type": "string", "enum": [ "BONUS", "ALLOWANCE", "BENEFIT" ] }, "amount": { "type": "object", "$ref": "#/components/schemas/amount" }, "baseAmount": { "type": "object", "$ref": "#/components/schemas/amount" } }, "required": [ "name", "label", "category", "amount", "guaranteed", "prorated", "baseAmount", "frequency" ] } } }, "required": [ "totalAmount", "constituents" ] }, "oysterFee": { "type": "object", "nullable": true, "properties": { "amountInEmploymentCurrency": { "type": "object", "$ref": "#/components/schemas/amount" }, "amountInCompanyCurrency": { "type": "object", "$ref": "#/components/schemas/amount" } }, "required": [ "amountInEmploymentCurrency", "amountInCompanyCurrency" ] }, "vat": { "type": "object", "nullable": true, "properties": { "percentage": { "type": "string" }, "amount": { "type": "object", "$ref": "#/components/schemas/amount" } }, "required": [ "percentage", "amount" ] }, "totalCostsAmount": { "type": "object", "$ref": "#/components/schemas/amount" }, "taxesAndSocialSecurity": { "type": "object", "nullable": true, "properties": { "totalAmount": { "type": "object", "$ref": "#/components/schemas/amount" }, "constituents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string", "enum": [ "SOCIAL_SECURITY", "INCOME_TAX", "EMPLOYEE_BENEFIT", "TAX_CREDIT", "SOLIDARITY_TAX" ] }, "amount": { "type": "object", "$ref": "#/components/schemas/amount" } }, "required": [ "name", "category", "amount" ] } } }, "required": [ "totalAmount", "constituents" ] }, "netSalaryAmount": { "type": "object", "$ref": "#/components/schemas/amount" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "engagement", "grossSalaryAmount", "mandatoryCosts", "additionalCosts", "oysterFee", "vat", "totalCostsAmount", "taxesAndSocialSecurity", "netSalaryAmount", "notes" ] }, "amount": { "type": "object", "properties": { "decimal": { "type": "string", "pattern": "^\\d+([.]\\d+)?$" }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "decimal", "currencyCode" ] } } }, "paths": { "/v0.1/hiring/employments/{id}/cost_estimates/monthly": { "get": { "summary": "Retrieve monthly cost estimates for an employment", "tags": [ "Cost Estimate" ], "description": "Retrieve monthly cost estimates for an employment", "security": [ { "bearer_auth": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "Employment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "examples": { "Successful": { "value": { "data": { "engagement": { "id": "A5540727", "countryCode": "PT" }, "grossSalaryAmount": { "decimal": "2862.00", "currencyCode": "EUR" }, "mandatoryCosts": { "totalAmount": { "decimal": "701.00", "currencyCode": "EUR" }, "constituents": [ { "name": "Social Tax", "category": "SOCIAL_SECURITY", "amount": { "decimal": "680.00", "currencyCode": "EUR" }, "label": null }, { "name": "Labor Accident Insurance", "category": "SOCIAL_SECURITY", "amount": { "decimal": "22.00", "currencyCode": "EUR" }, "label": null } ] }, "additionalCosts": { "totalAmount": { "decimal": "3.00", "currencyCode": "EUR" }, "constituents": [ { "name": "Vacation bonus", "category": "BONUS", "amount": { "decimal": "1.00", "currencyCode": "EUR" }, "label": "VACATION_BONUS", "guaranteed": false, "frequency": "YEARLY", "prorated": true, "baseAmount": { "decimal": "10.00", "currencyCode": "EUR" } }, { "name": "Car", "category": "ALLOWANCE", "amount": { "decimal": "2.00", "currencyCode": "EUR" }, "label": "CAR", "guaranteed": false, "frequency": "QUARTERLY", "prorated": true, "baseAmount": { "decimal": "5.00", "currencyCode": "EUR" } } ] }, "oysterFee": { "amountInEmploymentCurrency": { "decimal": "666.00", "currencyCode": "EUR" }, "amountInCompanyCurrency": { "decimal": "699.00", "currencyCode": "USD" } }, "vat": { "percentage": "0", "amount": { "decimal": "0.00", "currencyCode": "EUR" } }, "totalCostsAmount": { "decimal": "4232.00", "currencyCode": "EUR" }, "taxesAndSocialSecurity": { "totalAmount": { "decimal": "1099.00", "currencyCode": "EUR" }, "constituents": [ { "name": "Social Security", "category": "SOCIAL_SECURITY", "amount": { "decimal": "315.00", "currencyCode": "EUR" } }, { "name": "Personal Income Tax", "category": "INCOME_TAX", "amount": { "decimal": "784.00", "currencyCode": "EUR" } } ] }, "netSalaryAmount": { "decimal": "1763.00", "currencyCode": "EUR" }, "notes": [ "A refundable deposit that equals one-month of the total cost of employment for this new Team Member is required", "This deposit is refundable after the Team Member has been with Oyster for 12 months." ] } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/employmentCostEstimate" } }, "required": [ "data" ] } } } } } } } }, "servers": [ { "url": "https://api.oysterhr.com", "description": "Production server" }, { "url": "https://api-sandbox.oysterhr.com", "description": "Sandbox server" } ] } ```