V5 onwards only
This tutorial demonstrates how to upload files to 12d Synergy via the RESTful API.
The commands are provided in curl and can be run from the command prompt when the 12d Synergy Server is running (or in a batch script).
Additional API documentation
To get a list of most of the API requests available, with the 12d Synergy server running, browse http://synergy.myserver.com/api-docs/ui/index.
(Replace synergy.myserver.com with the external server address and update the port numbers if necessary.)
1.1. Logging in and Using Access Tokens for the API Requests
A bearer access token must be sent with each request. The tutorial for getting and updating tokens is here: Generate PAT in Web client
1.2. Outline of steps to perform
This example assumes that the developer wants to upload some files to a top-level folder in a job. But they currently only have the job name. Using the following requests, the developer can retrieve the job ID for the job and then retrieve all top-level folders under that job. Once the correct folder ID has been found, the files can be uploaded to that folder.
1.3. Retrieving the job_id by Job Name
This request is in the API documentation under Jobs, called 'Perform a quick job search'.
To get the job_id put the name of the job in the request URL(using the + symbol for spaces if there are any spaces in the name). In this example, the request is looking for a job called "My API Job".
Aside from spaces in the job name, there may be other characters that need to be escaped properly / URL encoded.
Put the new access token after the 'Authorization: Bearer' part of the header.
Find Jobs By Name Request
curl --location --request GET "http://synergy.myserver.com/api/v1/jobs/?name=My+API+Job&page=1&page_size=20" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json"Be aware that this is a search query. So, several jobs may come back with similar names.
The example response below contains a lot of information to sift through. So it may be easier to read it in an application like Notepad++, as some lines can be collapsed.
There are three jobs that are returned (the one requested is the first one, where "Name" equals "My API Job").
Each job has about 20 properties beginning with a capital letter, including Name and ID (which are the ones needed for this example).
Another property is Attributes; the first job returned has five job attributes in the array.
The ID property is made up of the "IDString" (this is the job_id followed by the server_id), the "_id" (the job_id), the "_server_guid" and the "_server_id".
It is possible to have subjobs that have the same name as top-level jobs. In this case, you can differentiate between them by looking at the ParentJobID and Path properties.
Click 
in the line below to see the code.
Find Jobs By Name Response
{
"PageNumber": 1,
"PageSize": 20,
"Result": [{
"AlwaysDisplayParent": false,
"Attributes": [{
"attribute_id": {
"IDString": "270_1",
"_id": 270,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "Job Admin",
"enum_items": null,
"id": {
"IDString": "270_1",
"_id": 270,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "Job Admin",
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 7,
"value": {
"_contact_data": {
"active": true,
"attributes": null,
"companies": null,
"create_date": "2020-09-28T22:10:02.4",
"email": "bill.posters@myCompany.com",
"first_name": "Bill",
"id": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"image_modified_date_time": "0001-01-01T00:00:00",
"is_user": true,
"last_name": "Posters [ADMIN]"
},
"_value": null,
"enum_id": null,
"value_id": {
"IDString": "21762_1",
"_id": 21762,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "269_1",
"_id": 269,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "Business",
"enum_items": null,
"id": {
"IDString": "269_1",
"_id": 269,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "Business",
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 10,
"value": {
"_company_data": {
"active": false,
"attributes": [],
"create_date": "2021-06-28T03:12:51.627",
"created_by": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"id": {
"IDString": "2_1",
"_id": 2,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"name": "GavinsGloriousGolfClubs",
"updated_date": "2021-06-28T04:55:37.633"
},
"_value": null,
"enum_id": null,
"value_id": {
"IDString": "21761_1",
"_id": 21761,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "271_1",
"_id": 271,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "Job Location",
"enum_items": null,
"id": {
"IDString": "271_1",
"_id": 271,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "Job Location",
"optional": false,
"order": 4,
"read_only": false,
"reprompt_on_change": false,
"type": 6,
"value": {
"_coordinate": {
"search_distance": 0.0,
"search_is_metric": true,
"search_wkt": "",
"x": 151.213290569302,
"y": -33.7136183885099
},
"_value": null,
"enum_id": null,
"value_id": {
"IDString": "21763_1",
"_id": 21763,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "30321_1",
"_id": 30321,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "link text",
"enum_items": null,
"id": {
"IDString": "30321_1",
"_id": 30321,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "link text",
"optional": false,
"order": 4,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "Synergy12d://sparsenesstest.12dmodelcloud.com?Folder=6e85cb75-f2c4-459c-8b18-5bb5e1a57f9c",
"enum_id": null,
"value_id": {
"IDString": "73018_1",
"_id": 73018,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "JobType",
"enum_items": null,
"id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "JobType",
"optional": false,
"order": 5,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "testing",
"enum_id": null,
"value_id": {
"IDString": "125409_1",
"_id": 125409,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}
],
"CreatedDate": "2020-11-03T00:00:06.16",
"CreatorID": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"DeleteLocked": false,
"Description": "",
"EntityObject": {
"always_display_parent": false,
"attributes": [{
"attribute_id": {
"IDString": "270_1",
"_id": 270,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "Job Admin",
"enum_items": null,
"id": {
"IDString": "270_1",
"_id": 270,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "Job Admin",
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 7,
"value": {
"_contact_data": {
"active": true,
"attributes": null,
"companies": null,
"create_date": "2020-09-28T22:10:02.4",
"email": "bill.posters@myCompany.com",
"first_name": "Bill",
"id": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"image_modified_date_time": "0001-01-01T00:00:00",
"is_user": true,
"last_name": "Posters [ADMIN]"
},
"_value": null,
"enum_id": null,
"value_id": {
"IDString": "21762_1",
"_id": 21762,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "269_1",
"_id": 269,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "Business",
"enum_items": null,
"id": {
"IDString": "269_1",
"_id": 269,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "Business",
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 10,
"value": {
"_company_data": {
"active": false,
"attributes": [],
"create_date": "2021-06-28T03:12:51.627",
"created_by": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"id": {
"IDString": "2_1",
"_id": 2,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"name": "GavinsGloriousGolfClubs",
"updated_date": "2021-06-28T04:55:37.633"
},
"_value": null,
"enum_id": null,
"value_id": {
"IDString": "21761_1",
"_id": 21761,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "271_1",
"_id": 271,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "Job Location",
"enum_items": null,
"id": {
"IDString": "271_1",
"_id": 271,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "Job Location",
"optional": false,
"order": 4,
"read_only": false,
"reprompt_on_change": false,
"type": 6,
"value": {
"_coordinate": {
"search_distance": 0.0,
"search_is_metric": true,
"search_wkt": "",
"x": 151.213290569302,
"y": -33.7136183885099
},
"_value": null,
"enum_id": null,
"value_id": {
"IDString": "21763_1",
"_id": 21763,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "30321_1",
"_id": 30321,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "link text",
"enum_items": null,
"id": {
"IDString": "30321_1",
"_id": 30321,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "link text",
"optional": false,
"order": 4,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "Synergy12d://sparsenesstest.12dmodelcloud.com?Folder=6e85cb75-f2c4-459c-8b18-5bb5e1a57f9c",
"enum_id": null,
"value_id": {
"IDString": "73018_1",
"_id": 73018,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}, {
"attribute_id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "JobType",
"enum_items": null,
"id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "JobType",
"optional": false,
"order": 5,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "testing",
"enum_id": null,
"value_id": {
"IDString": "125409_1",
"_id": 125409,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}
],
"cad_publish_output_path": "",
"create_date": "2020-11-03T00:00:06.16",
"creator_id": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"creator_name": "Bill Posters [ADMIN]",
"delete_locked": false,
"description": "<HTML><HEAD>\r\n<META name=GENERATOR content=\"MSHTML 11.00.10570.1001\"></HEAD>\r\n<BODY></BODY></HTML>",
"id": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"inherit_permissions": true,
"inherits_file_naming_rules": false,
"name": "My API Job",
"num_children": 5,
"num_folders": 108,
"num_td_projects": 3,
"parent_project_id": null,
"rule_set": null,
"type": 0
},
"ID": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"InheritFileNamingRules": false,
"InheritPermissions": true,
"JobCreatorName": "Bill Posters [ADMIN]",
"JobItems": null,
"Name": "My API Job",
"NoOfChildren": 5,
"NoOfFolders": 108,
"NoOfNotes": 0,
"NoOfTDJobs": 3,
"ParentJobID": null,
"Path": "My API Job",
"Type": "Normal"
}, {
"AlwaysDisplayParent": false,
"Attributes": [{
"attribute_id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "JobType",
"enum_items": null,
"id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "JobType",
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "testing",
"enum_id": null,
"value_id": {
"IDString": "125413_1",
"_id": 125413,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}
],
"CreatedDate": "2021-07-13T10:49:31.813",
"CreatorID": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"DeleteLocked": false,
"Description": "",
"EntityObject": {
"always_display_parent": false,
"attributes": [{
"attribute_id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "JobType",
"enum_items": null,
"id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "JobType",
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "testing",
"enum_id": null,
"value_id": {
"IDString": "125413_1",
"_id": 125413,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}
],
"cad_publish_output_path": "",
"create_date": "2021-07-13T10:49:31.813",
"creator_id": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"creator_name": "Bill Posters [ADMIN]",
"delete_locked": false,
"description": "<HTML><HEAD>\r\n<META name=GENERATOR content=\"MSHTML 11.00.10570.1001\"></HEAD>\r\n<BODY></BODY></HTML>",
"id": {
"IDString": "10011_1",
"_id": 10011,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"inherit_permissions": true,
"inherits_file_naming_rules": false,
"name": "Your API Job",
"num_children": 0,
"num_folders": 2,
"num_td_projects": 0,
"parent_project_id": null,
"rule_set": null,
"type": 0
},
"ID": {
"IDString": "10011_1",
"_id": 10011,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"InheritFileNamingRules": false,
"InheritPermissions": true,
"JobCreatorName": "Bill Posters [ADMIN]",
"JobItems": null,
"Name": "Your API Job",
"NoOfChildren": 0,
"NoOfFolders": 2,
"NoOfNotes": 0,
"NoOfTDJobs": 0,
"ParentJobID": null,
"Path": "Your API Job",
"Type": "Normal"
}, {
"AlwaysDisplayParent": false,
"Attributes": [{
"attribute_id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "JobType",
"enum_items": null,
"id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "JobType",
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "testing",
"enum_id": null,
"value_id": {
"IDString": "125414_1",
"_id": 125414,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}
],
"CreatedDate": "2021-07-13T10:52:39.537",
"CreatorID": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"DeleteLocked": false,
"Description": "",
"EntityObject": {
"always_display_parent": false,
"attributes": [{
"attribute_id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"auto_increment_start": 1,
"description": "",
"display_name": "JobType",
"enum_items": null,
"id": {
"IDString": "50433_1",
"_id": 50433,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"name": "JobType",
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": "testing",
"enum_id": null,
"value_id": {
"IDString": "125414_1",
"_id": 125414,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
}
},
"visibility_constraint": null,
"workflow_id": null
}
],
"cad_publish_output_path": "",
"create_date": "2021-07-13T10:52:39.537",
"creator_id": {
"IDString": "1_1",
"_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"creator_name": "Bill Posters [ADMIN]",
"delete_locked": false,
"description": "<HTML><HEAD>\r\n<META name=GENERATOR content=\"MSHTML 11.00.10570.1001\"></HEAD>\r\n<BODY></BODY></HTML>",
"id": {
"IDString": "10012_1",
"_id": 10012,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"inherit_permissions": true,
"inherits_file_naming_rules": false,
"name": "Some Other API Job",
"num_children": 0,
"num_folders": 2,
"num_td_projects": 0,
"parent_project_id": null,
"rule_set": null,
"type": 0
},
"ID": {
"IDString": "10012_1",
"_id": 10012,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"_server_id": 1
},
"InheritFileNamingRules": false,
"InheritPermissions": true,
"JobCreatorName": "Bill Posters [ADMIN]",
"JobItems": null,
"Name": "Some Other API Job",
"NoOfChildren": 0,
"NoOfFolders": 2,
"NoOfNotes": 0,
"NoOfTDJobs": 0,
"ParentJobID": null,
"Path": "Some Other API Job",
"Type": "Normal"
}
],
"TotalPages": 1,
"TotalRows": 3
}1.4. Retrieving the folder_ids in a Job
This request is available in the API documentation under Jobs, called "Get job items'. It will retrieve all the folders, managed folders and 12dModel projects that sit directly under the job.
Before sending this request, send the refresh token request again to get an updated access token to use in the header.
The Job ID string "1_1" that was retrieved in the previous request will be used in the URL for this new request.
This request should not be used to look for sub-jobs within a job or folder attributes. But it's good for retrieving other folder information, such as ID, Name, number of sub-folders, and whether it's a managed folder or a 12dModel project.
Get Job Items Request
curl --location --request GET "http://synergy.myserver.com/api/v1/jobs/1_1/items" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json"Below is the response, truncated to show only the first 3 folders.
Click in the line below to see the code.
Get Job Items Response
{
"HasTeam": false,
"HasIssuedFilesRegistry": true,
"SubJobs": [],
"SubFolders": [
{
"ID": {
"_id": 61360,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "61360_1"
},
"Name": "Attribute Values Source",
"ParentFolderID": null,
"JobID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"Attributes": [],
"FileAttributes": null,
"FileChangeAttributes": null,
"CreatedByID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"CreatedOn": "2022-07-22T02:03:03.2",
"InheritsPermissions": true,
"UpdatedOn": "0001-01-01T00:00:00",
"FolderType": 1,
"ActiveCheckout": null,
"HasSubFolders": false,
"Has12dProjects": false,
"IsManagedFolder": true,
"NoOfSubFolders": 0,
"NumberOf12dProjects": 0,
"FolderState": 0,
"InheritsFileAttributes": true,
"InheritsFileNamingRules": true,
"LockInfo": null,
"Type": 1,
"Path": null,
"EntityObject": null
},
{
"ID": {
"_id": 61381,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "61381_1"
},
"Name": "01 Finance & Accounting",
"ParentFolderID": null,
"JobID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"Attributes": [],
"FileAttributes": null,
"FileChangeAttributes": null,
"CreatedByID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"CreatedOn": "2022-08-25T04:47:34.72",
"InheritsPermissions": true,
"UpdatedOn": "0001-01-01T00:00:00",
"FolderType": 0,
"ActiveCheckout": null,
"HasSubFolders": false,
"Has12dProjects": false,
"IsManagedFolder": false,
"NoOfSubFolders": 0,
"NumberOf12dProjects": 0,
"FolderState": 0,
"InheritsFileAttributes": true,
"InheritsFileNamingRules": true,
"LockInfo": null,
"Type": 1,
"Path": null,
"EntityObject": null
},
{
"ID": {
"_id": 3,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "3_1"
},
"Name": "cad files",
"ParentFolderID": null,
"JobID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"Attributes": [],
"FileAttributes": null,
"FileChangeAttributes": null,
"CreatedByID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"CreatedOn": "2020-11-03T00:04:36.587",
"InheritsPermissions": true,
"UpdatedOn": "0001-01-01T00:00:00",
"FolderType": 0,
"ActiveCheckout": null,
"HasSubFolders": true,
"Has12dProjects": false,
"IsManagedFolder": false,
"NoOfSubFolders": 3,
"NumberOf12dProjects": 0,
"FolderState": 0,
"InheritsFileAttributes": false,
"InheritsFileNamingRules": true,
"LockInfo": null,
"Type": 1,
"Path": null,
"EntityObject": null
},
],
"Forums": []
}1.5. Retrieving the File Attributes for a given folder_id
Before uploading files to a folder, a request should be sent to check whether the folder has the required file attributes (that is, any file going to that folder must have a specific attribute with its value filled out).
If the file is uploaded without the required attribute values, it will fail.
For this example, the request is made for the folder named "01 Finance & Accounting", with IDString "61381_1".
In the API Documentation, this request is under Folders, called 'Get a folder by ID'.
If the request is successful, the folder information returned is mostly the same as what was given in the previous response. But if the retrieve_attributes parameter = true, the attributes for that folder are also returned.
Sift through the attributes and check if their "optional" properties are false. If an attribute has "optional": false, it must be sent with a value in the FileUploadModel.
Get Folder by ID Request
curl --location --request GET "http://synergy.myserver.com/api/v1/folders/61381_1?retrieve_attributes=true" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json"Below is the response showing there are two file attributes attached to the folder, one called Status and the other called Revision (both with "optional": false).
Aside from the ID, the attribute "type" is also important. The attribute type will help determine which values are allowed.
The "Status" attribute is a "list" type attribute (type 4). This list offers three possible values or "enum_items": "WIP", "In Review" and "Approved".
The "Revision" attribute is a "text" type attribute (type 0). It will accept any alphanumeric characters and any special characters.
Click in the line below to see the code.
Get Folder by ID Response
{
"ID": {
"_id": 61381,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "61381_1"
},
"Name": "01 Finance & Accounting",
"ParentFolderID": null,
"JobID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"Attributes": [],
"FileAttributes": [
{
"auto_increment_start": 1,
"description": "",
"enum_items": [
{
"visibility_constraint": null,
"enum_id": {
"_id": 108,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "108_1"
},
"value": "WIP",
"display_name": "WIP",
"hidden": false,
"id": {
"_id": 108,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "108_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 109,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "109_1"
},
"value": "In Review",
"display_name": "In Review",
"hidden": false,
"id": {
"_id": 109,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "109_1"
}
},
{
"visibility_constraint": null,
"enum_id": {
"_id": 110,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "110_1"
},
"value": "Approved",
"display_name": "Approved",
"hidden": false,
"id": {
"_id": 110,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "110_1"
}
}
],
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 1,
"read_only": false,
"reprompt_on_change": false,
"type": 4,
"value": {
"_value": null,
"enum_id": null,
"value_id": null
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50507,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50507_1"
},
"name": "Status",
"display_name": "Status",
"id": {
"_id": 50507,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50507_1"
}
},
{
"auto_increment_start": 1,
"description": "",
"enum_items": null,
"input_mask": "",
"is_auto_increment": false,
"is_visible": true,
"optional": false,
"order": 2,
"read_only": false,
"reprompt_on_change": false,
"type": 0,
"value": {
"_value": null,
"enum_id": null,
"value_id": null
},
"visibility_constraint": null,
"workflow_id": null,
"attribute_id": {
"_id": 50508,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50508_1"
},
"name": "Revision",
"display_name": "Revision",
"id": {
"_id": 50508,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "50508_1"
}
}
],
"FileChangeAttributes": [],
"CreatedByID": {
"_id": 1,
"_server_id": 1,
"_server_guid": "cd877c4c-ca8f-4476-83fe-9a2cf107621c",
"IDString": "1_1"
},
"CreatedOn": "2022-08-25T04:47:34.72",
"InheritsPermissions": true,
"UpdatedOn": "0001-01-01T00:00:00",
"FolderType": 0,
"ActiveCheckout": null,
"HasSubFolders": false,
"Has12dProjects": false,
"IsManagedFolder": false,
"NoOfSubFolders": 0,
"NumberOf12dProjects": 0,
"FolderState": 0,
"InheritsFileAttributes": true,
"InheritsFileNamingRules": true,
"LockInfo": null,
"Type": 1,
"Path": "My API Job/01 Finance & Accounting/",
"EntityObject": null
}For more details about Attributes, please refer to the Attributes page.
1.6. How to Retrieve AttributeTypes
Below is a request to get our current AttributeTypes and their enum values. This is useful when reading the folder_id response to determine which attributes are returned.
This request can also be used to get other types and is in the API documentation under Types, labelled 'Get a list of available options from given enum type_name'.
For example, change type=Contracts.Data.AttributeType to type=Contracts.Data.RoleAccessType to find the enum values for various roles and access.
Get Any Type Request
curl --location --request GET "http://synergy.myserver.com/api/v1/types?type=Contracts.Data.AttributeType" ^
--header "Authorization: Bearer <token>" ^
--header "Content-Type: application/json"Click in the line below to see the code.
Get Any Type Response
{
"Type": "Contracts.Data.AttributeType",
"List": [
{
"Name": "String",
"Value": 0
},
{
"Name": "Integer",
"Value": 1
},
{
"Name": "Real",
"Value": 2
},
{
"Name": "Date",
"Value": 3
},
{
"Name": "Enum",
"Value": 4
},
{
"Name": "User",
"Value": 5
},
{
"Name": "Coordinate",
"Value": 6
},
{
"Name": "Contact",
"Value": 7
},
{
"Name": "YesNo",
"Value": 8
},
{
"Name": "Address",
"Value": 9
},
{
"Name": "Company",
"Value": 10
}
]
}1.7. Uploading a File to that Folder and Assigning Attribute values / Modifying the Existing File and Attributes
This request is in the API documentation under Files, marked "Use this method to upload or add a new file".
The path to the file being uploaded and the FileUploadModel (JSON body) must both be supplied as multi-part form data.
The FileUploadModel must include the destination folder ID and any relevant attribute information.
In the example below, the Status attribute is given a value of "WIP", and the Revision attribute is given a value of "A".
A response of true means the file has been uploaded successfully.
A note on Curl syntax
The curl syntax can be quite demanding, particularly when executed from a batch script or the Windows command prompt. Here are a few tips that might help:
The syntax can differ when executing curl across different environments. With the Windows command prompt, the ^ character is used instead of ` for a new line.
In the form model below, a single backslash will escape the " marks, but this will only work if there are no spaces in the strings. 3 backslashes are required before the " marks to fix this.
Curl is less picky when the JSON body is on a single line, but this can make it harder to read. It may be easier and more readable to save the JSON as a separate file and reference it in the curl request.
In the form model below, the square brackets for an array of objects must be placed on an individual line.
If a null reference error is returned, it likely means the deserialised data is null, because the JSON string was not formatted correctly.
Click in the line below to see the code.
Upload File Request
curl --location --request POST "http://synergy.myserver.com/api/v1/files/upload" ^
--header "Authorization: Bearer <token>" ^
--header "multipart/form-data" ^
--form "file=@"C:\Users\bill.posters\Desktop\test.txt"" ^
--form "model=\" ^
{ ^
\\\"operation\\\":0, ^
\\\"file_name\\\":\\\"test.txt\\\", ^
\\\"keep_check_out\\\":false, ^
\\\"id\\\": ^
{ ^
\\\"_id\\\":61381, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"61381_1\\\" ^
}, ^
\\\"description\\\":\\\"file uploaded by curl\\\", ^
\\\"file_attributes\\\": ^
[ ^
{ ^
\\\"auto_increment_start\\\":1, ^
\\\"description\\\":\\\"\\\", ^
\\\"enum_items\\\": ^
[ ^
{ ^
\\\"visibility_constraint\\\":null, ^
\\\"enum_id\\\": ^
{ ^
\\\"_id\\\":108, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"108_1\\\" ^
}, ^
\\\"value\\\":\\\"WIP\\\", ^
\\\"display_name\\\":\\\"WIP\\\", ^
\\\"hidden\\\":false, ^
\\\"id\\\": ^
{ ^
\\\"_id\\\":108, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"108_1\\\" ^
} ^
}, ^
{ ^
\\\"visibility_constraint\\\":null, ^
\\\"enum_id\\\": ^
{ ^
\\\"_id\\\":109, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"109_1\\\" ^
}, ^
\\\"value\\\":\\\"In Review\\\", ^
\\\"display_name\\\":\\\"In Review\\\", ^
\\\"hidden\\\":false, ^
\\\"id\\\": ^
{ ^
\\\"_id\\\":109, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"109_1\\\" ^
} ^
}, ^
{ ^
\\\"visibility_constraint\\\":null, ^
\\\"enum_id\\\": ^
{ ^
\\\"_id\\\":110, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"110_1\\\" ^
}, ^
\\\"value\\\":\\\"Approved\\\", ^
\\\"display_name\\\":\\\"Approved\\\", ^
\\\"hidden\\\":false, ^
\\\"id\\\": ^
{ ^
\\\"_id\\\":110, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"110_1\\\" ^
} ^
} ^
], ^
\\\"input_mask\\\":\\\"\\\", ^
\\\"is_auto_increment\\\":false, ^
\\\"is_visible\\\":true, ^
\\\"optional\\\":false, ^
\\\"order\\\":1, ^
\\\"read_only\\\":false, ^
\\\"reprompt_on_change\\\":false, ^
\\\"type\\\":4, ^
\\\"value\\\": ^
{ ^
\\\"_value\\\":\\\"WIP\\\", ^
\\\"enum_id\\\": ^
{ ^
\\\"_id\\\":108, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"108_1\\\" ^
}, ^
\\\"value_id\\\":null ^
}, ^
\\\"visibility_constraint\\\":null, ^
\\\"workflow_id\\\":null, ^
\\\"attribute_id\\\": ^
{ ^
\\\"_id\\\":50507, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"50507_1\\\" ^
}, ^
\\\"name\\\":\\\"Status\\\", ^
\\\"display_name\\\":\\\"Status\\\", ^
\\\"id\\\": ^
{ ^
\\\"_id\\\":50507, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"50507_1\\\" ^
} ^
}, ^
{ ^
\\\"auto_increment_start\\\":1, ^
\\\"description\\\":\\\"\\\", ^
\\\"enum_items\\\":null, ^
\\\"input_mask\\\":\\\"\\\", ^
\\\"is_auto_increment\\\":false, ^
\\\"is_visible\\\":false, ^
\\\"optional\\\":false, ^
\\\"order\\\":2, ^
\\\"read_only\\\":false, ^
\\\"reprompt_on_change\\\":false, ^
\\\"type\\\":0, ^
\\\"value\\\": ^
{ ^
\\\"_value\\\":\\\"A\\\", ^
\\\"enum_id\\\":null, ^
\\\"value_id\\\":null ^
}, ^
\\\"visibility_constraint\\\":null, ^
\\\"workflow_id\\\":null, ^
\\\"attribute_id\\\": ^
{ ^
\\\"_id\\\":50508, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"50508_1\\\" ^
}, ^
\\\"name\\\":\\\"Revision\\\", ^
\\\"id\\\": ^
{ ^
\\\"_id\\\":50508, ^
\\\"_server_id\\\":1, ^
\\\"_server_guid\\\":\\\"cd877c4c-ca8f-4476-83fe-9a2cf107621c\\\", ^
\\\"IDString\\\":\\\"50508_1\\\" ^
} ^
} ^
], ^
\\\"change_attributes\\\":null, ^
\\\"workflow_capture_data\\\":null ^
}\"" The same request can be used to upload a newer version of the file and adjust attribute values if necessary.