Change requests

Change Requests provide construction companies a way to keep track of changes to their projects in terms of cost, price and markup.

A change request may consist of one or more lines of changes that are captured using the construction work breakdown structure (Project + Task + Cost Type) along with cost and price information. Information about other dimensions may also be captured when relevant.

In some instances only the cost is captured, when the change is not billed to the customer.

Sometimes the cost and price on a change request are the same amount, such as when the cost of a change is simply passed on to the customer.

Sometimes, in the early stages of a change request, you may not have all the information at a line item level. In such cases, you may want to create a change request without any line items, and later go back to it to add line item along with cost and/or price information.

Once a change request is approved, the user would want to update the primary estimate of the project by posting the change request. When the primary estimate is posted to GL budgets, those line items generated by the posting of the change request would also be part of the posting of the project estimate to GL budgets.

List change requests

get/objects/construction/change-request

Returns up to 100 object references from the collection with a key, ID, and link for each change request. This operation is mostly for use in testing; use the query service to find objects that meet certain criteria and to specify properties that are returned.

SecurityOAuth2
Responses
200

OK

400

Bad Request

Request samples 
Response samples 
application/json
{
  • "ia::result": [
    • {
      • "key": "1",
      • "id": "CR-1",
      • "href": "/objects/construction/change-request/1"
      },
    • {
      • "key": "2",
      • "id": "CR-2",
      • "href": "/objects/construction/change-request/2"
      },
    • {
      • "key": "3",
      • "id": "CR-3",
      • "href": "/objects/construction/change-request/3"
      }
    ],
  • "ia::meta": {
    • "totalCount": 3,
    • "start": 1,
    • "pageSize": 100,
    • "next": null,
    • "previous": null
    }
}
Create a change request
post/objects/construction/change-request
Creates a new change request.


SecurityOAuth2 
Request 
Request Body schema: application/json
required
Change request to create


id
required
string  <= 40 characters 
Unique identifier for the change request.


 
 Example:  "CR-12"
required
object
Reference to the project associated with the change request.


 
key
string
Unique key for the project.


 
 Example:  "2"
id
string
Unique identifier for the project.


 
 Example:  "NET-XML30-2"
changeRequestDate
required
string <date> 
Date of the change request, which is used as the estimate entry effective date if posted to a GL budget.


 
 Example:  "2024-01-24"
description
string  <= 1000 characters 
Description of the change request.


 
 Example:  "Change Request 12"
object
Reference to the change request status.


 
key
string
Unique key for the change request status.


 
 Example:  "12"
id
string
Unique identifier for the change request status.


 
 Example:  "CRStatus-12"
object
Specifies the type of change request, which may be used for reporting purposes.


 
key
string
Unique key for the change request type.


 
 Example:  "12"
id
string
Unique identifier for the change request type.


 
 Example:  "CRType-12"
changeRequestState
string
 Default:  "draft"
Indicates the current state of the change request. Use draft to save the request without initiating posting, or posted to proceed with posting as configured. Note that the project change order must be in a posted state to update the project contract lines.


 Enum: "draft" "posted"  
 Example:  "draft"
costEffectiveDate
string <date> 
Cost effective date of the change request. When posting change request lines to a project estimate, the estimate line effectiveDate field will be populated from this value. If the costEffectiveDate is null, the estimate line effectiveDate field will be populated from the changeRequestDate.


 
 Example:  "2022-01-24"
priceEffectiveDate
string <date> 
Price effective date of the change request.


 
 Example:  "2022-01-24"
object
Reference to the project change order to link to. This is only allowed if the changeRequestState is posted.


 
key
string
Unique key for the project change order.


 
 Example:  "5"
id
string
Unique identifier for the project change order.


 
 Example:  "PCO-BTI-1"
projectContractLineSource
string
 Default:  "projectChangeOrder"
Project contract line source - where this change request integrates with project contracts. 


    

  • none - Project contract (projectContract) and project contract line (projectContractLine) cannot be used. 
    • 

  • projectChangeOrder - Project contract (projectContract) and project contract line (projectContractLine) are inherited from the project change order (projectChangeOrder). 
    • 

  • changeRequest - Project contract (projectContract) and project contract line (projectContractLine) can be used on the change request and will be inherited by the change request lines. 
    • 

  • changeRequestLine - Project contract (projectContract) and project contract line (projectContractLine) can be entered on change request lines.
    • 



 Enum: "changeRequest" "changeRequestLine" "none" "projectChangeOrder"  
 Example:  "projectChangeOrder"
