Workiom API Guide

You will learn how to authenticate, get list meta-data, and get and create records.

Chat icon
Transcript

Authentication


All APIs in Workiom needs an API Key to pass it in the header. You can grab your API Key from Account Settings





Then pass it through the header using the name "X-Api-Key"

Sample:
curl -X GET "https://api.workiom.com/api/services/app/Apps/GetAll" -H "accept: text/plain" -H "X-Api-Key: {Your API Key}"


Get List Meta Data


Most actions you might want to take on a list will probably require getting the list’s meta-data first. The meta-data response will contain a lot of useful information like the list’s fields and views along with their IDs.

GET `/api/services/app/Lists/Get`Content-Type "application/json"Headers`X-Api-Key {Your API Key}`Parametersid: stringexpand: array[string] (any combination of: “Fields”, “Views”, “Filters”)


Response

{ "appId": "string", "fields": [ { "id": 0 "name": "string", "description": "string", "dataType": 0, } ], "id": "string" "name": "string", "description": "string"}


Get List Records


Getting records from a list is simple and flexible. You have to specify a listId to get its records, but you can also specify sorting options, and use maxResultCount and skipCount for pagination, or pass an array of filter objects to have much more granular control over what records you get.

POST `/api/services/app/Data/All`
Content-Type "application/json"
Headers`X-Api-Key  {Your API Key} `

Body


Response

{ "summary": { "additionalProp1": 0, "additionalProp2": 0, "additionalProp3": 0 }, "totalCount": 0, "items": [ {} ]}


Creating Records


Records are simple JSON objects in which each key is a fieldId and each value is that record’s value for the field. Different fields might have different data-types, you can find a field’s id and dataType from the list’s meta-data response.

POST `/api/services/app/Data/Create`Content-Type "application/json"Headers`X-Api-Key {Your API Key} `Parameters`listId: string`Body{ // This is an example of a record /* fieldId: value */ "1186": "2018-11-13T00:00:00.000+00:00", "1251": "[email protected]", "1421": [ { "_id": "r29jrg8hgg48g33nig", "label": "linked record" }, { "_id": "1354535tregrfrwni2", "label": "another linked record" } ], "1425": "Ahmad Lam", "1532": 132, "1563": { "id": "14372839", "label": "static list item" }, "1591": { "id": "28349232", "label": "Khaled Sameeh" }}


Filters


Filters can be used when requesting data. Usually an array of filter objects containing the fieldId to filter on, the filter operator and a filter value. For example, a filter property in a Data/All request might be:

{ "filters": [ { "fieldId": 1425, "operator": 1, "value": "Ahmad Masa" } ]}The filter operators are:Contains = 1,DoesNotContain = 2,Is = 3,IsNot = 4,Greater = 5,GreaterOrEqual = 9,Less = 6,LessOrEqual = 10,Between = 11,IsEmpty = 7,IsNotEmpty = 8,In = 12,NotIn = 13


Sorting


Sorting can be done using a sort string containing the fieldId to sort on and a sorting direction. For example, ascending sort on field 11284 is:

sorting: "11284 ASC"

For descending sort on the same field:

sorting: "11284 DESC"


Data Types


Workiom supports many field data-types, fields with different data-types accept values of different types. A Date field would only accept dates, while a LinkedList field would only accepts an array of objects containing the linked record IDs. Data-types are represented by the following numbers:

Text = 0,Number = 1,DateTime = 2,Boolean = 3,StaticSelect = 4,LinkList = 5,User = 6,Website = 7,Email = 8,File = 9,Rollup = 10,PhoneNumber = 11,Count = 12,Currency = 13,AutoNumber = 14,CheckList = 15


Updating Records


Record updates are almost as simple as record creation. You just have to do

a PUT call instead of POST, and you must provide the record ID in

addition to the list ID. This is a standard PUT request, so the request

body is the whole record, with the changed fields modified.

PUT /api/services/app/Data/Update
Content-Type: "application/json"
Headers`X-Api-Key  {Your API Key} `


Parameters: listId: string, id: string
Body

{ "1186": "2019-11-13T00:00:00.000+00:00", "1251": "[[email protected]](/cdn-cgi/l/email-protection)", "1421": [ { "_id": "r29jrg8hgg48g33nig", "label": "linked record" }, { "_id": "1354535tregrfrwni2", "label": "another linked record" } ], "1425": "Ahmad Lam", "1532": 132, "1563": { "id": "14372839", "label": "static list item" }, "1591": { "id": "28349232", "label": "Khaled Sameeh" } }


Partially Updating Records

If you do not wish to send the whole record with every update, you can use

the /UpdatePartial end point, which allows you to send only the changed

fields, unlike the standard PUT endpoint at /Update.

PUT `/api/services/app/Data/UpdatePartial`Content-Type: "application/json"Headers: `Authorization Bearer [your-access-token`]Parameters: listId: string, id: stringBody{"1186": "2019-11-13T00:00:00.000+00:00","1251": "[[email protected]](/cdn-cgi/l/email-protection)",}



