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.

Please be aware that this object is currently "Uncertified", signifying that it has not undergone the complete review process and the design may change during ongoing refinement. Users are advised to exercise discretion in using this object and are encouraged to provide feedback.

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.

Permissions and other requirements
SubscriptionConstruction, Project Costing and Billing
User typeBusiness, Project Manager
PermissionsList, View Change requests
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.



Permissions and other requirements



SubscriptionConstruction, Project Costing and Billing


User typeBusiness, Project Manager


PermissionsList, View, Add Change requests







SecurityOAuth2 
Request 
Request Body schema: application/json
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 to use


 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.



Permissions and other requirements



SubscriptionConstruction, Project Costing and Billing


User typeBusiness, Project Manager


PermissionsList, View Change requests







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


 
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"
      },
    • "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.



Permissions and other requirements



SubscriptionConstruction, Project Costing and Billing


User typeBusiness, Project Manager


PermissionsList, View, Edit Change requests







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


 
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 to use


 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.



Permissions and other requirements



SubscriptionConstruction, Project Costing and Billing


User typeBusiness, Project Manager


PermissionsList, View, Delete Change requests







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


 
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
    }
}
Query change requests
post/services/core/query
Queries an object for filtered data.


SecurityOAuth2 
Request 
Request Body schema: application/json
object
string
Object type to query, in the form <application-name>/<object name>. For custom objects use platform-apps/nsp::<object-name>.


 
 Example:  "construction/change-request"
fields
Array of strings
List of fields to include in the response. Can be any combination of these:


    

  • The name of a field in the object that you are querying, such as id.
    

    • 

  • The name of a field in a related object, using the form relatedObjectName.fieldName, such as vendor.id.
    

    • 

  • The result of an aggregate function run against the values in the returned objects. Use the form function:fieldName, such as min:startDate to return the earliest starting date. Valid function names are:
    

      

    • count
      • 

    • avg
      • 

    • sum
      • 

    • min
      • 

    • max
      • 

    

    • 

  • The result of an aggregate function run against the values in related objects, using the form function:relatedObjectName.fieldName, such as max:vendor.creditLimit. The same functions are supported as for object fields.
    

    • 



 
 Example:  ["key","id","max:vendor.creditLimit"]
Array of equal (object) or not equal (object) or less than (object) or (less than or equal (object)) or greater than (object) or (greater than or equal (object)) or in (object) or not in (object) or between (object) or not between (object) or contains (object) or does not contain (object) or starts with (object) or does not start with (object) or ends with (object) or does not end with (object)
Filter conditions to select the objects to return based on their field values. You use operators and conditions to build your filter, such as {"$eq":{"status":"active"}} to select objects in which status is equal to "active".


 
 Example:  [{"$eq":{"status":"active"}},{"$gt":{"totalDue":"1000"}},{"$contains":{"name":"Acme"}}]
 Array 
Any of:
Field value must be equal to this specified value.


For date fields, you can use these macro values that are relative to the current date or the asOfDate in filterParameters, if set:







    

  • today

  • currentWeek

  • currentMonth

  • currentQuarter

  • currentYear





    

  • yesterday

  • lastWeek

  • priorMonth

  • priorQuarter

  • priorYear









These are most useful for queries that you want to save and use repeatedly, such as for views or reports. Just change the asOfDate each time to retrieve the same data set for different time periods.


For example, {"eq":{"postingDate":"priorYear"}}.


object
The field name and value to be compared with object values.


 
 Example:  {"status":"active"}
filterExpression
string
 Default:  "and"
Logical operators to apply when there are multiple filter conditions. The conditions in the filters array are implicitly numbered starting at 1. Supports and, or, and grouping with parentheses.


Shortcuts:


    

  • and by itself means that all conditions must be true.
    • 

  • or by itself means that at least one condition must be true.
    • 



 
 Example:  "(1 and 2) or 3"
object

Pre-defined filter options.


 
asOfDate
string <date> 
The "as of" date to use with any relative date comparisons in filters. For example, if asOfDate is set to "2022-04-01" then priorMonth will be "03".


The current date is used if asOfDate is not set.


 
 Example:  "2022-04-01"
includeHierarchyFields
boolean
 Default:  false
Set to true to include hierarchical structure information with each object in the response.


 
 Example:  false
caseSensitiveComparison
boolean
 Default:  true
Queries are case-sensitive by default. Set to false to ignore case in a query.


 
 Example:  true
includePrivate
boolean
 Default:  false
By default, in a multi-entity company, queries from the top-level entity do not access data in private entities. Set includePrivate to true if you want to query data in private entities.


 
 Example:  false
Array of objects
Set the order of the results by specifying field names to sort by and whether they should be in ascending or descending order.


 
 Example:  [{"totalDue":"asc"},{"lastPaymentMadeDate":"desc"}]
 Array 
property name*
additional property
string
 Enum: "asc" "desc"  
start
integer
First record of the result set to include in the response.


 
 Example:  1
size
integer
Number of records to include in the response.


 
 Example:  100
Responses 
200
OK


400
Bad Request


Request samples 
application/json
{
  • "object": "accounts-payable/vendor",
  • "fields": [
    • "id",
    • "name",
    • "status",
    • "href"
    ],
  • "filters": [
    • {
      • "$eq": {
        }
      },
    • {
      • "$eq": {
        }
      }
    ],
  • "filterExpression": "1 and 2",
  • "orderBy": [
    • {
      • "id": "asc"
      }
    ]
}
Response samples 
application/json
{
  • "ia::result": [
    • {
      • "id": "Vend-00002",
      • "name": "Test vendor",
      • "status": "active",
      • "href": "/objects/accounts-payable/vendor/85"
      },
    • {
      • "id": "VEND-00010",
      • "name": "Design Works",
      • "status": "active",
      • "href": "/objects/accounts-payable/vendor/111"
      }
    ],
  • "ia::meta": {
    • "totalCount": 2,
    • "start": 1,
    • "pageSize": 100,
    • "next": null,
    • "previous": null
    }
}