object
Reference to the project contract affected by this change request. Requires projectContractLine.


 
key
string
Unique key for the project contract.


 
 Example:  "3"
id
string
Unique identifier for the project contract.


 
 Example:  "Project-Contract-03"
object
Reference to the specific project contract line that is affected by this change request. Required if projectContract is provided.


 
key
string
System-assigned unique key for the project contract line.


 
 Example:  "4"
id
string
Unique identifier for the project contract line.


 
 Example:  "Project-Contract-Line-04"
scope
string or null
Details about the expected scope of work for the change request.


 
 Example:  "Design"
inclusions
string or null
Details related to items that are explicitly included in the terms of this change request.


 
 Example:  "Original plan"
exclusions
string or null
Details related to items that are explicitly excluded in the terms of this change request.


 
 Example:  "Hardware accessories"
terms
string or null
Additional terms or performance obligations.


 
 Example:  "Standard terms and conditions"
object
 
scheduledStartDate
string <date> 
Scheduled start date


 
 Example:  "2021-06-15"
actualStartDate
string <date> 
Actual start date


 
 Example:  "2021-06-30"
scheduledCompletionDate
string <date> 
Scheduled completion date


 
 Example:  "2022-11-15'"
revisedCompletionDate
string <date> 
Revised completion date


 
 Example:  "2021-12-15"
substantialCompletionDate
string <date> 
Substantial completion date


 
 Example:  "2021-09-30"
actualCompletionDate
string <date> 
Actual completion date


 
 Example:  "2021-12-15"
noticeToProceedDate
string <date> 
Notice to proceed date


 
 Example:  "2021-05-30"
responseDueDate
string <date> 
Response due date


 
 Example:  "2021-06-05"
executedOnDate
string <date> 
Executed on date


 
 Example:  "2021-06-01"
scheduleImpact
string
Schedule Impact


 
 Example:  "None"
object
 
referenceNumber
string
Reference number


 
 Example:  "INT-01"
object
Initiated by


 
key
string
Employee key


 
 Example:  "2"
id
string
Employee id


 
 Example:  "dhatchet"
object
Verbal approval by


 
key
string
Employee key


 
 Example:  "2"
id
string
Employee id


 
 Example:  "sdye"
object
Issued by


 
key
string
Employee key


 
 Example:  "25"
id
string
Employee id


 
 Example:  "amarquess"
issuedOnDate
string <date> 
Issued on date


 
 Example:  "2021-05-30"
object
Approved by


 
key
string
Employee key


 
 Example:  "1"
id
string
Employee id


 
 Example:  "treser"
approvedOnDate
string <date> 
Approved on date


 
 Example:  "2021-10-02"
object
Signed by


 
key
string
Employee key


 
 Example:  "32"
id
string
Employee id


 
 Example:  "broberts"
signedOnDate
string <date> 
Signed on date


 
 Example:  "2021-05-31"
source
string
Internal source


 
 Example:  "Internal"
sourceReferenceNumber
string
Internal source reference number


 
 Example:  "REF-INT-01"
object
 
referenceNumber
string
External reference number


 
 Example:  "A23"
object
Verbal approval by


 
key
string
Contact key


 
 Example:  "6"
id
string
Contact name


 
 Example:  "Johnson"
object
Approved by


 
key
string
Contact key


 
 Example:  "51"
id
string
Contact name


 
 Example:  "Jagadish"
approvedOnDate
string <date> 
Approved on date


 
 Example:  "2021-11-03"
object
Signed by


 
key
string
Contact key


 
 Example:  "200"
id
string
Contact name


 
 Example:  "Modulus Industries"
signedOnDate
string <date> 
Signed on date


 
 Example:  "2021-12-01"
Array of objects
Change request lines.


 
 Array 
workflowType
string
 Default:  "none"
Workflow type for the change request line.


 Enum: "approvedChange" "forecast" "none" "original" "other" "pendingChange" "revision"  
 Example:  "revision"
object
 
numberOfProductionUnits
string
Number of production units, which are units that track several inputs of cost (such as for material, labor, equipment).


 
 Example:  "1200"
quantity
string <decimal-precision-2> 
Quantity for the change request line.


 
 Example:  "10.00"
externalUOM
string or null
External unit of measure.


 
 Example:  "each"
unitCost
string <decimal-precision-2> 
Unit cost for the change request line.


 
 Example:  "50.00"
cost
string <decimal-precision-2> 
Total cost for the change request line.


 
 Example:  "250.00"
unitPrice
string <decimal-precision-2> 
Unit price for the change request line.


 
 Example:  "50.00"
