The Cost Estimates API is an API subscription that enables Cost Estimate and What-If Cost Estimate to be created, calculated, and exchanged between AssignmentPro and other systems.
Note - Cost Estimate and What-If Cost Estimate calculations created with API requests will decrement relevant click counters and licensing modules. |
Use of this feature requires the following:
Client's webserver is configured to use the API - please contact your Equus representative. Configuration is completed by the Equus Development Team.
In AssignmentPro, create an API subscriber with a subscription to the Cost Estimate API (select Cost Estimates from the list of available API Subscriptions) and generate GUID and Secret Key for the API subscriber.
The appropriate defaulting values must be properly configured first (e.g. Cost Estimate & WICE Templates, Exchange Rate, Compensation Data Repository, etc.)
Cost Estimate reports can be pre-configured with their parameters ahead of time under the Cost Estimate Template API Automation Configuration Tab.
Flow diagram of the Cost Estimates API
Cost Estimate Domain Endpoints
The following /domain endpoints can be retrieved with a GET request:
Cost Estimate
Cost Estimate Calc Error
Cost Estimate Currency True Up
Cost Estimate Document
Cost Estimate Line Item
Cost Estimate Process Batch
Cost Estimate Process Batch Log
Cost Estimate Template
Cost Estimate Yearly Input
Tax Estimator
What If Cost Estimate
The following /domain endpoints can be created with POST requests, updated with PATCH requests, retrieved with GET requests, or deleted with DELETE requests
Compensation Data Repository
Cost Estimate Operation Endpoints
To create, calculate, and retrieve a Cost Estimate, use the following Cost Estimate Operation Endpoints:
1. POST Cost Estimate
This endpoint initially creates the Cost Estimate and populates Calculation Inputs and Line Items when defaults are applicable
Requires the following fields to create:
Effective Date
Assignment ID
Cost Estimate Template ID
Calculation Inputs and Line Items are populated when defaults are applicable
Post Year amount isn’t calculated on initial creation. Post Year is calculated in the Cost Estimate Enqueue endpoint
For posting lookup values, you will need to either provide the EQ code in the payload or pass the lookup display value in the URL
EX: For Marital Status, the API Subscriber can pass EQMSSN (single) in the payload
or the API Subscriber can include costEstimate?lookup[costEstimate][displayValue]=maritalStatus in their URL then pass Single in the payload
2. PATCH Cost Estimate
This endpoint updates an Assignment’s Cost Estimate writable General Information or Tax Estimator Inputs. A Cost Estimate API Subscriber can get a Cost Estimate’s Tax Estimator IDs and check whether the Tax Estimator is locked or visible by the initial POST Cost Estimate response or by retrieving the Cost Estimate through the operation endpoints. API subscribers can also view which fields can be patched in the Swagger documentation.
Requires a Cost Estimate ID
Writable General Information of the Cost Estimate can be updated
These are top-level attributes in the Cost Estimate API
Writable Tax Estimator Inputs of the Cost Estimate can be updated
isReadOnly needs to be false and isVisible needs to be true for it to be updated
Exchange Rates cannot be updated through the Cost Estimate API. Appropriate configuration will need to be defaulted beforehand
Line Items cannot be updated through this endpoint. To default an Assignment’s Line Items, use the Compensation Data Repository Endpoints and setup the appropriate configuration to pull Compensation Data Repository entries into a Cost Estimate Template.
3. POST Enqueue Cost Estimate Process Batch
This endpoint enqueues a Cost Estimate for batch processing. The batch process will perform tax-related calculations and generate documents from the Cost Estimate template’s API Automation Configuration.
Requires the following fields to enqueue for batch processing:
Cost Estimate ID
Calculate flag set to true
GenerateReports flag set to true
Performs tax-related calculations
API requests will decrement relevant click counters and licensing modules
Generates Cost Estimate reports based on the Cost Estimate Template’s API Automation Configuration
Returns a Cost Estimate Process Batch ID which can be used to retrieve the status of the Cost Estimate in processing
Whenever a Cost Estimate document is generated, it will remove any prior documents associated with the Cost Estimate and substitute them with the new document.
API Subscribers have the option to provide a culture value using the reportCulture field. This field will then format the Cost Estimate document according to the specified culture
The culture code can be passed as a string following the RFC 4646 standard, which serves as an identification for a language
4. GET Cost Estimate
This endpoint returns the Cost Estimate
Requires Cost Estimate ID
Returns Cost Estimate in the form of a JSON object
5. GET Cost Estimate’s Status That is Enqueued for Calculation
Requires Cost Estimate Process ID
Returns status of the Cost Estimate enqueued for calculation
What-If Cost Estimate Operation Endpoints
To create, calculate, and retrieve a What-If, use the following What-If Operation Endpoints:
1. POST What-If Cost Estimate
This endpoint initially creates the What-If and populates Calculation Inputs and Line Items when defaults are applicable
Requires the following fields to create
Base Currency
Effective Date
Optionally, Start Date and End Date can also be provided
If only Start Date is given, it will create a 1-year What-If Cost Estimate that is 1 year after the Start Date. If the What-If Cost Estimate Template is configured to support Post Year, then it will create a 1-year What-If Cost Estimate plus Post Year
If only the End Date is given, it will create a 1-year What-If Cost Estimate that is 1 year before the End Date. If the What-If Cost Estimate Template is configured to support Post Year, then it will create a 1-year What-If Cost Estimate plus Post Year
Home Family Size
Requires minimum family size of 1
Host Family Size
Requires minimum family size of 1
Initial Base Salary
Marital Status
Company ID
Cost Estimate Template ID
If Work Time in Home Country is not given, it will default to 0
If Work Time in Host country is not given, it will default to 100
What-If Cost Estimate endpoint does not support User Report Inputs. User Report inputs must be configured with defaulted values
Calculation Inputs and Line Items are populated when defaults are applicable
Post Year amount isn’t calculated on initial creation. Post Year is calculated in the Cost Estimate Enqueue endpoint
For posting lookup values, you will need to either provide the EQ code in the payload or pass the lookup display value in the URL
EX: For Marital Status, the API Subscriber can pass EQMSSN (single) in the payload
or the API Subscriber can include whatIfCostEstimate?lookup[costEstimate][displayValue]=maritalStatus in their URL then pass Single in the payload
CE API currently does not have the capability to create What-If Cost Estimate documents. If the API Subscriber creates a What-If Cost Estimate document through the API, it will be notified with an error.
The CE API does not support admin review. If the What-If Cost Estimate is configured to require admin action then you will see this prompt in AssignmentPro. The API Subscriber will still be able to retrieve the What-If Cost Estimate results in the GET request
2. PATCH What-If Cost Estimate
This endpoint updates an Assignment’s Cost Estimate writable General Information or Tax Estimator Inputs. A Cost Estimate API Subscriber can get a Cost Estimate’s Tax Estimator ids and check whether the Tax Estimator is locked or visibile by the initial POST Cost Estimate reponse or by retrieving the Cost Estimate through the operation endpoints. API subscribers can also view which fields can be patched in the Swagger documentation.
Requires a Cost Estimate ID
Writable General Information of the What-If Cost Estimate can be updated
These are top-level attributes in the Cost Estimates API
Writable Tax Estimator Inputs of the What-If Cost Estimate can be updated
isReadOnly needs to be false and isVisible needs to be true for it to be updated
Exchange Rates cannot be updated through the Cost Estimate API. Appropriate configuration will need to be defaulted beforehand
3. POST Cost Estimate Process Batch
This endpoint enqueues a Cost Estimate for batch processing. The batch process will perform tax-related calculations and generate documents from the Cost Estimate Template's What-If Cost Estimate Report Configuration
Requires the following fields to enqueue for batch processing:
Cost Estimate ID
A What-If Cost Estimate is a child of a Cost Estimate and has a Cost Estimate ID. In the enqueue endpoint, provide the Cost Estimate ID as opposed to the What-If Cost Estimate ID
Calculate flag set to true
GenerateReports flag set to true
Performs tax-related calculations
API requests will decrement relevant click counters and licensing modules
Generates What-If Cost Estimate reports based on the What-If Cost Estimate report configuration in the Cost Estimate Template
Returns a Cost Estimate Process Batch ID which can be used to retrieve the status of the Cost Estimate in processing
Whenever a What-If Cost Estimate document is generated, it will remove any prior documents associated with the What-If Cost Estimate and substitute them with the new document.
API Subscribers have the option to provide a culture value using the reportCulture field. This field will then format the Cost Estimate document according to the specified culture
The culture code that can be passed as a string following the RFC 4646 standard, which serves as an identification for a language
4. GET What-If Cost Estimate
This endpoint returns the Cost Estimate
Requires What-If Cost Estimate ID
Returns What-If Cost Estimate in the form of a JSON object
Note - What-If Cost Estimates are children of Cost Estimates. The API Subscriber can also retrieve a What-If Cost Estimate’s information that’s available in the Cost Estimate table by passing the Cost Estimate ID
5. GET What-If Cost Estimate’s Status That is Enqueued for Calculation
Requires Cost Estimate Process ID
Returns status of the Cost Estimate enqueued for calculation
Things to Note
Cost Estimates API does not support the 'Custom Calculation (old)' on the Compensation Line Items Details screen
The system can return JSON format or retrieve documents as an output. For more information, it is advisable to consult the Swagger documentation when using the API