Instances
GET
containers/{containerId}/instances
Retrieves information about all the BIM 360 Field Management checklists in a project, including details about their statuses, priorities, and assignees. To get more information about a single checklist, for example, details about checklist items, sections, attachments, and signatures, see GET instances/:id.
New! Autodesk Construction Cloud platform (ACC). Note that this endpoint is not compatible with ACC projects. For more information about the Autodesk Construction Cloud APIs, see the Autodesk Construction Cloud documentation.
Resource Information
Method and URI | GET https://developer.api.autodesk.com/bim360/checklists/v1/containers/{containerId}/instances |
Authentication Context | user context required |
Required OAuth Scopes | data:read |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via a three-legged OAuth flow. |
* Required
Request
URI Parameters
containerId string | Each project is assigned a container that stores all the checklists for the project. To find the ID, see the Retrieve a Container ID tutorial. |
Request
Query String Parameters
sort enum:string | Sort the checklists by title , templateType.id , or scheduledDate . For example, sort=title . Separate multiple values with commas. To sort in descending order add a - before the sort criteria; for example, sort=-title . For more details, see JSON API Sorting.
Possible values: templateType.id , title , scheduledDate |
filter[templateTypeId] number | Retrieves checklists associated with the specified template type. For example, filter[templateTypeId]=1 or queryFilter[templateType.id]=1 or queryFilter[templateTypeId]=1 . Possible values: 1 (quality), 6 (punch List), 11 (safety), 15 (commissioning). Separate multiple values with commas. For more details, see JSON API Filtering. |
filter[statusId] number | Retrieves checklists with the specified status. For example, filter[statusId]=3 or queryFilter[status.id]=3 or queryFilter[statusId]=3 . Possible values: 1 (not scheduled), 2 (scheduled), 3 (in progress), 4 (completed), 5 (signed off), 6 (pending signature), 7 (not started). Separate multiple values with commas. For more details, see JSON API Filtering. |
filter[assigneeIds] string | Retrieves checklists assigned to the specified user. For example, filter[assigneeIds]=PER8KQPK2JRT or queryFilter[assignees.assigneeId]=PER8KQPK2JRT or queryFilter[assigneeIds]=PER8KQPK2JRT . Use the assignee’s Autodesk ID. To check a user`s Autodesk ID, call GET users and check the uid . Note that you need to use a 2-legged token to call GET users. For more details, see JSON API Filtering. |
filter[scheduledDate] datetime: ISO 8601 | Retrieves checklists with the specified scheduled date. Value is the timestamp of the date in the following format: YYYY-MM-DDThh:mm:ss.sz , or a date range in the following format: YYYY-MM-DDThh:mm:ss.sz...YYYY-MM-DDThh:mm:ss.sz . For more details, see JSON API Filtering. |
limit number | The number of checklists to return in the response payload. Default value: 50 . For example, to limit the response to two checklists per page, use page[limit]=2 or limit=2 . For more details, see JSON API Paging. |
offset number | The page number that you want to begin checklist results from; for example, page[offset]=20 or offset=20 . For more details, see JSON API Paging. |
fields[instances] string | Specify which attributes you want to appear in the response. Separate multiple values with commas; for example, fields[instances]=createdAt,templateType. For more details, see JSON API Sparse Fieldsets. |
Response
HTTP Status Code Summary
200 OK | Success |
400 Bad Request | The request could not be understood by the server due to malformed syntax or missing request header |
403 Forbidden | The request has not been applied because it lacks valid authentication credentials for the target resource |
410 | Forbidden |
500 Internal Server Error | An unexpected error occurred on the server |
Response
Body Structure (200)
Expand all
jsonapi object | The JSON API object. |
version string | The version of JSON API; will always be 1.0 . |
meta object | The meta object. |
offset number | The page number that the checklist results begin from. |
limit number | The number of checklists per page. |
total number | The total number of checklists. |
links object | The links object. |
self string | A link to the checklist itself. |
first string | A link to the first page. |
last string | A link to the last page. |
next string | A link to the next page. |
prev string | A link to the previous page. |
data array: object | The data object. |
id string | The ID of the checklist. |
type string | The type of object; will always be instances . |
attributes object | The attributes object. |
instanceRevision string | Not relevant |
urn string | Not relevant |
scheduledDate datetime: ISO 8601 | The due date for the checklist, in the following format: YYYY-MM-DDThh:mm:ss.sz . |
location string: UUID | Not relevant |
title string | The name of the checklist.
Max length: 100 |
templateVersionId int | The version ID of the template associated with the checklist. Every time you update a template it updates the version ID. |
createdBy string | The Autodesk ID of the user who created the checklist. |
modifiedBy string | The Autodesk ID of the user who last modified the checklist. |
updatedAt datetime: ISO 8601 | The date and time that the resource was last updated, in the following format: YYYY-MM-DDThh:mm:ss.sz . |
createdAt datetime: ISO 8601 | The date and time that the resource was created, in the following format: YYYY-MM-DDThh:mm:ss.sz . |
deletedAt datetime: ISO 8601 | The date and time that the resource was deleted, in the following format: YYYY-MM-DDThh:mm:ss.sz . This is used for offline mobile database managment. |
trades array: object | Not relevant |
instructions string | The description of the template. |
templateType object | Information about the type of template.
Possible values:
1 - Quality
6 - Punch List
11 - Safety
15 - Commissioning |
id number | The ID of the type of template. Possible values: 1 (Quality), 6 (Punch List), 11 (Safety), 15 (Commissioning). |
name string | The name of the type of template. Possible values: Quality , Punch List , Safety , Commissioning . |
permittedAttributes array: string | The list of properties that a user with edit permission is allowed to modify. |
status object | Information about the status of the checklist. |
id number | The ID of the status. Possible values:
1 - Not Scheduled
2 - Scheduled
3 - In Progress
4 - Completed
5 - Signed off
6 - Pending Signature
7 - Not Started |
name string | The name of the status. Possible values: Not Scheduled , Scheduled , In Progress , Completed , Signed Off , Pending Signature , Not Started . |
urgency number | Not relevant |
permittedAttributes array: string | The list of properties that a user with edit permission is allowed to modify. |
signaturesStatus enum:string | The signatures status of the checklist. Possible values:
Pending - all sections are complete but one or more signatures are required.
Required - not all sections are complete, and one or more signatures are required.
Signed - no more signatures are required.
None - signatures are not needed. |
assignees array: object | A list of users who have been assigned to the checklist. |
id number | Not relevant |
assigneeId string | The Autodesk ID of the assignee. |
name string | The name of the assignee. |
type object | Information about the type of entity assigned to the checklist. |
id number | The ID of the type of entity assigned to the checklist.
Possible values:
1 - User
2 - Company
3 - Role |
name string | The name of the entity assigned to the checklist. Possible values: User , Company , Role . |
permittedAttributes array: string | The list of properties that a user with edit permission is allowed to modify. |
permittedAttributes array: string | The list of properties that a user with edit permission is allowed to modify. |
progress number | The percentage of checklist items that are completed; calculated using data.attributes.completedItemsCount and data.meta.totalItems . |
completedItemsCount number | The number of completed checklist items. |
permittedActions array: string | A list of actions that the user is permitted to perform on the resource. |
permittedAttributes array: string | A list of properties that a user with edit permission is allowed to modify. |
allowSectionAssignee boolean |
|
signatures array: object | A list of final signoff signatures. |
urn string | The URN of the signature. |
instanceRevision string | The identifier of a specific version of a checklist. |
instanceId int | The identifier of the signature. |
index int | The array index of the signature. |
requiredBy string | The name of the person or organization that requires the checklist to be signed. |
isRequired boolean |
Currently, all signatures are required. |
definedAt string | The type of object in which the signature is defined. This can be an instance or a template. |
requiredName string | The name of the person that is required to sign the checklist. |
requiredCompany string | The name of the company that is required to sign the checklist. |
isSigned boolean |
|
formalSignature object | The properties of the individual signature. |
instanceSignedRevision string | The identifier of a specific version of a signed instance. |
signedName string | The name of the person who signed the instance. |
signedCompany string | The name of the company that signed the instance. |
signedAt datetime: ISO 8601 | The date and time that the person or company signed the instance, in the following format: YYYY-MM-DDThh:mm:ss.sz . |
graphic object | The details of the signature graphic. |
type string | The image type of the signature graphic. |
content string | The raw signature image data, or a link to the signature image file. |
permittedAttributes array: string | The list of graphic properties that a user with edit permission is allowed to modify. |
permittedAttributes array: string | The list of signature properties that a user with edit permission is allowed to modify. |
updatedAt datetime: ISO 8601 | The date and time that the resource was last updated, in the following format: YYYY-MM-DDThh:mm:ss.sz . |
createdAt datetime: ISO 8601 | The date and time that the resource was created, in the following format: YYYY-MM-DDThh:mm:ss.sz . |
deletedAt datetime: ISO 8601 | The date and time that the resource was deleted, in the following format: YYYY-MM-DDThh:mm:ss.sz . This is used for offline mobile database managment. |
submittedBy string | The Autodesk ID of the user who last submitted signataures to this checklist instance. |
permittedAttributes array: string | The list of signature properties that a user with edit permission is allowed to modify. |
permittedActions array: string | The list of actions that the user is permitted to perform on the signature. |
relationships object | The relationships object. |
sections object | The sections object. |
links object | The links object. |
self string | A link to the object itself. |
related string | A link to the related object. |
meta object | The meta object. |
data array: object | The data object. |
type string | The type of object; will always be instance_sections |
id string | The ID of the object. |
container object | The related container object. |
links object | The links object. |
self string | A link to the object itself. |
related string | A link to the related object. |
meta object | The meta object. |
data object | The data object. |
type string | The type of object; will always be containers . |
id string | The ID of the object. |
createdFrom object | The relation to template. |
links object | The links object. |
self string | A link to the object itself. |
related string | A link to the related object. |
meta object | The meta object. |
data object | The data object. |
type string | The type of object; will always be templates . |
id string | The ID of the object. |
meta object | The meta object. |
totalItems number | The number of items in all the sections of the checklist. |
totalSections number | The number of sections in the checklist. |
totalRequiredSignatures number | The number of required checklist-level signatures. For information about section-level signatures, see included[].attributes.signatures . |
totalSignedSignatures number | The number of checklist-level signed signatures. For information about section-level signatures, see included[].attributes.signatures . |
totalUnsignedSignatures number | The number of unsigned checklist-level signatures in the checklist. For information about section-level signatures, see included[].attributes.signatures . |
links object | The links object. |
self string | A link to the object itself. |
related string | A link to the related object. |
Example
Success
Request
curl -v 'https://developer.api.autodesk.com/bim360/checklists/v1/containers/efca79bd-3865-4e68-88d5-30d982175c7d/instances?sort=title&filter[templateTypeId]=1&filter[statusId]=3&filter[assigneeIds]=NZFGQS2CTCCC&filter[scheduledDate]=2017-09-13T10:25:03.000Z&limit=10' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
Response
{
"jsonapi": {
"version": "1.0"
},
"meta": {
"offset": 0,
"limit": 50,
"total": 210
},
"links": {
"self": "/containers/efca79bd-3865-4e68-88d5-30d982175c7d/instances?page[offset]=50",
"first": "/containers/efca79bd-3865-4e68-88d5-30d982175c7d/instances?page[offset]=0",
"last": "/containers/efca79bd-3865-4e68-88d5-30d982175c7d/instances?page[offset]=200",
"next": "/containers/efca79bd-3865-4e68-88d5-30d982175c7d/instances?page[offset]=100",
"prev": "/containers/efca79bd-3865-4e68-88d5-30d982175c7d/instances?page[offset]=0"
},
"data": [
{
"id": "41",
"type": "instances",
"attributes": {
"instanceRevision": "fesd3",
"urn": "urn:adsk.checklists.cs.instance:efca79bd-3865-4e68-88d5-30d982175c7d/41",
"scheduledDate": "2018-05-24T15:29:29.772Z",
"location": "3ba7a68b-1cd2-4a63-a08a-cdda3e94e5ea",
"title": "Painting Checklist",
"templateVersionId": 1433,
"createdBy": "1QAZ2WSX",
"modifiedBy": "1QAZ2WSX",
"updatedAt": "2018-05-23T08:18:55.098Z",
"createdAt": "2018-05-23T08:18:55.098Z",
"deletedAt": "2018-05-23T08:18:55.098Z",
"trades": [],
"instructions": "detailed description",
"templateType": {
"id": 1,
"name": "Quality",
"permittedAttributes": [
"id"
]
},
"status": {
"id": 4,
"name": "Completed",
"urgency": 0,
"permittedAttributes": [
"id"
]
},
"signaturesStatus": "None",
"assignees": [
{
"id": 13200,
"assigneeId": "93TNJUDDTJXL",
"name": "John Doe",
"type": {
"id": 1,
"name": "User",
"permittedAttributes": [
"id"
]
},
"permittedAttributes": [
"assigneeId",
"name",
"type"
]
}
],
"progress": 0,
"completedItemsCount": 0,
"permittedActions": [
"canArchive",
"canEdit"
],
"permittedAttributes": [
"title",
"location",
"scheduledDate",
"sections",
"assignees",
"status"
],
"allowSectionAssignee": true,
"signatures": [
{
"urn": "urn:adsk.checklists.cs.instance.signature:efca79bd-3865-4e68-88d5-30d982175c7d/41",
"instanceRevision": "fesd3",
"instanceId": 11453,
"index": 11,
"requiredBy": "IKEA",
"isRequired": true,
"definedAt": "Template",
"requiredName": "Carlos",
"requiredCompany": "IKEA",
"isSigned": true,
"formalSignature": {
"instanceSignedRevision": "fesd6",
"signedName": "Rodrigo",
"signedCompany": "IKEA",
"signedAt": "2018-05-23T08:18:55.098Z",
"graphic": {
"type": "SVG",
"content": "<svg> .... </svg>",
"permittedAttributes": [
"content",
"type"
]
},
"permittedAttributes": [
"instanceSignedRevision",
"signedName",
"signedCompany",
"signedAt",
"graphic"
]
},
"updatedAt": "2018-05-23T08:18:55.098Z",
"createdAt": "2018-05-23T08:18:55.098Z",
"deletedAt": "2018-05-23T08:18:55.098Z",
"submittedBy": "1QAZ2WSX",
"permittedAttributes": [
"requiredName",
"requiredCompany",
"correlationId"
],
"permittedActions": [
"canEdit"
]
}
]
},
"relationships": {
"sections": {
"links": {
"self": "",
"related": ""
},
"meta": {},
"data": [
{
"type": "instance_sections",
"id": "1"
}
]
},
"container": {
"links": {
"self": "",
"related": ""
},
"meta": {},
"data": {
"type": "containers",
"id": "efca79bd-3865-4e68-88d5-30d982175c7d"
}
},
"createdFrom": {
"links": {
"self": "",
"related": ""
},
"meta": {},
"data": {
"type": "templates",
"id": "66"
}
}
},
"meta": {
"totalItems": 1,
"totalSections": 1,
"totalRequiredSignatures": 3,
"totalSignedSignatures": 1,
"totalUnsignedSignatures": 2
},
"links": {
"self": "",
"related": ""
}
}
]
}
Show More