Project Insight allows administrators to customize REST API query output by using model properties. Model properties let you decide which fields are returned from an API call, so you can return the default fields, add extra fields, reduce the response to only the fields you need, or control which related object fields are included.
Project Insight does this by letting you pass a model property list into supported REST API search or get calls. This helps teams send cleaner, more focused Project Insight data to outside reporting tools, dashboards, integrations, or custom applications.
Best for: Project Insight administrators, developers, reporting teams, and business intelligence teams that use the Project Insight REST API to control what project, task, user, expense, or related data is returned from API queries.
What Are Model Properties in the Project Insight REST API?
Model properties are the fields you want returned from a Project Insight REST API call. By default, Project Insight sends default columns from the REST API. If you do not specify model properties, only the default properties are returned.
You can use model properties when you want:
- More fields than the default response includes
- Fewer fields than the default response includes
- Specific fields from a related object, such as a user, project type, or expense code
- A more focused API response for reports, dashboards, or integrations
In short, model properties help you control the size and content of the API response.
What Do You Need Before Customizing REST API Output?
Before you customize REST API output, you need REST API access in Project Insight. The video explains that you need to install the REST API Add-On and create a REST API token or key.
You can use the Project Insight article for setting up REST API access before working with model properties.
Placeholder link needed: Add link to the Project Insight article for setting up REST API access.
Video reference: View video at 00:29 to see the REST API token requirement.
Where Do You Find REST API References and API Models?
Project Insight provides REST API references and API models. The REST API references show the services you can use, such as project services. The API models show the different objects that can be returned from the API.
For example, the video uses the Project service and the active projects endpoint. The active projects endpoint is shown as:
Project/Active
This endpoint gets all active projects out of Project Insight.
Video reference: View video at 00:55 to see the API references and API models.
How Do You Find the Properties Available for an Endpoint?
To find which properties are available for an endpoint, open the REST API reference for the service you want to use. In the video example, the Project service is opened and the active projects endpoint is selected.
The endpoint page shows the response body and the properties included in the response. It also shows input parameters. One of the available inputs is the model property list.
The model property list tells Project Insight which properties you want returned from the API.
Video reference: View video at 01:00 to see the Project service and active projects endpoint.
How Do You Use a Query String to Select Model Properties?
One way to customize REST API output is to pass model properties in the query string. The video explains this as a simple way to specify which properties should come back from the API.
A query string example from the video uses model properties to return specific project fields:
modelProperties=name,projectType,projectStatus,workPercentComplete,primaryProjectManager
This overrides the default response and tells Project Insight to return only those selected properties.
Video reference: View video at 03:12 to see model properties used in a query string.
How Do Commas, Semicolons, and Colons Work in Model Properties?
Model properties use punctuation to separate fields and related object instructions.
- Use commas to separate properties on the main object.
- Use a semicolon when you are finished listing properties for one object and want to define properties for another object type.
- Use a colon after the related object type to define which properties should be returned for that object.
For example, the video explains that the first segment of model properties applies to the main object, such as a project. After a semicolon, you can define properties for a related object, such as a user.
modelProperties=name,projectType,projectStatus,workPercentComplete,primaryProjectManager;user:firstName,lastName
In this example, Project Insight returns selected project fields and, when a user object is returned, only the user’s first name and last name.
In short, commas separate properties, semicolons separate object instructions, and colons connect an object type to the properties you want from that object.
Video reference: View video at 04:11 to see how related object properties are formatted.
How Do You Return the Default Properties Plus One Extra Field?
If you want the default fields plus another field, use the keyword default and then add the additional property.
In the video, the example adds actual expense total to the default response:
modelProperties=default,actualExpenseTotal
This tells Project Insight to return the default columns plus the actual expense total.
Video reference: View video at 05:06 and 07:28 to see default properties used with an additional field.
How Do You Return Fewer Fields from an API Response?
To return fewer fields, specify only the model properties you want. In the video, the API call is narrowed down to return only the project name. Project Insight still returns the ID because the ID always comes out.
Example:
modelProperties=name
This can be useful when an integration or report only needs a small amount of information.
Video reference: View video at 05:54 to see the response reduced to fewer properties.
How Do You Add a Field That Is Not in the Default Response?
To add a field that is not in the default response, include that field in the model properties list. In the video, actual expense total is added to the response.
modelProperties=actualExpenseTotal
If you want the default fields and actual expense total, use:
modelProperties=default,actualExpenseTotal
Project Insight does this by reading the property list and returning the additional project field in the API response.
Video reference: View video at 06:21 to see actual expense total added to the output.
How Do You Customize User Object Output?
Related objects can have their own model property instructions. In the video, the primary project manager is returned as a user object. By default, Project Insight returns default user fields such as first name, last name, color settings, and ID.
To control the user object output, add a semicolon after the project properties, then define the user properties.
modelProperties=name,primaryProjectManager;user:name
This returns the project name and the primary project manager, but limits the user object to the name.
Video reference: View video at 06:44 to see primary project manager returned, and 07:06 to see user output customized.
Can You Pass Model Properties as a JSON Object?
Yes. The video also shows a more complex method where model properties are passed as a JSON object instead of a query string.
In that method, the object has one property called modelPropertyLists. That property contains an array, and each item can identify the object type and the comma-separated properties to return.
The video explains examples for task, user, and project objects. For example:
- For a task object, define the task properties you want.
- For a user object, define fields such as ID, name, and avatar.
- For a project object, define fields such as ID and item number full.
If the list applies to the main object being returned, you do not have to specify the type.
Video reference: View video at 07:59 to see model properties passed as a JSON object.
Where Do You Find the Object Types and Available Properties?
Use the API models list to find object types and available properties. The video points to object types such as task, project, location, and notification. The object type name is the word used when building either the URL method or the JSON method.
The same API model page also shows the available properties you can choose from.
Video reference: View video at 08:52 to see where object types and available properties appear in the API models.
Which REST API Calls Support Model Properties?
The video explains that most Project Insight API calls that are search or get calls involving lists of things include this option in the service call references.
To confirm whether a specific API call supports model properties, open that service call in the REST API references and review the input parameters. In the video, the active project call includes model property lists as an input parameter.
Video reference: View video at 10:41 to see where model property list input parameters appear.
Common Mistakes When Using Model Properties
- Not creating a REST API token before trying to call the API.
- Expecting non-default fields to appear without adding them to the model property list.
- Using only custom properties when you actually wanted the default fields plus one extra field.
- Forgetting to use the
defaultkeyword when you want default properties included. - Mixing up commas, semicolons, and colons when formatting related object properties.
- Trying to customize an API call before checking whether model property lists are supported on that service call.
Related Questions
What happens if I do not specify model properties?
If you do not specify model properties, Project Insight returns the default properties for that API call.
Can I return only one property from the API?
Yes. You can specify one property, such as the project name. The video also notes that the ID will still come out because the ID cannot be removed.
Can I add actual expense total to an API response?
Yes. If actual expense total is available on the model, you can include actualExpenseTotal in the model properties list.
Can I control which user fields are returned?
Yes. You can define user properties separately by adding a semicolon, the user object type, a colon, and the user fields you want returned.
Can I use model properties with JSON instead of a URL query string?
Yes. You can pass model properties as a JSON object using modelPropertyLists.
Need More Help?
If you have questions about Project Insight REST API model properties, visit Project Insight Support .
Comments
0 comments
Please sign in to leave a comment.