# Introduction ## Extend the power of WorkSmart with REST APIs and Webhooks You can integrate between WorkSmart and your applications using REST Web API or Webhooks. Check below links to understand how you can use REST Web API or Webhooks based on your requirements: {% content-ref url="/pages/-MVNNVJzsQW7Bu7Ctq1g" %} [REST Web API](/web-api) {% endcontent-ref %} {% content-ref url="/pages/-MVS8pt0TsSaDjO4P8fn" %} [Webhook](/webhook) {% endcontent-ref %} # REST Web API ### **Introduction** WorkSmart Web API, based on REST principles, allows your application to retrieve and manage your WorkSmart content. You can perform operations like adding a new record to your application or editing an existing record. Also can add comments to your record if you have comments plugin enabled for your application. Refer the links from the left menu to gain more information how you can perform these operations using WorkSmart Web API. ### **Manage your WorkSmart Applications** Before you start using API, your application must be registered into your WorkSmart portal. This will generate a unique client id and a secret key which will be required for authorization requests. Follow the steps listed below to register your application for API usage : * Go to Web API Setting page from “System Admin > Portal Settings > Web API Setting”. * Click on “Register New Application” and provide your application name, description and a call-back URL. This step registers your application with WorkSmart * Click on your newly created application and you should be able to see you applications client credentials (Client ID and Secret Key) ### **Your WorkSmart Web API end point** Your endpoint URL is based on your portal, so please make sure you are using correct endpoint to access WorkSmart Web API for you portal. Please use the URL mentioned on your portal Web API Settings page. Below image shows where you can find your Endpoint URL : # Oauth 2.0 Authorization Before you access any data stored WorkSmart via Web API, you must first request an `Access Token`. No data is accessible via the Web API without sending a valid `Access Token`. You can obtain `Access Token` using two ways : * Using Authorization Code (Auth Code Flow) – recommended * Using Client Credentials # Authorisation Code Flow Authorisation Code Flow is a two step process : 1. Get authorisation code by making a GET request as below to the authorize URL - once the request is successful, you will receive an Authorizarion Code to your callback URL 2. Exchange Authorisation Code obtained in above step for an Access token using [Token (Auth Code Flow)](/web-api/untitled/token-auth-code-flow) {% hint style="info" %} Authorises API request using Oauth 2.0 Authorization Code Flow {% endhint %} URL : `/api/v1/oauth2/authorize`\ Method : `GET` ### Parameters *`client_id`* (**required**)\ Your application client id *`response_type`* (**required**)\ Use the value as “code” *`state`* (**required**)\ Any random string to prevent from CSRF *`redirect_uri`* (optional)\ Endpoint to handle authorisation response ### Sample Request `curl https://my.worksmart.app/api/v1/oauth2/authorize?client_id=ibl90vqe9ll5198ss53v1b1knpk4fhacv4y7uzpa.worksmart.net&response_type=code&state=aozcah` # Token (Auth Code Flow) ### Request Access Token Using Authorization Code Flow: URL : `/api/v1/oauth2/token`\ Method : `POST` ### Parameters *`client_id`* (**required**)\ Your application client id *`client_secret`* (**required**)\ Your application client secret *`grant_type`* (**required**)\ Use the value as “`authorization_code`“ *`code`* (**required**)\ Authorisation code received in authorise response ### Sample Request `curl -X POST -d "client_id=ibl90vqe9ll5198ss53v1b1knpk4fhacv4y7uzpa.worksmart.net&client_secret= avfyflz1ygyaxrmx95nf&grant_type=authorization_code&code=m98z8wr6mxvmtr9sf3kl" https:://my.worksmart.app/api/v1/oauth2/token` ### Sample Response ``` { "access_token": "abcdefghijklmnopqrstuvwxyz123456789", "expires_in": 3600, "token_type": "Bearer", "scope": null, "refresh_token": "123456789abcdefghijklmnopqrstuvwxyz" } ``` # Token (Client Credentials) ### Request Access Token Using client credentials: URL : `/api/v1/oauth2/token`\ Method : `POST` ### Parameters *`client_id`* (**required**)\ Your application client id *`client_secret`* (**required**)\ Your application client secret *`grant_type`* (**required**)\ Use the value as “`client_credentials`“ ### Sample Request `curl -u {client_id}:{client_secret} https://my.worksmart.app/api/v1/oauth2/token -d 'grant_type=client_credentials'` ### Sample Response ``` { "access_token": "abcdefghijklmnopqrstuvwxyz123456789", "expires_in": 3600, "token_type": "Bearer", "scope": null } ``` # Records # Create Record **Create record in an application:** URL : `/api/v1/app/{app_id}/record/`\ Method : `POST` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id App for where the record is present *API request must send all required parameters for creating a record as POST request body.* If your app has “Draft” mode enabled, to save your record into “Draft” state, you can pass a parameter “draft” with a value of “1” as part of your POST request body. By default, record will always be saved in “Published” state. To change a record from “Draft” state to “Published” state, you must send an UPDATE record API request with the “draft” parameter value as 0. ### Sample Request `curl -H "Authorization: Bearer {access_token}" -X POST https://my.worksmart.app/api/v1/app/1234/record/ -d 'f1=New Record Data'` ### Sample Response ``` { "f1":"New Record Data" } ``` # Read Record **Read record for an application using record id:** URL : `/api/v1/app/{app_id}/record/{record_id}`\ Method : `GET` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id App for where the record is present *`record_id`* **(required, path parameter)**\ ID of the record you want to fetch ### Sample Request `curl -H "Authorization: Bearer {access_token}" https://my.worksmart.app/api/v1/app/1234/record/1` ### Sample Response ``` { "data":{ "f1":"Test Record" }, "metadata":[ { "app_id":"1234", "field_id":"f1", "field_name":"Test Field", "field_description":"", "type":"0", "type_name":"Text Field", "position":"3", "required":"1" } ] } ``` # Update Record **Updates a record for application using record id:** URL : `/api/v1/app/{app_id}/record/{record_id}`\ Method : `PUT` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id App for where the record is present *`record_id`* **(required, path parameter)**\ ID of the record you want to fetch ### Sample Request `curl -H "Authorization: Bearer {access_token}" -X PUT https://my.worksmart.app/api/v1/app/1234/record/134 -d 'f1=New Updated Data'`
# Delete Record **Archives a record from the application and moves it to trash.** {% hint style="info" %} This call will move the record to trash, so you won’t loose your data permanently. {% endhint %} URL : `/api/v1/app/{app_id}/record/{record_id}`\ Method : `DELETE` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id App for where the record is present *`record_id`* **(required, path parameter)**\ ID of the record you want to fetch ### Sample Request `curl -H "Authorization: Bearer {access_token}" -X DELETE https://my.worksmart.app/api/v1/app/1234/record/241` ### Sample Response ``` { "deleted":{ "id":"241", "deleted":"1" } } ``` # Read Records By View **Get all records by a specific view:** URL : `/api/v1/app/{app_id}/view/{view_id}`\ Method : `GET` Parameters: *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, header parameter)**\ Application Id *`view_id`* **(required, header parameter)**\ View Id\
### Filter Parameters (Optional) : **Method – `GET` – for filtering data** *`filter_columns`*\ Column Ids. To filter data for multiple columns, use “|” as separator e.g. *`filter_columns=2|3|4`* *`filter_values`*\ Values that needs to be matched. To filter data using multiple values, use “|” as separator e.g. *`filter_columns=2|2|4`*and *`filter_values=Column2Text1|Column2Text2|Column4`* *`filter_apps`*\ App Ids for the columns (only applicable for columns from Lookup App). To filter data using multiple apps, use “|” as separator *`filter_operators`*\ Operators to use for filtering data. To use multiple operators, use “|” as separator e.g. *`filter_operators=0|0|1`*. **Operator codes are as below:** *`0`* : contains *`1`* : does not contain *`2`* : equals *`3`* : does not equal *`4`* : empty *`5`* : not empty *`6`* : less than *`7`* : less than or equal to *`8`* : greater than *`9`* : greater than or equal to ### Sample Request `curl -H "Authorization: Bearer {access_token}" https://my.worksmart.app/api/v1/app/124/view/456` ### Sample Response ``` { "data":[ { "a30":"DEMO00000" }, { "a30":"DEMO00002" } ], "metadata":[ { "view_id":"456", "field_id_in_data":"a30", "field_name":"Title", "field_description":"", "app_id":"124", "id":"1", "type_name":"Auto Number" } ] } ``` # Add Comment **Add comment to a record** {% hint style="warning" %} Comment plugin must be install/enabled for the application {% endhint %} URL : `/api/v1/app/{app_id}/record/{record_id}/comment`\ Method : `POST` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id of the record *`record_id`* **(required, path parameter)**\ Record Id where the comment needs to be added *`comment`* **(required, body parameter)**\ Comment text to be added to the record ### Sample Request `curl -H "Authorization: Bearer {access_token}" -X POST https://my.worksmart.app/api/v1/app/1234/record/134/comment -d 'comment=New comment'` # Add Attachment **Add attachment (file) to a record** URL : `/api/v1/app/{app_id}/record/{record_id}/attachment`\ Method : `POST` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id of the record *`record_id`* **(required, path parameter)**\ Record Id where the file needs to be attached *`attachment_file`* **(required, form parameter)**\ File which needs to be attached to the record ### Sample Request # Download Attachment **Download attachment (file) of a record.** {% hint style="warning" %} Currently only downloads the first attachment of the record {% endhint %} URL : `/api/v1/app/{app_id}/record/{record_id}/attachment`\ Method : `GET` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id of the record *`record_id`* **(required, path parameter)**\ Record Id where the file needs to be attached ### Sample Request `curl -H "Authorization: Bearer {access_token}" https://my.worksmart.app/api/v1/app/124/record/1/attachment` # List Sites **Get information about all sites** URL : `/api/v1/site`\ Method : `GET` ### Parameters: *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* ### Sample Request `curl -H "Authorization: Bearer {access_token}" https://my.worksmart.app/api/v1/site` ### Sample Response ``` [ { "id":"1", "name":"Finance", "manager":"Jack Broad", "apps":[ { "app_id":"1224", "name":"Application 1" }, { "app_id":"2345", "name":"Application 2" } ] }, { "id":"2", "name":"Project Management", "manager":"John Gill", "apps":[ { "app_id":"3453", "name":"Application 3" }, { "app_id":"413", "name":"Application 4" } ] } ] ``` # Columns This section explains how to pass values for different fields when adding or updating a record using API. {% hint style="warning" %} NOTE : Only columns which are currently supported by API for add or edit record are listed below. If you do not find any column that means it not available for use in API. {% endhint %} **TEXT**: Any string **MULTILINE** : Any valid HTML **EMAIL:** A valid email address **PHONE/FAX NO.** : Any alphanumeric string **URL** : A valid URL **NUMBER** : Any valid number including floating point numbers. **CURRENCY** : Any valid number including decimals but without any currency symbol. Currency symbol defined at the column settings will be used. **DATE**: 1. DATE ONLY: Date string in the format “DD-MM-YYYY” e.g. 20-03-2026 2. DATE & TIME : Date string in the format “DD-MM-YYYY hh:mm” e.g. “20-03-2030 13:25” where hh is a two digit 24 hour time and mm is a two digit minute. **The time must be in a UTC time zone.** **DURATION**: hh:mm format duration where hh is a two digit 24 hour time and mm is a two digit minute **CHOICE**: The id of the choice value **USER**: A comma-separated list of valid email addresses # List of Columns **Create record in an application:** URL : `/api/v1/app/{app_id}/columns`\ Method : `GET` ### Parameters *`access_token`* **(required, header parameter)**\ Send this as header – e.g.*“Authorization: Bearer access\_token”* *`app_id`* **(required, path parameter)**\ Application Id App for where the record is present This API call will return a list of all columns of an app with all it's metadata. ### Sample Request `curl -H "Authorization: Bearer {access_token}" -X GET https://my.worksmart.app/api/v1/app/1234/columns` ### Sample Response ``` [ { "app_id": "40", "field_id": "72", "field_id_in_data": "f72", "field_name": "Store", "field_description": "", "type": "16", "type_name": "LookUp", "position": "1", "unique_value": "0" }, { "app_id": "40", "field_id": "74", "field_id_in_data": "f74", "field_name": "Title", "field_description": "", "type": "2", "type_name": "Choice", "position": "2", "unique_value": "0", "default_value": "", "choice_type": "0", "choice_types": { "1": "single_select_radio_button", "0": "single_select_dropdown", "2": "multi_select_checkbox" }, "display_format": "0", "display_formats": { "2": "Cards", "0": "One Per Line", "1": "Next to each other", "3": "Slider", "4": "Star Rating" }, "choices": [ { "id": "805", "name": "Mr", "color": "#FFE599", "order": "1" }, { "id": "806", "name": "Mrs", "color": "#427e53", "order": "2" }, { "id": "807", "name": "Miss", "color": "#3c68bb", "order": "3" }, { "id": "808", "name": "Ms", "color": "#c73f37", "order": "4" } ] }, { "app_id": "40", "field_id": "37", "field_id_in_data": "f37", "field_name": "Employee Name", "field_description": "", "type": "0", "type_name": "Text Field", "position": "4", "unique_value": "0" } ] ``` # Webhook Webhooks allows your to get informed about the events that has happened in your portal i.e. when a record is created or updated, etc. You can utilise the webhook events to trigger an action on your system or any third app. {% content-ref url="/pages/hwe4i6WGYSngcyzQbU02" %} [Configure a Webhook](/webhook/configure-a-webhook) {% endcontent-ref %} # Configure a Webhook To setup a webhook for your app, Navigate to "App Settings" --> "Advanced Settings" --> "Webhook Settings" ![](/files/hKKt9fkoYP5E53LuQo7L) Click "New Webhook" to configure a new webhook and enter the following details: * Payload URL - the url where webhook payload will be sent * Events - Select the events that you want to listen to * Secret Key (Optional) - if provided, the webhook payload will be signed using the secret key, so you can verify the webhook payload on your end to confirm that the webhook was actually triggered from your WorkDigital. * Active - whether the webhook is active or inactive ![](/files/vfhLSZ1rjo67He6uNnzl) Click "Apply" and your Webhook is now configured. ![](/files/Ls0DZsONznSufpFVrT6b)