price
string <decimal-precision-2> 
Total price for the change request line.


 
 Example:  "250.00"
priceMarkupPercent
string <decimal-precision-2> 
Price markup percent for the change request line.


 
 Example:  "5.00"
priceMarkupAmount
string <decimal-precision-2> 
Price markup amount for the change request line.


 
 Example:  "300.00"
memo
string
Memo for the change request line.


 
 Example:  "Awaiting approval"
object
Reference to the General Ledger account associated with the change request line.


 
object
Reference to the project contract affected by this change request line.


 
object
Reference to the specific project contract line that is affected by this change request line.


 
object
Supporting document ID.


 
key
string
Attachment key


 
 Example:  "6"
id
string
Attachment id


 
 Example:  "att-1"
Responses 
201
Created


400
Bad Request


Request samples 
application/json
{
  • "id": "CR-4",
  • "changeRequestDate": "2021-11-11",
  • "project": {
    • "key": "12"
    }
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "4",
    • "id": "CR-4",
    • "href": "/objects/construction/change-request/4"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Get a change request
get/objects/construction/change-request/{key}
Returns detailed information for a particular change request.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for the change request.


 
 Example:  99
Responses 
200
OK


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "key": "1",
    • "id": "CR1-DIMBTI-CRHSrce",
    • "changeRequestType": {
      • "key": "12",
      • "id": "CRType-12",
      • "href": "/objects/construction/change-request-type/12"
      },
    • "project": {
      • "key": "1",
      • "id": "DIM - BTI",
      • "name": "Dimensions - Berkeley Technology Inc",
      • "href": "/objects/projects/project/1"
      },
    • "location": {
      • "key": "1",
      • "id": "1",
      • "name": "United States of America",
      • "href": "/objects/company-config/location/1"
      },
    • "projectCustomer": {
      • "key": "14",
      • "id": "BTI",
      • "name": "Berkeley Technology Inc",
      • "href": "/objects/accounts-receivable/customer/14"
      },
    • "changeRequestDate": "2021-02-07",
    • "changeRequestState": "posted",
    • "changeRequestStatus": {
      • "key": "1",
      • "id": "CRStatus_Original",
      • "workflowType": "original",
      • "href": "/objects/construction/change-request-status/1"
      },
    • "description": "CR1 with Line Source set to change request header",
    • "costEffectiveDate": "2021-02-02",
    • "priceEffectiveDate": "2021-02-02",
    • "totalCost": "100.00",
    • "totalPrice": "200.00",
    • "projectChangeOrder": {
      • "key": "1",
      • "id": "PCO1-DIMBTI",
      • "href": "/objects/construction/project-change-order/1"
      },
    • "scope": "change request scope",
    • "inclusions": null,
    • "exclusions": null,
    • "terms": null,
    • "schedule": {
      • "scheduledStartDate": "2022-05-30",
      • "actualStartDate": "2022-05-30",
      • "scheduledCompletionDate": "2022-05-30",
      • "revisedCompletionDate": "2022-05-30",
      • "substantialCompletionDate": "2022-05-30",
      • "actualCompletionDate": "2022-05-30",
      • "noticeToProceedDate": "2022-05-30",
      • "responseDueDate": "2022-05-30",
      • "executedOnDate": "2022-05-30",
      • "scheduleImpact": "None"
      },
    • "internalReference": {
      • "referenceNumber": "INT-01",
      • "initiatedBy": {
        },
      • "verbalApprovalBy": {
        },
      • "issuedBy": {
        },
      • "issuedOnDate": "2021-05-30",
      • "approvedBy": {
        },
      • "approvedOnDate": "2021-10-02",
      • "signedBy": {
        },
      • "signedOnDate": "2021-05-31",
      • "source": "NA",
      • "sourceReferenceNumber": "REF-01"
      },
    • "externalReference": {
      • "referenceNumber": "A23",
      • "verbalApprovalBy": {
        },
      • "approvedBy": {
        },
      • "approvedOnDate": "2021-11-03",
      • "signedBy": {
        },
      • "signedOnDate": "2021-12-01"
      },
    • "attachment": {
      • "id": "1"
      },
    • "projectContract": {
      • "key": "1",
      • "id": "PCN1-Top-DIMBTI",
      • "name": "PCN1-Top-DIMBTI",
      • "href": "/objects/construction/project-contract/1"
      },
    • "projectContractLine": {
      • "key": "1",
      • "id": "01",
      • "name": "01-Billable Labor",
      • "href": "/objects/construction/project-contract-line/1"
      },
    • "audit": {
      • "modifiedDateTime": "2023-06-14T13:56:37Z",
      • "createdDateTime": "2023-06-14T13:56:35Z",
      • "modifiedBy": "1",
      • "createdBy": "1"
      },
    • "entity": {
      • "key": "46",
      • "id": "CORP",
      • "name": "Corp",
      • "href": "/objects/company-config/entity/46"
      },
    • "projectContractLineSource": "changeRequest",
    • "changeRequestLines": [
      • {
        }
      ],
    • "href": "/objects/construction/change-request/1"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Update a change request
patch/objects/construction/change-request/{key}
Updates an existing change request by setting field values. Any fields not provided remain unchanged.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for the change request.


 
 Example:  99
Request Body schema: application/json
object
Reference to the project associated with the change request.


 
key
string
Unique key for the project.


 
 Example:  "2"
id
string
Unique identifier for the project.


 
 Example:  "NET-XML30-2"
changeRequestDate
string <date> 
Date of the change request, which is used as the estimate entry effective date if posted to a GL budget.


 
 Example:  "2024-01-24"
description
string  <= 1000 characters 
Description of the change request.


 
 Example:  "Change Request 12"
object
Reference to the change request status.


 
key
string
Unique key for the change request status.


 
 Example:  "12"
id
string
Unique identifier for the change request status.


 
 Example:  "CRStatus-12"
object
Specifies the type of change request, which may be used for reporting purposes.


 
key
string
Unique key for the change request type.


 
 Example:  "12"
id
string
Unique identifier for the change request type.


 
 Example:  "CRType-12"
changeRequestState
string
 Default:  "draft"
Indicates the current state of the change request. Use draft to save the request without initiating posting, or posted to proceed with posting as configured. Note that the project change order must be in a posted state to update the project contract lines.


 Enum: "draft" "posted"  
 Example:  "draft"
costEffectiveDate
string <date> 
Cost effective date of the change request. When posting change request lines to a project estimate, the estimate line effectiveDate field will be populated from this value. If the costEffectiveDate is null, the estimate line effectiveDate field will be populated from the changeRequestDate.


 
 Example:  "2022-01-24"
priceEffectiveDate
string <date> 
Price effective date of the change request.


 
 Example:  "2022-01-24"
object
Reference to the project change order to link to. This is only allowed if the changeRequestState is posted.


 
key
string
Unique key for the project change order.


 
 Example:  "5"
id
string
Unique identifier for the project change order.


 
 Example:  "PCO-BTI-1"
projectContractLineSource
string
 Default:  "projectChangeOrder"
Project contract line source - where this change request integrates with project contracts. 


    

  • none - Project contract (projectContract) and project contract line (projectContractLine) cannot be used. 
    • 

  • projectChangeOrder - Project contract (projectContract) and project contract line (projectContractLine) are inherited from the project change order (projectChangeOrder). 
    • 

  • changeRequest - Project contract (projectContract) and project contract line (projectContractLine) can be used on the change request and will be inherited by the change request lines. 
    • 

  • changeRequestLine - Project contract (projectContract) and project contract line (projectContractLine) can be entered on change request lines.
    • 



 Enum: "changeRequest" "changeRequestLine" "none" "projectChangeOrder"  
 Example:  "projectChangeOrder"
object
Reference to the project contract affected by this change request. Requires projectContractLine.


 
key
string
Unique key for the project contract.


 
 Example:  "3"
id
string
Unique identifier for the project contract.


 
 Example:  "Project-Contract-03"
object
Reference to the specific project contract line that is affected by this change request. Required if projectContract is provided.


 
key
string
System-assigned unique key for the project contract line.


 
 Example:  "4"
id
string
Unique identifier for the project contract line.


 
 Example:  "Project-Contract-Line-04"
scope
string or null
Details about the expected scope of work for the change request.


 
 Example:  "Design"
inclusions
string or null
Details related to items that are explicitly included in the terms of this change request.


 
 Example:  "Original plan"
exclusions
string or null
Details related to items that are explicitly excluded in the terms of this change request.


 
 Example:  "Hardware accessories"
terms
string or null
Additional terms or performance obligations.


 
 Example:  "Standard terms and conditions"
object
 
scheduledStartDate
string <date> 
Scheduled start date


 
 Example:  "2021-06-15"
actualStartDate
string <date> 
Actual start date


 
 Example:  "2021-06-30"
scheduledCompletionDate
string <date> 
Scheduled completion date


 
 Example:  "2022-11-15'"
revisedCompletionDate
string <date> 
Revised completion date


 
 Example:  "2021-12-15"
substantialCompletionDate
string <date> 
Substantial completion date


 
 Example:  "2021-09-30"
actualCompletionDate
string <date> 
Actual completion date


 
 Example:  "2021-12-15"
noticeToProceedDate
string <date> 
Notice to proceed date


 
 Example:  "2021-05-30"
responseDueDate
string <date> 
Response due date


 
 Example:  "2021-06-05"
executedOnDate
string <date> 
Executed on date


 
 Example:  "2021-06-01"
scheduleImpact
string
Schedule Impact


 
 Example:  "None"
object
 
referenceNumber
string
Reference number


 
 Example:  "INT-01"
object
Initiated by


 
key
string
Employee key


 
 Example:  "2"
id
string
Employee id


 
 Example:  "dhatchet"
object
Verbal approval by


 
key
string
Employee key


 
 Example:  "2"
id
string
Employee id


 
 Example:  "sdye"
object
Issued by


 
key
string
Employee key


 
 Example:  "25"
id
string
Employee id


 
 Example:  "amarquess"
issuedOnDate
string <date> 
Issued on date


 
 Example:  "2021-05-30"
object
Approved by


 
key
string
Employee key


 
 Example:  "1"
id
string
Employee id


 
 Example:  "treser"
approvedOnDate
string <date> 
Approved on date


 
 Example:  "2021-10-02"
object
Signed by


 
key
string
Employee key


 
 Example:  "32"
id
string
Employee id


 
 Example:  "broberts"
signedOnDate
string <date> 
Signed on date


 
 Example:  "2021-05-31"
source
string
Internal source


 
 Example:  "Internal"
sourceReferenceNumber
string
Internal source reference number


 
 Example:  "REF-INT-01"
object
 
referenceNumber
string
External reference number


 
 Example:  "A23"
object
Verbal approval by


 
key
string
Contact key


 
 Example:  "6"
id
string
Contact name


 
 Example:  "Johnson"
object
Approved by


 
key
string
Contact key


 
 Example:  "51"
id
string
Contact name


 
 Example:  "Jagadish"
approvedOnDate
string <date> 
Approved on date


 
 Example:  "2021-11-03"
object
Signed by


 
key
string
Contact key


 
 Example:  "200"
id
string
Contact name


 
 Example:  "Modulus Industries"
signedOnDate
string <date> 
Signed on date


 
 Example:  "2021-12-01"
Array of objects
Change request lines.


 
 Array 
workflowType
string
 Default:  "none"
Workflow type for the change request line.


 Enum: "approvedChange" "forecast" "none" "original" "other" "pendingChange" "revision"  
 Example:  "revision"
object
 
numberOfProductionUnits
string
Number of production units, which are units that track several inputs of cost (such as for material, labor, equipment).


 
 Example:  "1200"
quantity
string <decimal-precision-2> 
Quantity for the change request line.


 
 Example:  "10.00"
externalUOM
string or null
External unit of measure.


 
 Example:  "each"
unitCost
string <decimal-precision-2> 
Unit cost for the change request line.


 
 Example:  "50.00"
cost
string <decimal-precision-2> 
Total cost for the change request line.


 
 Example:  "250.00"
unitPrice
string <decimal-precision-2> 
Unit price for the change request line.


 
 Example:  "50.00"
price
string <decimal-precision-2> 
Total price for the change request line.


 
 Example:  "250.00"
priceMarkupPercent
string <decimal-precision-2> 
Price markup percent for the change request line.


 
 Example:  "5.00"
priceMarkupAmount
string <decimal-precision-2> 
Price markup amount for the change request line.


 
 Example:  "300.00"
memo
string
Memo for the change request line.


 
 Example:  "Awaiting approval"
object
Reference to the General Ledger account associated with the change request line.


 
object
Reference to the project contract affected by this change request line.


 
object
Reference to the specific project contract line that is affected by this change request line.


 
object
Supporting document ID.


 
key
string
Attachment key


 
 Example:  "6"
id
string
Attachment id


 
 Example:  "att-1"
Responses 
200
OK


400
Bad Request


Request samples 
application/json
{
  • "description": "CR1 with Line Source set to change request header - updated by project manager"
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "4",
    • "id": "CR-4",
    • "href": "/objects/construction/change-request/4"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Delete a change request
delete/objects/construction/change-request/{key}
Deletes a change request.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for the change request.


 
 Example:  99
Responses 
204
No Content


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}