Skip to main content
POST
/
v1
/
requests
Create a Request
curl --request POST \
  --url https://api.siit.io/v1/requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title_markdown": "<string>",
  "requested_by": "<string>",
  "title": "<string>",
  "description": "<string>",
  "description_markdown": "<string>",
  "author": "<string>",
  "slack_direct_link": "<string>",
  "tags": [
    "<string>"
  ],
  "associated_apps": [
    "<string>"
  ],
  "associated_equipments": [
    "<string>"
  ],
  "target": "<string>",
  "assignee_admin": "<string>",
  "assignee_inbox": "<string>",
  "custom_form_inputs": [
    {
      "label": "<string>",
      "value": "<string>"
    }
  ]
}
'
{
  "result": {
    "uid": "<string>",
    "admin_permalink_url": "<string>",
    "archived_at": "2023-11-07T05:31:56Z",
    "assignee_admin": "<string>",
    "assignee_admin_uid": "<string>",
    "assignee_inbox": "<string>",
    "assignee_inbox_uid": "<string>",
    "associated_apps": [
      "<string>"
    ],
    "associated_equipments": [
      "<string>"
    ],
    "approvals": [
      "<string>"
    ],
    "attachments": [
      {
        "filename": "<string>",
        "url": "<string>"
      }
    ],
    "author": "<string>",
    "author_uid": "<string>",
    "completed_at": "2023-11-07T05:31:56Z",
    "completed_by": "<string>",
    "completed_by_uid": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "custom_form_inputs": [
      {
        "label": "<string>",
        "value": "<string>"
      }
    ],
    "description": "<string>",
    "description_markdown": "<string>",
    "follower_uids": [
      "<string>"
    ],
    "followers": [
      "<string>"
    ],
    "friendly_id": "<string>",
    "requested_by": "<string>",
    "requested_by_uid": "<string>",
    "slack_channel_id": "<string>",
    "slack_direct_link": "<string>",
    "slack_thread_ts": "<string>",
    "slack_ts": "<string>",
    "sla_data": {
      "first_replied_at": "2023-11-07T05:31:56Z",
      "first_completed_at": "2023-11-07T05:31:56Z",
      "paused_at": "2023-11-07T05:31:56Z",
      "first_reply_due_at": "2023-11-07T05:31:56Z",
      "first_completion_due_at": "2023-11-07T05:31:56Z"
    },
    "status": "open",
    "tag_uids": [
      "<string>"
    ],
    "tags": [
      "<string>"
    ],
    "target": "<string>",
    "target_uid": "<string>",
    "title": "<string>",
    "title_markdown": "<string>",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

​
Introduction

Please note that: the author_uid should be the same as requested_by_uid OR reference a User with an admin role

​
Custom forms

When submitting custom_form_inputs[], you can use arbitrary forms and native forms You can actually send a mix of Arbitrary and Native forms as long as the native form are valid. An example payload would be: 
// POST https://api.siit.io/v1/requests
{
  "title": "Request from API with forms",
  "submitted_from": "employee_portal",
  "author": "U1",
  "requested_by": "U1",
  "target_uid": "wa_xxxxx",
  "custom_form_inputs": [
    { "label": "An arbitrary field", "value": "With its arbitrary value"},
    { "uid": "custom_input_longprefix", "value": "string or uid or array or number depending on the configuration" }
  ]
}
NB: we currently don’t allow uploading custom form files at the moment via the public API.

​
Arbitrary forms

You can submit arbitrary values by sending custom_form_inputs[] items with the format 
{ "label": "string", "value": "string" }
This is a good way to store extra information, but cannot be picked by workflows.

​
Native forms

Native custom forms are always scoped by Service object. If you submit at least one native form, then the whole custom form validation logic will run (e.g if you have a field that is required and missing on the payload, it will fail the creation of the request). So the flow to use them is to:
  1. retrieve the custom forms from the target you’re planning on submitting GET https://api.siit.io/v1/services/wa_xxxx endpoint (custom_form_input_configuration[])
  2. add the custom_form_inputs[] to your request creation payload
{ "uid": "custom_input_yyyy", "value": "item | items[]" }
Where item should be an array if the custom form input is multiple. If you have workflows configured targeting those fields, they will properly run at the request creation except in the case of a batch import.

​
Usage

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
title_markdown
string
required

The title as markdown. Takes precedence over title when both are provided.

​
submitted_from
enum<string>
required
Available options:
employee_portal,
slack,
mail,
ms_teams
​
requested_by
string
required

can be different from the author UID (e.g Admin submitting on behalf)

​
title
string
deprecated

please use "title_markdown" instead

​
description
string
deprecated

please use "description_markdown" instead

​
description_markdown
string

The description as markdown. Takes precedence over description when both are provided.

​
author
string

must be equal to requester UID or reference an admin user. Defaults to the token owner when omitted.

​
slack_direct_link
string

can be provided along submitted_from=slack to link directly to a specific message. Note that if bot has a specific public request configuration for the channel then the request mode will be "public".

​
status
enum<string>
Available options:
open,
in_progress,
waiting,
resolved,
archived
​
priority
enum<string>
Available options:
low,
medium,
high,
urgent
​
tags
string[]
​
associated_apps
string[]
​
associated_equipments
string[]
​
target
string
​
assignee_admin
string
​
assignee_inbox
string
​
custom_form_inputs
(Arbitrary input (by label) · object | Native input (by uid) · object)[]

An optional array containing data attached to the request. Each item must include either "uid" (native input) or "label" (arbitrary input), plus "value".

A custom form input item for request creation. Either "label" (arbitrary input) or "uid" (native input from service configuration) must be provided.

Response

Request created

​
result
object