Data Types Payload


Linked List: [ { "_id":string, "label":string } ]
Static List { "id":string, "label":string }
User { "id":int, "username":string }

For any question, please reach us on support@workiom.com.It is meant as a limited general guide that will be improved and expanded with time. For more formal and comprehensive documentation.

Resources:

swagger spec available on: https://api.workiom.com/swagger/.
The API endpoint is available at https://api.workiom.com.

Attach file to record

To attach a file to a record you need to:

  1. Upload the file to the server.
  2. Get the file id and use it in the desired API.
Upload the file
  • Upload the file Using the API /File/Upload
  • When the upload is done, you’ll get a response with the file info.
  • Save this info to use it while creating or updating a record.

API Response:

fileName : "FILE_NAME"

fileToken : "FILE_TOKEN"

fileType : "FILE/MIME_TYPE"

fileUrl : "FILE_URL"

hasThumbnail : true / false

thumbnailUrl : "FILE_THUMBNAIL_URL" // for images files

success : true

targetUrl : null

unAuthorizedRequest : false

Curl exmaple to upload file

PHP Code Beautified
<?php
// Set the URL where you want to upload the file
$uploadUrl = "https://api.workiom.com/File/Upload";

// Set the file name and its path on your local machine
$fileName = "image-file.png";
$filePath = "/path/to/local/image-file.png"; // Replace this with the actual file path

// Create a cURL handle
$curl = curl_init();

// Set the cURL options
curl_setopt($curl, CURLOPT_URL, $uploadUrl);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, [
    'file' => new CURLFile($filePath, mime_content_type($filePath), $fileName)
]);

// Execute the cURL request and get the response
$response = curl_exec($curl);

// Check if there was an error during the cURL request
if (curl_errno($curl)) {
    echo "cURL Error: " . curl_error($curl);
} else {
    // Process the response from the API
    $statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    if ($statusCode === 200) {
        echo "File uploaded successfully!";
        // You can handle the API response here if needed
        // $decodedResponse = json_decode($response, true);
        // ... handle the response data ...
    } else {
        echo "File upload failed. Status code: " . $statusCode;
        // ... handle the error ...
    }
}

// Close the cURL handle
curl_close($curl);
?>
  

Create/Update Record

Using the file info from the previous step we will call the record creation or record update API

Let’s use 12345 as file field id, using the partial update API

/api/services/app/Data/UpdatePartial?listId=LIST_ID&id=RECORD_ID

we should send array of files they should look like this

{

  ‘12345’: [

    {

"AnonymousForm" : false ,

"ContentType" : "FILE/MIME_TYPE" ,

"ExpiryDate" : null ,

"FileName" : "FILE_NAME" ,

"FileUrl" : null ,

"ThumbnailUrl" : null ,

"HasThumbnail" : true/false ,

"IsPermanent" : true ,

"Size" : FILE_SIZE ,

"UserId" : CURRENT_USER_ID ,

"_id" : "FILE_TOKEN"

    }

  ]

}

We can use the same payload for create record API /api/services/app/Data/Create?listId=LIST_ID

Search icon

Looking for something else?

Search by entering some keywords such as; 'email automation', 'linked list'...
Chat icon

Still need help?

If you could not find the answer to your question, please contact the support team using the chat box.