V5 onwards only
This tutorial demonstrates how to upload files to 12d Synergy via the RESTful API.
The steps include:
Outline of steps to perform
Retrieving the job_id by job name
Retrieving the top-level folder_ids in a job
Retrieving the file attributes for a given folder_id
How to retrieve attribute types
How to upload a file to that folder and assign attribute values (or modify an existing file and its attribute values)
The commands are provided in curl and can be run from the command prompt when the 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 is required to be sent up 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 of the 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 can be found 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 a number of other characters that will 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 names that are similar.
The example response below contains a lot of information to sift through. So it may be easier to read it in something like Notepad++ as some of the lines can be collapsed.
There are three jobs that have been 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 sub-jobs that have the same name as top-level jobs. In this case, it may be possible to differentiate 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 can be found 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 IDString "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 getting other folder information such as ID, Name, number of sub-folders and whether or not it's a managed folder or 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 so it's only showing 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 see if the folder has required file attributes (that is, any file going to that folder is required to have a specific attribute with the value filled out).
If the file is uploaded without the required attribute values, it will fail.
For this example, the request will be made for the folder named "01 Finance & Accounting", with IDString "61381_1".
In the API Documentation, this request can be found 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, then it must be sent up with a value as part of 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 type of attribute will help determine what kind of 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 will be useful when reading the folder_id response to know what kind of attributes are coming back.
This request can also be used to get other types and can be found 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. How to upload a file to that folder and assign attribute values / modify existing file and attributes
This request can be found 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 uploaded successfully.
A note on Curl syntax
The curl syntax can be quite demanding, in particular when being executed from a batch script or the Windows command prompt. Here are a few tips that might help:
The syntax can be different when executing curl from 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 if the JSON body is all on one line, but this can make it more difficult to read. It may be easier and more readable to save the JSON as a separate file and reference that file 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.