Pular para o conteúdo principal

Client API

Overview​

The Client API is designed for creating and updating documents in Skills Workflow. It’s not intended for bulk data extraction or reporting—use our Data API for that.

Purpose​

The Client API is intended for interacting with and managing documents and entities within Skills Workflow. It allows for the creation, update, and manipulation of items within your workflow but is not suited for large-scale data extraction.

Use Cases​

Integrate Skills Workflow into tools such as:

  • Project management systems: Asana, Trello, Monday, ZiFlow
  • Collaboration platforms: AirTable, Notion
  • Business systems: ERP systems, attendance tracking, and other external document workflows

Key Limitations​

  • Not for data extraction: Don’t rely on this API to pull large datasets; use the Data API for that purpose.
  • 30-second execution cap: Long-running calls will be terminated. For optimal performance, use filters or pagination (e.g., skip/take) on listing endpoints.
  • Rate limits may apply: High-frequency requests should be managed to avoid throttling.
  • Limited data interactions: This API focuses on document creation and updating, not extensive data querying or analysis.

Getting Started​

Authentication​

Before calling any endpoint, you must obtain the following credentials from our Support team:

  • App Key (X-AppId)
  • App Secret (X-AppSecret)
  • Tenant ID (X-AppTenant)

These are provided by the support team upon request.

Include them in each request via HTTP headers:

X-AppTenant:  <X-AppTenant>
X-AppId:      <X-AppId>
X-AppSecret:  <X-AppSecret>
X-AppUser:    <UserId>     # Optional, if user-scoped filtering is required
Content-Type: application/json

Environments​

The API is available in four environments, depending on your subscription plan:

  • Development
  • Test
  • UAT
  • Production

Each environment has its own base URL:

{{ApiUrl}}/api/v3/analytics

Postman Collection​

To facilitate testing of the available queries, we provide a Postman collection file with all endpoints configured. You can download it from the link below:

Download Postman Collection - Client API

After downloading, make sure to configure the variables {{ApiUrl}}, {{TenantId}}, {{AppId}}, {{AppSecret}}, and {{UserId}} according to the credentials you have been given.

Rate Limits​

  • 30-second cap on every call—avoid timeouts by filtering or paging large result sets.
  • Listing endpoints support two query parameters:
    • skip (int): number of records to skip
    • take (int): maximum number of records to return

Endpoints​

Swagger

Examples​

Creating a Document​

The /api/posts endpoint is the main way client integrations create documents in Skills Workflow. A single call can:

  • Create a new document (when Actions.Document is supplied)
  • Add a comment to a document's feed
  • Run a workflow stage transition on a document
  • Attach an initial Document Brief
nota

DocumentId does not select an existing document to update when Actions.Document is present — see the Payload Reference below for how document creation and comment/transition-only calls differ.

Request​

POST https://apiv2-{{Tenant}}.skillsworkflow.com/api/posts

Include the standard authentication headers and set Content-Type: application/json.

Payload Reference​

These fields make up the common request envelope, regardless of which document type is being created:

FieldTypeDescription
DocumentIdguidID of the document the post/comment/transition applies to. When Actions.Document is included, a new document of that type is always created and this field is ignored for that purpose — it can simply be omitted, as in the examples below. To add a comment or run a transition on an existing document without creating one, omit Actions.Document and set this to that document's ID instead.
DocumentTypeNamestringThe document type being created or updated — see Supported Document Types below.
TextstringComment added to the document's feed.
Actions.TransitionobjectOptional. Runs a workflow stage transition on the document as part of the same call.
Actions.Transition.StatusIdguidID of the workflow status/stage the document is in.
Actions.Transition.TransitionIdguidID of the workflow transition to execute.
Actions.DocumentobjectOptional. Present only when creating a new document (or, for Deliverable, updating one — see below).
Actions.Document.DocumentTypestringSame value as DocumentTypeName.
Actions.Document.DocumentActionTypestringRequired whenever Actions.Document is present. Use "Post" to create a document. Deliverable is the only type that also supports "Put", to update an existing Deliverable instead of creating one (using a JobPutModel object in place of Job — not covered in detail here).
Actions.Document.<nested property>objectThe document's own fields. The property name and shape depend on the document type — see Supported Document Types and the tabs below.
Actions.Document.<nested property>.DocumentBriefobjectOptional, only for document types that support it (see below). Creates an initial Brief linked to the document — see Document Brief below.
nota

Unlike the other fields above, DocumentBrief is nested inside the type-specific object (e.g. Actions.Document.Project.DocumentBrief), not as a sibling of it.

