{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"026be0fb-669a-492d-9b38-71f8a3e2cae2","name":"FACS - Public API","description":"This API is a RESTful API that allows you to both retrieve data from FACS and submit new records to FACS. This API is dynamic and the requirements of some requests will change as the configuration of your FACS system changes. For this reason, the API includes several metadata endpoints that allow you to view the current list of resources you are allowed to access and the current requirements needed to submit new records.\n\nThe API enables the interaction with FACS resources such as Users, Projects and Companies. The API allows the interaction with both Project level and Portal level resources. Portal level resources are resources that are available and remain consistent throughout the portal. Project level resources are resources that are added and configured for a specific project. The API provides separate endpoints for dealing with Portal level and Project level resources.\n\n# Glossary\n\n*   **API** – Application Programming Interface. The mechanism that allows programmatic interaction with the FACS platform\n*   **FACS Platform** – The web application that stores all data and provides functionality to manage projects and documents\n*   **portal** – the account with the FACS platform that you login to that contains all configurations and resource entries\n*   **resource** – any of the service types available within the FACS platform. (service, sub-service, data-project, data-portal)\n    *   **portal level resource** – a resource that stores its entries for the whole portal\n    *   **project level resource** – a resource that stores its entries within a specific project\n*   **project** – the container within the FACS platform to store all data related to a construction project\n*   **entry** – a single record within a resource\n*   **field** – the definition of how an item of data is stored with an entry\n*   **field options** – the list of valid options for a particular field. Field options only apply to certain field types\n*   **field types** – the type of fields available within the FACS platform. (text, number, date,...etc.)\n*   **JWT** - JSON web token, is an open standard that defines a compact and secure method of transmitting information between parties. After logging into the API, a JWT will be returned. This JWT should be sent on subsequent requests.\n    \n\n# Security\n\n*   SSL Encryption - The API is only available via SSL encryption. The FACS Platform uses a 2048 bit key with RSA Encryption.\n*   Credentials - To interact with the API you will need to supply valid credentials for a user within your FACS system. This is the same email and password used to log in via the web app or the mobile app. After successfully logging in, a token will be returned in the response payload. This token should be submitted on all subsequent requests to the API in the `Authorization` header. The value of the header should be: `Bearer PUT_TOKEN_HERE`\n*   Permissions - The API uses the same permission scheme as the web application and the mobile application. To access resources via the API, you must use a user account that has been granted access to read and/or write to those resources.\n    \n\n# Rate Limiting\n\nThis FACS API employs rate limiting to safeguard against bursts of incoming traffic to help maximize its stability. A rate limiter is in place to restrict users to 60 requests per minute. When the rate limit is exceeded a `429` response code will be returned with the message `Too Many Attempts.`.\n\n# Portal and Project Level Resources\n\nThis API allows the interaction of both Portal level and Project level resources. Portal level resources as resources that are available throughout the FACS platform. While Project level resources are tied to a project and only available within that project. The API has different endpoints for interacting with Portal level resources and Project level resources.\n\n# Portal Param\n\nAll requests are required to send a URL query param named `portal`. This is the same value you enter into the `portal` field when logging into the web application or the mobile application. POST requests can have the `param` submitted in the body of the request instead.\n\n# Accept Header\n\nAll requests must have the `Accept` header set to the value of `application/json`. Submitting this header with every request will ensure you receive the proper json response from the API.\n\n# Submitting Data\n\nThere are several endpoints that allow you to submit data to create new records or update existing records. In both cases the HTTP method should be `POST` and data should be submitted as `multipart/form-data`. The `Content-Type` header should be included with these requests with a value of `multipart/form-data`.\n\nWhen updating a resource entry or trying to create a new resource entry you will need to use the endpoints to get the list of fields that make up that resource. To submit a value for a resource entry the request body (form-data) fields should be named in the following format. `field_{FIELD_ID}`. For example to submit a value for a field with the id of 4 the request body would have a field named `field_4`. The value of that form field can be any valid value for that field type. The API will return errors if an invalid value was submitted for any of the fields in the request.\n\nSome fields can only accept values from a specific list of options. If a field has the `has_options` property set to `True` , then field only accepts specific values. You can use the `public/api/field_options/{FIELD_ID}` endpoint to retrieve the list of valid options. When submitting the value, you submit either the `id` or the `label`. If submitting the option's label, the value must match exactly including the case of letters.\n\nSome fields that accept specific options can receive multiple values. To submit multiple values, separate the values using a comma `,`.  \nExample Values: `1234,3456` or `John Doe,Jane Doe,Facs Rep`\n\nNote: if the value contains a comma `,`, you must submit it using the option's `id` instead of the `label`.\n\n### Sub Services\n\nSome resources contain sub services. The enable you create new record entries are associated with a parent entry. Sub service entries must be submitted after a parent entry is created.\n\n# REST HTTP Methods\n\nThe API uses to different HTTP methods for accessing and modifying data stored in the FACS platform. Please refer to the table below to see what HTTP Method should be used for each action.\n\n| Action | HTTP Method | Example URL Route |\n| --- | --- | --- |\n| Retrieve a list of resource entries | GET | /public-api/resources/1/entries |\n| Retrieve a specific resource entry | GET | /public-api/resources/1/entries/200 |\n| Create a new resource entry | POST | /public-api/resources/1/entries |\n| Update a resource entry | POST | /public-api/resources/1/entries/200 |\n| Delete a resource entry | DELETE | /public-api/resources/1/entries/200 |\n| Login | POST | /public-api/login |\n\n# Pagination\n\nSome endpoints return a list of records. These lists will be paginated and will only return a fixed amount of records on each request. Below is an example of a paginated response.\n\n```\n{\n    \"current_page\": 1,\n    \"data\": [\n        {\n            \"id\": 2,\n            \"label\": \"Company\"\n        },\n        {\n            \"id\": 4,\n            \"label\": \"Project\"\n        },\n        {\n            \"id\": 10,\n            \"label\": \"Project Role\"\n        },\n.... Results Truncated .... \n        {\n            \"id\": 1,\n            \"label\": \"User\"\n        }\n    ],\n    \"from\": 1,\n    \"last_page\": 5,\n    \"next_page_url\": \"/public-api/resources/?page=2\",\n    \"path\": \"/public-api/resources/\",\n    \"per_page\": 25,\n    \"prev_page_url\": null,\n    \"to\": 25,\n    \"total\": 106\n}\n\n```\n\nBelow is a description of each param returned in a paginated response.\n\n| Response Key | Description |\n| --- | --- |\n| current_page | The current page of records returned |\n| data | The list of returned records |\n| from | The start point of the records in the response |\n| last_page | The number of the last page in the list of records |\n| next_page_url | The url path of the next page of results |\n| path | The start point of the records in the response |\n| per_page | The current page of results returned |\n| prev_page_url | The url path of the previous page of results |\n| to | The end point of the records in the response |\n| total | The total number of records |\n\nBy default, you will receive the 1st page of records when retrieving a paginated resource. To select a different page, append a `page` query parameter to your request with the value being the page number you would like to retrieve. You can customize the number of records returned by appending the `per_page` query parameter to the request URL.\n\n| Query Parameter | Type | Description |\n| --- | --- | --- |\n| page | int | The page number to retrieve |\n| per_page | int | The amount of records to return on each page |\n\n# Sorting\n\nAll endpoints that return a list of records support sorting. Sorting can be performed on any of the fields returned in the results response.\n\n| Query Parameter | Type | Description |\n| --- | --- | --- |\n| sort | string | The label of the field to sort the records |\n| sort_direction | string | The direction of the sorted results. Valid values are 'asc' and 'desc' for ascending and descending respectively. (The default is 'asc').**  <br>Note: when specifying the 'sort_ direction' you must all provide a value for the 'sort' query param.** |\n\n# Filtering\n\nAll endpoints that return a list of records support filtering. Filtering can be performed on any of the fields returned in the results response.\n\n| Query Parameter | Type | Description |\n| --- | --- | --- |\n| filter\\[\\] | string | A pipe (\" |\n\nNote: The `filter[]` parameter can be repeated in a URL to submit multiple filters.\n\nExample: `/public-api/resources/1/entries?portal=portal&filter[]=Role|==|Admin&filter[]=Email|=@|test_company.com`\n\nThe following table lists the available operators that can be used in a filter\n\n| Filter Operator | Description |\n| --- | --- |\n| \\== | Match records that equal the specified value |\n| \\=@ | Match records that contain the specified value |\n| < | Match records that are less than the specified value |\n| <= | Match records that are less or equal to the specified value |\n| \\> | Match records that are greater than the specified value |\n| \\> | Match records that are greater or equal to the specified value |\n\n# Timestamps\n\nSome records returned by the API will contain `created_at` and `updated_at` fields in the API response. These values are formatted as unix timestamps in milliseconds. Using these values you can determine when a record was created or when it was last updated. These values can also be very useful in filtering records to limit the result set to show only the time interval you are interested in.\n\n# API Responses\n\nThis REST API uses the following HTTP Response codes to indicate the result of a request.\n\n| Response Code | Description |\n| --- | --- |\n| 200 | The request was successfully processed |\n| 400 | Invalid request. Recheck the request requirements |\n| 401 | The user is not authenticated. Check the authorization header and the `portal` query param |\n| 403 | The user is not authorized for this action |\n| 404 | The specified resource/record was not found |\n| 422 | Invalid request. Check the response for information about invalid fields |\n| 429 | The rate limit has been exceeded |\n| 500 | Internal server error |\n\n# API Limitations\n\nThe API allows for you to interact with many types of resources that are available in the FACS system, however, there are some resources and fields types that can not be accessed via the API. Currently, files can not be retrieved or submitted via the API. When retrieving a resource that contains a file, metadata about that file will be retrieved, but not the contents of the file.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"16185843","collectionId":"026be0fb-669a-492d-9b38-71f8a3e2cae2","publishedId":"UUy4bjod","public":true,"publicUrl":"https://api-docs.facsware.com","privateUrl":"https://go.postman.co/documentation/16185843-026be0fb-669a-492d-9b38-71f8a3e2cae2","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.4","publishDate":"2021-10-05T16:46:12.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"FACS Public API - Production Environment","id":"1459059f-309f-454d-921f-ad2880c5777e","owner":"16185843","values":[{"key":"email","value":"your_user_email@test.com","enabled":true},{"key":"password","value":"your_user_password","enabled":true},{"key":"domain","value":"app.facsware.com","enabled":true},{"key":"portal","value":"your_portal","enabled":true},{"key":"prefix","value":"public-api","enabled":true},{"key":"token","value":"YOUR_TOKEN_HERE","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://facsware.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"FACS Public API - Production Environment","value":"16185843-1459059f-309f-454d-921f-ad2880c5777e"}],"canonicalUrl":"https://api-docs.facsware.com/view/metadata/UUy4bjod"}