--- title: "Creates a cost estimation of employments" method: POST path: "/v1/cost-calculator/estimation" tags: ["Cost Calculator"] --- # Creates a cost estimation of employments `POST /v1/cost-calculator/estimation` ## Request - Base URL: `https://gateway.remote.com` - URL: `https://gateway.remote.com/v1/cost-calculator/estimation` - Auth: one of: - OAuth 2 - Authorization code: `/auth/oauth2/authorize` - Token URL: `/auth/oauth2/token` - OAuth 2 - Client credentials - Token URL: `/auth/oauth2/token` - OAuth 2 - Client credentials - Token URL: `/auth/oauth2/token` - OAuth 2 - Client credentials - Token URL: `/auth/oauth2/token` - HTTP bearer - HTTP bearer ## Authentication This endpoint accepts any one of the following token types: - **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained through the Authorization Code flow or the Refresh Token flow, acting as the user who authorized it. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners). - **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion). - **Client credentials access token** (`OAuth2ClientCredentials`) — obtained through the Client Credentials flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners). - **Employee-scoped access token** (`OAuth2Assertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion). - **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers). - **Client token** (`ClientToken`) — a partner `client_token`, accepted only on the endpoints that list it. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners). ## Request body - CostCalculatorEstimateParams: Parameters for generating a cost estimate for one or more employments across different countries/regions. - `company_name` string: The company name, used for labeling in PDF/CSV exports. - `employer_currency_slug` string, required: The ISO 4217 currency code for the employer's preferred currency (e.g., "USD"). All costs will be converted to this currency. - `employments` CostCalculatorEmploymentParam[], required: One or more employments to estimate costs for. - `age` integer: The employee's age. Used in some countries to calculate age-dependent benefits or contributions. - `annual_gross_salary` integer: The annual gross salary in the region's local currency, in cents. Provide this OR `annual_total_cost`, not both. - `annual_gross_salary_in_employer_currency` integer: The annual gross salary in the employer's preferred currency, in cents. Used when you want to specify salary in a different currency than the region's. - `annual_total_cost` integer: The target total annual cost (salary + all employer costs) in the region's local currency, in cents. The calculator will derive the gross salary. Provide this OR `annual_gross_salary`, not both. - `annual_total_cost_in_employer_currency` integer: The target total annual cost in the employer's preferred currency, in cents. - `benefits` CostCalculatorBenefitParam[]: Specific benefit selections to include in the estimate. - `benefit_group_slug` string, required: The unique identifier (slug) of the benefit group to include in the estimate. - `benefit_tier_slug` string, required: The unique identifier (slug) of the benefit tier within the group. Determines the level of coverage and cost. - `discount` CostCalculatorDiscount: Configuration for applying a discount to a cost estimate. Provide either an `amount` or `percent` — not both. - `amount` integer: The fixed discount amount in cents. Mutually exclusive with `percent`. - `months` integer: The number of months the discount applies to (1-12). Defaults to 12. - `percent` number: The discount as a decimal fraction (e.g., 0.1 for 10%). Mutually exclusive with `amount`. - `quoted_amount` integer: The originally quoted amount before discount, in cents. - `text` string, required: A human-readable label for the discount (e.g., "10% Discount"). - `employment_term` 'fixed' | 'indefinite' - `region_slug` string, required: The unique identifier (slug) of the region/country for this employment. Required. - `regional_to_employer_exchange_rate` string: A custom exchange rate from the regional currency to the employer currency. If not provided, the current market rate is used. - `title` string: An optional label for this employment in the estimate (e.g., the job title or role name). - `global_discount` CostCalculatorDiscount: Configuration for applying a discount to a cost estimate. Provide either an `amount` or `percent` — not both. - `amount` integer: The fixed discount amount in cents. Mutually exclusive with `percent`. - `months` integer: The number of months the discount applies to (1-12). Defaults to 12. - `percent` number: The discount as a decimal fraction (e.g., 0.1 for 10%). Mutually exclusive with `amount`. - `quoted_amount` integer: The originally quoted amount before discount, in cents. - `text` string, required: A human-readable label for the discount (e.g., "10% Discount"). - `include_benefits` boolean: Whether to include benefit costs in the estimate. Defaults to false if not provided. - `include_cost_breakdowns` boolean: Whether to include detailed cost breakdowns (individual contributions, benefits, etc.) in the response. - `include_management_fee` boolean: Whether to include Remote's management fee in the total cost calculation. - `include_premium_benefits` boolean: Whether to include premium benefit options in the estimate. ## Response `200` Success - CostCalculatorEstimateResponse - `data` object, required - `employments` CostCalculatorEmployment[] - `country` MinimalCountry, required: A lightweight country representation with basic identification fields. - `alpha_2_code` string, required: The ISO 3166-1 alpha-2 country code (e.g., "PT", "US", "GB"). - `code` string, required: The ISO 3166-1 alpha-3 country code (e.g., "PRT", "USA", "GBR"). This is the primary code used across the Remote API. - `features` string[]: Feature flags indicating which Remote services are available in this country. - `name` string, required: The country's full English name. - `slug` string, required: A unique URL-friendly identifier for the country. - `country_benefits_details_url` string, nullable, required: A link to Remote's guide on benefits available in this country. Null if not available. - `country_guide_url` string, nullable, required: A link to Remote's country hiring guide. Null if not available. - `employer_currency_costs` CostCalculatorCosts, required - `annual_benefits_breakdown` CostCalculatorCost[]: The list of all annual benefit costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `annual_benefits_total` integer: The annual benefits total that a company must pay for this employment - `annual_contributions_breakdown` CostCalculatorCost[]: The list of all annual employer contribution costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `annual_contributions_total` integer, required: The annual contributions that a company must pay for this employment - `annual_gross_salary` integer, required: The annual gross salary that the employee is going to earn - `annual_indirect_tax` integer: The annual indirect tax that a company must pay for this employment - `annual_management_fee` integer: The annual management fees - `annual_total` integer, required: The annual gross salary + annual contributions + annual fee (monthly fee * 12) + extra statutory payments if applicable - `currency` Currency, required: The type of money in general use in a particular country - `code` string, required - `name` string - `slug` string, required - `symbol` string, required - `discount` CostCalculatorDiscountResponse: The discount applied to a cost estimate, showing the annual and monthly savings. - `annual_amount` integer, required: The annual discount amount in cents. - `monthly_amount` integer, required: The monthly discount amount in cents. - `months` integer, required: The number of months the discount applies to. - `text` string, required: A human-readable label for the discount. - `extra_statutory_payments_breakdown` CostCalculatorCost[]: The list of all annual extra statutory payment costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `extra_statutory_payments_total` integer, required: 13th month salary, this happens for countries such as Philippines - `fringe_benefits_tax_breakdown` CostCalculatorCost[]: The list of all annual fringe benefits tax costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `fringe_benefits_tax_total` integer: Estimated tax on employer-paid benefit premiums (e.g. New Zealand FBT) - `monthly_benefits_breakdown` CostCalculatorCost[]: The list of all monthly benefit costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `monthly_benefits_total` integer: The benefits total that the company pays monthly - `monthly_contributions_breakdown` CostCalculatorCost[]: The list of all monthly employer contribution costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `monthly_contributions_total` integer, required: The contributions that the company pays monthly - `monthly_fringe_benefits_tax_breakdown` CostCalculatorCost[]: The list of all monthly fringe benefits tax costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `monthly_fringe_benefits_tax_total` integer: Monthly estimated tax on employer-paid benefit premiums (e.g. New Zealand FBT) - `monthly_gross_salary` integer, required: The gross monthly salary for the Employee - `monthly_indirect_tax` integer: The monthly indirect tax that a company must pay for this employment - `monthly_management_fee` integer: The monthly management fees - `monthly_tce` integer, required: Monthly gross salary + monthly contributions (doesn't include fee) - `monthly_total` integer, required: Monthly gross salary + monthly contributions + monthly fee - `has_extra_statutory_payment` boolean, required: Whether this country has extra statutory payments (e.g., 13th month salary in the Philippines). - `has_fringe_benefits_tax` boolean: Whether this country has a fringe benefits tax on employer-paid benefit premiums (e.g. New Zealand). - `indirect_tax_summary` CostCalculatorIndirectTaxSummary, nullable: How local indirect tax applies to this employment. Null when the country has no indirect tax. - `description` string, required: How indirect tax applies in this country. - `estimate` string, required: Short text shown as the indirect tax cost. - `guide_url` string, required: Help center article explaining local country indirect taxes. - `minimum_onboarding_time` number, nullable, required: The minimum number of business days required to onboard an employee in this country. Null if not determined. - `region` MinimalRegion, required - `child_regions` MinimalRegion[] - `code` string, nullable - `name` string, required - `slug` string, required - `status` 'active' | 'inactive', nullable - `regional_currency_costs` CostCalculatorCosts, required - `annual_benefits_breakdown` CostCalculatorCost[]: The list of all annual benefit costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `annual_benefits_total` integer: The annual benefits total that a company must pay for this employment - `annual_contributions_breakdown` CostCalculatorCost[]: The list of all annual employer contribution costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `annual_contributions_total` integer, required: The annual contributions that a company must pay for this employment - `annual_gross_salary` integer, required: The annual gross salary that the employee is going to earn - `annual_indirect_tax` integer: The annual indirect tax that a company must pay for this employment - `annual_management_fee` integer: The annual management fees - `annual_total` integer, required: The annual gross salary + annual contributions + annual fee (monthly fee * 12) + extra statutory payments if applicable - `currency` Currency, required: The type of money in general use in a particular country - `code` string, required - `name` string - `slug` string, required - `symbol` string, required - `discount` CostCalculatorDiscountResponse: The discount applied to a cost estimate, showing the annual and monthly savings. - `annual_amount` integer, required: The annual discount amount in cents. - `monthly_amount` integer, required: The monthly discount amount in cents. - `months` integer, required: The number of months the discount applies to. - `text` string, required: A human-readable label for the discount. - `extra_statutory_payments_breakdown` CostCalculatorCost[]: The list of all annual extra statutory payment costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `extra_statutory_payments_total` integer, required: 13th month salary, this happens for countries such as Philippines - `fringe_benefits_tax_breakdown` CostCalculatorCost[]: The list of all annual fringe benefits tax costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `fringe_benefits_tax_total` integer: Estimated tax on employer-paid benefit premiums (e.g. New Zealand FBT) - `monthly_benefits_breakdown` CostCalculatorCost[]: The list of all monthly benefit costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `monthly_benefits_total` integer: The benefits total that the company pays monthly - `monthly_contributions_breakdown` CostCalculatorCost[]: The list of all monthly employer contribution costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `monthly_contributions_total` integer, required: The contributions that the company pays monthly - `monthly_fringe_benefits_tax_breakdown` CostCalculatorCost[]: The list of all monthly fringe benefits tax costs - `amount` integer, required: The cost amount in cents. - `description` string, nullable, required: A human-readable explanation of how this cost is calculated or what it covers. - `name` string, required: The name of this cost item (e.g., "Health Insurance", "Social Security"). - `zendesk_article_id` string, nullable, required: The ID of the related help article, if available. - `zendesk_article_url` string, nullable, required: A link to a help article with more information about this cost, if available. - `monthly_fringe_benefits_tax_total` integer: Monthly estimated tax on employer-paid benefit premiums (e.g. New Zealand FBT) - `monthly_gross_salary` integer, required: The gross monthly salary for the Employee - `monthly_indirect_tax` integer: The monthly indirect tax that a company must pay for this employment - `monthly_management_fee` integer: The monthly management fees - `monthly_tce` integer, required: Monthly gross salary + monthly contributions (doesn't include fee) - `monthly_total` integer, required: Monthly gross salary + monthly contributions + monthly fee ## Other responses - `404`: Not Found - `422`: Unprocessable Entity --- [API](https://skmtc.dev/remote-com/apis/pay-compensation.md) - [All operations](https://skmtc.dev/remote-com/apis/pay-compensation/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/pay-compensation/revisions/ec29f1865c5e?raw)