Supported Document Types​

DocumentType valueNested property under Actions.DocumentSupports DocumentBrief?
ProjectProjectYes
DeliverableJob (create) / JobPutModel (update)Yes, create only
ContractContractYes
EstimateEstimateYes
ExpenseExpenseYes
ExpenseItemExpenseItemYes
RateCardRateCardNo
PriceTablePriceTableNo
RequestRequestYes
TenderTenderNo
nota

Deliverable is the only type where the nested property name doesn't match DocumentType — it's Job, not Deliverable.

Examples by Document Type​

Each tab below shows a minimal creation payload and the fields table for that document type. Fields lists are not exhaustive — see Swagger for the full schema of each type. Text and Actions.Transition (shown in the Project tab) can be combined with any document type the same way.

The example below creates a new Project document, adds a comment to its feed, and runs a workflow transition on it in the same call.

{
    "DocumentTypeName": "Project",
    "Text": "Comment to be added initially to the newly created project's feed.",
    "Actions": {
        "Transition": {
            "StatusId": "e8e4651f-f6e2-4053-918b-1fb25ac7b6f6",
            "TransitionId": "2a0f65ab-408c-4696-8454-757a444dea9e"
        },
        "Document": {
            "DocumentType": "Project",
            "DocumentActionType": "Post",
            "Project": {
                "ClassificationId": "7d16465d-b535-44f1-822a-3ab449dab77b",
                "ClientId": "94177d4d-670b-47b9-a3ff-f05bb4deaf6e",
                "ContractId": "eee0c262-abbe-4ccf-9e44-a126402586bc",
                "CurrencyId": "12bb8ac2-1729-4be3-a587-0705c4888211",
                "BeginDateUtc": "2024-05-31T23:22:07.3520703Z",
                "EndDateUtc": "2024-12-01T00:22:07.3520703Z",
                "Investment": 0.0,
                "IsDraft": true,
                "ProductId": "8f77ad60-228d-4d07-a3f5-ff5ee2e64d8e",
                "ProjectNatureId": "c3d4e5f6-a7b8-49c0-8d1e-2f3a4b5c6d7e",
                "ProjectOwnerId": "d4e5f6a7-b8c9-4ad0-9e1f-3a4b5c6d7e8f",
                "AllowsTimesheet": true,
                "IsDeliverable": true,
                "DocumentBrief": {
                    "DocumentTypeName": "Project",
                    "Text": ""
                }
            }
        }
    }
}

Fields under Actions.Document.Project:

FieldTypeDescription
ClassificationIdguidProject classification.
ClientIdguidClient the project belongs to.
ContractIdguidAssociated contract.
CurrencyIdguidCurrency used for the project's financials.
BeginDateUtcdatetimeProject start date (UTC).
EndDateUtcdatetimeProject end date (UTC).
InvestmentnumberPlanned investment amount.
IsDraftbooleanWhether the project is created as a draft.
ProductIdguidAssociated product.
ProjectNatureIdguidProject nature/category. Use the empty GUID if not applicable.
ProjectOwnerIdguidProject owner (user). Use the empty GUID if not set.
AllowsTimesheetbooleanWhether timesheets can be logged against the project.
IsDeliverablebooleanWhether the project itself acts as a deliverable.
nota

CompanyId, ProjectManagerId, BusinessObjectTypeId, and IsActivated are deliberately left out here — they have no effect when creating a Project (they only apply when updating one through the client update endpoints). There's also no ProjectType field: the server always derives it from whether ContractId is set, so any submitted value would be discarded.

Document Brief​

Where supported (see the Supported Document Types table above), DocumentBrief is nested inside the type-specific object and has the same shape for every type:

FieldTypeDescription
DocumentTypeNamestringDocument type the brief belongs to — same value as the outer DocumentTypeName.
TextstringContent of the brief.

Response​

201 Created — the created Post (feed entry), not the document itself. Its DocumentId field holds the ID of the newly created document.

tip

Most Id fields across the tabs above reference records that already exist in your tenant (clients, companies, products, etc.). The Data Extraction queries under docs/api/data-extraction are available to look up the correct GUID for each of these before building a payload — don't hardcode IDs from another tenant or environment.

Testing with Postman​

The same requests can be sent from the Postman collection:

FieldValue
MethodPOST
URLhttps://apiv2-{{Tenant}}.skillsworkflow.com/api/posts
Bodyraw / JSON — paste any of the payloads above