API

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.


Getting Started

This section will discuss the steps required to enable the API and begin using it.

Csreate an API Key

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.

Create API Key

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.

API Key List

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.

Company ID

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.

Parameters for All 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

JSON Result

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.


File API

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.
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 Link API

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 recipientEmail The recipient(s) email address. Separate by comma or a semicolon if multiple.
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 itemValues Comma separated list of the item values.
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"]}


Uploader Status API

The Uploader Status API allows you to obtain any errored Uploader Status logs programmatically. To retrieve the current list of errored uploads using 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 objects 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 itemNameList 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 “Uploads with error” otherwise it will be the error message.
List objects 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 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