The Flatter Files application programing interface (API) allows you to perform specific tasks programmatically. This document will show how to get started with the API and describe in detail the current methods available via the API. Additional methods will be added to API over time.
This section will discuss the steps required to enable the API and begin using it.
Login to Flatter Files as an Administrator and go to Dashboard > Settings > Company > Scroll to the bottom > Misc Settings > Check the box for “Enable API Access” > Click “Manage API Keys” > Click “New.” This displays an option to enter a specific allowable IP address and an option to specify that the user agent must contain a specific value.
Specifying part or all of the user agent string allows you to only allow specific devices or applications to use the resulting key. For example, you could add custom text to the user agent string in the application you are developing at which point the key would only work if that unique value is present in the user agent. If you leave both values blank then all IP Addresses and all devices can access the API using that particular key. Click “Submit” and a new key should be listed.
Double click the entry and you should be able to copy the actual key value. This key is important and should not be shared since it is what gives you access to the content. Multiple keys can be created. Thus, it is recommended that each application that uses the API should have its own API key such that requests from different applications can easily be tracked.
A Company ID is a unique number that identies your account. To obtain your Company ID, email [email protected]. The Company ID is needed when making all API requests.
The API Key and Company ID should be added as parameters to every request made to the API. All requests can be made as either a GET request or POST request but it is recommended that POST be used. The parameter names are the following:
cmpyID={cmpyID}
apiKey={apiKey}
Thus, if you are making a GET request using any of the URLs shown below then you would add the values to the URL as shown below where the cmpyID and apiKey are equal to 1234:
?cmpyID=1234&apiKey=1234
All API results are returned as a JSON object. The JSON object contains a Boolean property named “error” and a String property named “result” at a minimum. In addition, sometimes additional object data will be passed along in a third parameter either named “object” or “objects.” The JSON response for each method is detailed below in each API description. Keep in mind that the JSON string returned will escape all special characters automatically. Thus, if you read the JSON result as just a simple string the data will contain the escape codes. Thus, it is highly recommended that you use a tool designed to parse JSON. JSON parsing libraries exist for all common languages and frameworks.
Any file that has been uploaded to Flatter Files can be programmatically retrieved via the API. The following URL form is used to retrieve files.
https://www.flatterfiles.com/api/{content-type}/{param}/{value}
| Inputs | |
|---|---|
| content-type | File type name such as pdf, step, preview, etc. Use aslypdf to retrieve Assembly View if exists |
| param | The item identifier property name used such as filename, pdmid, partnumber, etc. |
| value | The item identifier value. |
| pdmVer (optional) | Require the item to have a specific pdm version otherwise the file is not returned. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | Secure URL that can be used to obtain the file data directly. URL will only work for one minute. |
Examples
Obtain the pdf for part number BD-0001:
https://www.flatterfiles.com/api/pdf/partnumber/BD-0001
Specify that the PDM Version is 10:
https://www.flatterfiles.com/api/pdf/partnumber/BD-0001?pdmVer=10
External links can be created programmatically. This allows you to have a third-party application such as the software that is used to generate POs and/or manage your BOM’s automatically create the Flatter Files external link. The link can then be added directly to the PO or any customer document sent to the supplier.
The following URL is used to create links.
https://www.flatterfiles.com/api/link/external
You must also include the parameter “input” which is a json string with the following values:
| JSON Input | |
|---|---|
| String senderEmail | An email address for an internal user that has the ability to share items externally. |
| List |
The recipient(s) email address as a json list. |
| String password | Password required to access link. Must be at least 6 characters. |
| String param | The item identifier property name used such as filename, pdmid, partnumber, etc. |
| List |
List of the item values as a json list. |
| Optional Prameters | |
| Boolean sendEmail | Indicates whether email to recipient should be sent. Default is false. |
| String messageText | Any additional text that should be included in email message. |
| String notes | Value that will show up in the Notes column when viewing the link in “My Shared Items.” |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful, external link otherwise error message. |
Example
Create a link with [email protected] as the sender and [email protected] as the recipient:
https://www.flatterfiles.com/api/link/external?input=
{"recipientEmail":["[email protected]"],
"senderEmail":"[email protected]",
"password":"123456","param":"partnumber",
"itemValues":["BD-0005","BD-0004"]}
User accounts can be created and deleted programmatically. This allows you to have a third-party application automatically manage your Flatter Files users using the following URL:
https://www.flatterfiles.com/api/user/{command}
There are currently 2 supported commands: create, delete. Each will be detailed below.
The following URL is used to create users.
https://www.flatterfiles.com/api/user/create
You must also include the parameter “input” which is a json string with the following values:
| JSON Input | |
|---|---|
| String email | Email address for the new user. |
| String firstName | First name for the new user. |
| String lastName | Last name for the new user. |
| Optional Prameters | |
| String password | Password for new user (min 7 characters). If not included then initial password is auto generated. |
| String userGroupName | Specify user group name to auto add the user to it. |
| Boolean useGroupForSettings | If true then the user group specified will also be used for the user’s settings. |
| String notes | Value that will show up in the Notes column of the User settings list. |
| Boolean skipEmail | If true then the initial email with password will not be sent to the user. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
Example
Create a user for John Doe with the email address [email protected]:
https://www.flatterfiles.com/api/user/create?input=
{"email":"[email protected]",
"firstName":"John",
"lastName":"Doe"}
The following URL is used to delete users.
https://www.flatterfiles.com/api/user/delete
You must also include the parameter “input” which is a json string with the following values:
| JSON Input | |
|---|---|
| String email | Email address for the user. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
Example
Delete a user with the email address [email protected]:
https://www.flatterfiles.com/api/user/delete?input=
{"email":"[email protected]"}
User group membership can be managed programmatically. The following URL is used:
https://www.flatterfiles.com/api/usergroup/{command}
There are currently 4 supported commands: list, remove, add, create. Each will be detailed below.
To retrieve a list of email addresses for each use contained within the user group, the following url is used:
https://www.flatterfiles.com/api/usergroup/list
You must also include the following input.
| Inputs | |
|---|---|
| String groupName | Name of the user group. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
| List |
List of emails address for the users in the group. |
To remove a user from the user group the following url is used:
https://www.flatterfiles.com/api/usergroup/remove
You must also include the following inputs.
| Inputs | |
|---|---|
| String groupName | Name of the user group. |
| String userEmail | Email of the user that should be removed from the group. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
To add a user to the user group the following url is used:
https://www.flatterfiles.com/api/usergroup/add
You must also include the following inputs.
| Inputs | |
|---|---|
| String groupName | Name of the user group. |
| String userEmail | Email of the user that should be removed from the group. |
| String useGroupForSettings | Enter value of “YES” or “true” to use the group profile settings for the user’s settings. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
Example
Add user with the email address [email protected] to the user group Purchasing:
https://www.flatterfiles.com/api/usergroup/add?
groupName=Purchasing
To create a new user group the following url is used:
https://www.flatterfiles.com/api/usergroup/create
You must also include the following inputs.
| Inputs | |
|---|---|
| String groupName | Name of the new user group. The name must be unique. |
| Optional Prameters | |
| String settingsGroupName | Enter name of user group that should be used for the initial profile settings of the group |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
Example
Create a user group with the name “New” that starts with the settings from the user group “Current:”
https://www.flatterfiles.com/api/usergroup/create?
groupName=New
&settingsGroupName=Current
Libraries can be managed programmatically. The following URL is used:
https://www.flatterfiles.com/api/library/{command}
There are currently 2 supported commands: list, and create. Each will be detailed below.
The following URL is used to list the items currently contained within a Library.
https://www.flatterfiles.com/api/library/list
You must also include the parameter “input” which is a json string with the following values:
| JSON Input | |
|---|---|
| String name | Name for the Library. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
| List |
List of item objects located in the Library. |
Example
List the items located in a Library with the name Drawings:
https://www.flatterfiles.com/api/library/list?input=
{"name":"Drawings"}
The following URL is used to create a Library.
https://www.flatterfiles.com/api/library/create
You must also include the parameter “input” which is a json string with the following values:
| JSON Input | |
|---|---|
| String name | Name for the new Library. |
| Optional Prameters | |
| String parentName | Name of the parent Library, if not included then Library will be a root Library. |
| Boolean visibleByDefault | Determines if Library is visible to users by default. If not included value is true . |
| Boolean sendEmails | Specifies if new item and new rev emails should enabled for this library if user currently has emails enabled. |
| Boolean isSmart | Specifies if the new Library is a smart Library |
| String smartQuery | The query for the smart Library. |
| API Result | |
| Boolean error | Indicates if request resulted in error or not. |
| String result | If error, message indicating the cause. |
Example
Create a Library with the name New Library:
https://www.flatterfiles.com/api/library/create?input=
{"name":"New Library"}
The Uploader Status API allows you to obtain any Uploader Status logs programmatically containing an error. To retrieve the current list of uploads use the following URL:
https://www.flatterfiles.com/api/uploaderUploads/error
This returns a JSON object with the properties shown in the table below where an UploaderUpload is an object that describes the Upload status.
| API Result | |
|---|---|
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful “Uploads with error” otherwise it will be the error message. |
| List |
List of UploaderUpload objects |
The UploaderUpload objects that are returned contain the properties described by the table below:
| UploaderUpload | |
|---|---|
| Long ident | Random number id for each object |
| Long cmpyID | Company ID |
| String userID | User ID of the user logged into the Uploader |
| Date uploadStartDate | Date of the upload start |
| String uploadStartString | Local machine start date as string that matches local machine clock. |
| String computerName | Computer name |
| Date lastSavedDate | Last saved date for this upload object |
| Boolean containsError | Indicates if error or not |
| List |
List of item names uploaded during this upload |
To obtain the actual messages that occurred during the upload the following URL can be used.
https://www.flatterfiles.com/api/uploaderMessages/{ident}
Where the {ident} is the ident property in the appropriate UploaderUpload object.
| API Result | |
|---|---|
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful the UploaderUpload ident otherwise it will be the error message. |
| List |
List of UploaderMessage objects |
The UploaderMessage objects that are returned contain the properties described by the table below:
| UploaderMessage | |
|---|---|
| Long ident | Random number id for each object |
| Long uploadIdent | Upload object id |
| Long cmpyID | Company ID |
| Date messageDate | Date of the message |
| int entryNumber | Message entry number |
| String message | Message |
| String computerName | Computer name |
| Long uploadIdent | Random number id for the corresponding parent UploaderUpload object |
| Long itemName | Name of item |
| Boolean isError | Indicates if message is an error message |
A list of all the error messages that have occurred in the last 24 hours can be obtained by using the following url:
https://www.flatterfiles.com/api/uploaderMessages/error
| API Result | |
|---|---|
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful “Messages with Error” otherwise it will be the error message. |
| List |
List of UploaderMessage objects |
The History API allows you to obtain any History entries programmatically. To retrieve the current list of history entires use the following URL:
https://www.flatterfiles.com/api/history
This returns a JSON object with the properties shown in the table below where a Stat is an object that describes the history entry. By default the last hour of Stat objects will be returned in reverse chronological order. If additional entries are desired you can define the parameter “hours” and enter a value greater than 1 to indicate the number of hours of Stat objects that should be returned.
| API Result | |
|---|---|
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful “History” otherwise it will be the error message. |
| List |
List of Stat objects |
The Stat objects that are returned contain the properties described by the table below. Not all properties are included depending on if they are applicable or not for the stat.
| Stat | |
|---|---|
| Long ident | Random number id for each object |
| Long cmpyIdent | Company ID |
| String userID | User ID of the user that caused the stat (not used for share stats) |
| Date date | Date the stat occurred |
| String action | View, Download, Print, Search, Login, Email |
| String fileType | If search this is the search query, otherwise the file type |
| Boolean isInternal | Indicates if internal stat (not shared link) |
| String ipAddress | IP Address |
| String deviceType | Desktop, Mobile, Unknown |
| String deviceName | iPhone, iPad, Windows, etc.. |
| String appName | Web App, Chrome; Web App, Firefox, App |
| Long shareID | ID of share link |
| String email | Email used to login to share link |
| String shareNotes | Share notes |
| String itemID | ID of the item |
| String rev | Revision of the item |
| String partNumber | Part Number of the item |
| String description | Description of the item |
| String extraProperty | User defined property value of the item |
The Items API allows you to obtain item information programmatically. To retrieve a list of all items use the following URL:
https://www.flatterfiles.com/api/items
This returns a list of item objects. Only 500 items at a time will be returned. If there are more then 500 items remaining the property “cursor” is included in the result. Add the parameter “cursor” with the corresponding value and make an additional request to retrieve the next 500 items. Repeat until the cursor value isn’t returned at which point all items will have been returned.
| API Result | |
|---|---|
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful “Items” otherwise it will be the error message. |
| List |
List of Item objects |
| String cursor | Only included if more than 500 items are being returned. User cursor to get more items. |
A specific item can be retrieved by adding a param and value combination to the URL as shown below:
https://www.flatterfiles.com/api/items/{param}/{value}
| Inputs | |
|---|---|
| param | The item identifier property name used such as filename, pdmid, partnumber, etc. |
| value | The item identifier value. |
When specifying a parameter and value the result will be the following.
| API Result | |
|---|---|
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful “Item” otherwise it will be the error message. |
| Item object | The Item object returned. |
In addition to retrieving a specific item, you can specify a command to modify the item using the URL as shown below:
https://www.flatterfiles.com/api/items/{param}/{value}/{command}
| Commands | |
|---|---|
| deactivate | The item is updated to inactive. |
| activate | The item is updated to active. |
When specifying a command the result will be the following.
| API Result | |
|---|---|
| Boolean error | Indicates if request resulted in error or not. |
| String result | If successful will indicate the command used otherwise it will be the error message. |
| Item object | The Item object returned. |