---
# System prepended metadata

title: Request to a DocQ instance

---

# Request to a DocQ instance

Every request will be made to `https://{client}.docq.app/api/`, with the authorization token in the header `x-access-token`.

You can create DocQ access tokens using the UI, go to `https://{client}.docq.app/#/plugins/main` and under "DocQ Integration tokens", click on "`+ Add token`" button. After that, the token can be used on the `x-access-token` header of every request.

---

## Create workflow

`POST /api/workflow/create`

Payload:

```json
{
  "id": null,
  "name": "Workflow name",
  "version": "ifttt",
  "is_user_default": false,
  "allow_email_copy": false,
  "document_template_id": null,
  "content_access_id": 1,
  "send_to_ftp": false,
  "ftp_account_id": null,
  "keywords": null,
  "metadata": [],
  "steps": [
    {
      "order": 1,
      "type": "start",
      "name": "Start step",
      "actions": [
        {
          "type": "default",
          "name": "Default action",
          "approve_to": 3,
          "notes": ""
        }
      ],
      "notifications_in": [],
      "notifications_out": [],
      "position": { "x": 0, "y": 0 }
    },
    {
      "order": 2,
      "type": "end",
      "name": "End step",
      "notifications_in": [],
      "notifications_out": [],
      "position": { "x": 0, "y": 0 }
    },
    {
      "order": 3,
      "type": "notification",
      "name": "Notify external user",
      "actions": [
        {
          "type": "default",
          "name": "Default action",
          "approve_to": 2,
          "notes": ""
        }
      ],
      "destinations": [
        {
          "destinations": [
            {
              "type": "external",
              "name": "External User",
              "email": "external@email",
              "use_metadata_fields": false
            }
          ],
          "type": "individual"
        }
      ],
      "message_type": "rtf",
      "email_subject": "This is the subject of the email",
      "message_body": "Here goes the body of the email, it supports <b>html tags</b> and template variables: {{user_name}}",
      "email_attach_document": false,
      "notifications_in": [],
      "notifications_out": [],
      "position": { "x": 0, "y": 0 }
    }
  ]
}
```

The response will have:

```json
[
  {
    "allow_email_copy": false,
    "content_access_id": 1,
    "document_template_id": null,
    "ftp_account_id": null,
    "id": 13,
    "is_user_default": false,
    "keywords": null,
    "metadata": [],
    "name": "Workflow name",
    "send_to_ftp": false,
    "steps": [...], // `steps` will be the same as the payload above
    "version": "ifttt"
  }
]
```

The important field here is the `id`, this will be used to identify this workflow.

A workflow always has a `start` and `end` step, the example above shows a simple workflow to notify an external user.

Each step has a list of actions, an action will decide which step the document will go after an approval (or rejection) based of a condition. All the steps (with the exception of the final, `"type": "end"`) must have at least the default route with an `approve_to` going to the next step. All the steps must be reached from the starting step, and all the steps must reach the end step.

```json
{
  "actions": [
    {
      "type": "condition",
      "name": "Condition 1",
      "approve_to": 4,
      "notes": "",
      "condition": "equal",
      "metadata": "Quantity",
      "value": "5"
    },
    {
      "approve_to": 2,
      "name": "Default action",
      "notes": "",
      "type": "default"
    }
  ]
}
```

In this part taken from the workflow we can see beyond the default case, a condition where if the document template variable named `Quantity` has a value equals to `5`, then the step will not follow the normal route, instead it will go to the step order 4.

---


## Create template

`POST /api/documenttemplate`

Payload:

```json
{
  "name": "Template name",
  "workflow_id": 13,
  "content_access_id": 1,
  "filename": "Doc_A.pdf",
  "filetype": "pdf",
  "fields": [],
  "file": "{Base64 encoded PDF}"
}
```

The response will have:

```json
[
  {
    "content_access_id": 1,
    "fields": [],
    "file": "",
    "filename": "Doc_A.pdf",
    "filetype": "pdf",
    "forms": {},
    "id": 137,
    "name": "Template name",
    "signature_template": false,
    "sr_module": null,
    "workflow_id": 13,
    "workflow_sr": false,
    "workflow_steps": null
  }
]
```

The important field here is the `id`, this will be used to identify which document template should be edited on the SmartOnboard project (TO BE DEFINED, could be changed for security reasons).


### Template fields

Example of the `fields` array:

```json
[
  {
    "id": "age",
    "type": "number",
    "label": "Age",
    "required": false,
    "max": 100,
    "min": 1,
    "positions": [
      { "page": 0, "scale": 1, "x": 83.162, "y": 44.214 }
    ],
    "uuid": "8de77a41-883b-4ff8-9d74-fdf3100b2f0b"
  },
  {
    "id": "firstName",
    "type": "text",
    "label": "First Name",
    "required": false,
    "positions": [
      { "page": 0, "scale": 1, "x": 14.793, "y": 44.269 }
    ],
    "uuid": "0d6a4850-9158-45f2-9371-0f83b19a2e85"
  },
  {
    "id": "lastName",
    "type": "text",
    "label": "Last Name",
    "required": false,
    "positions": [
      { "page": 0, "scale": 1, "x": 30.95, "y": 44.277 }
    ],
    "uuid": "3eba795f-3ea5-42a0-8424-5246c39c8b8d"
  },
  {
    "id": "dateOfBirth",
    "type": "date",
    "label": "Date Of Birth",
    "required": false,
    "positions": [
      { "page": 0, "scale": 1, "x": 56.28, "y": 44.226 }
    ],
    "uuid": "85def1fe-95a3-4080-99c7-02376fe9d410"
  },
  {
    "id": "gender",
    "type": "dropdown",
    "label": " Gender",
    "required": false,
    "options": [
      { "label": "Male", "value": "M" },
      { "label": "Female", "value": "F" }
    ],
    "positions": [
      { "page": 0, "scale": 1, "x": 70.748, "y": 49.262 }
    ],
    "uuid": "2a39fbc2-b86f-4c83-ae05-335aab5afd57"
  },
  {
    "id": "email",
    "type": "email",
    "label": "Email address",
    "required": false,
    "confirm_email": true,
    "positions": [
      { "page": 0, "scale": 1, "x": 67.605, "y": 58.404 }
    ],
    "uuid": "7760bf66-f77f-4173-a55f-48cc43ebf520"
  },
  {
    "id": "checkbox",
    "type": "checkbox",
    "label": "Checkbox",
    "required": false,
    "max": 2,
    "positions": [
      { "page": 0, "scale": 1, "value": "CB#1", "x": 92.82, "y": 85.494 },
      { "page": 0, "scale": 1, "value": "CB#2", "x": 92.979, "y": 88.197 },
      { "page": 0, "scale": 1, "value": "CB#3", "x": 92.819, "y": 91.025 },
      { "page": 0, "scale": 1, "value": "CB#4", "x": 92.819, "y": 93.606 }
    ],
    "uuid": "4e6be71a-0a4d-4764-a6e6-8bb8a851ff5d"
  },
  {
    "id": "textareaTest",
    "type": "textarea",
    "label": "Textarea Test",
    "hint": "test hint",
    "required": false,
    "max": 200,
    "min": 5,
    "positions": [
      { "page": 0, "scale": 1, "x": 17.647, "y": 53.759 }
    ],
    "uuid": "2a606229-90d8-42cc-aecc-ac6f9dbe623f"
  },
  {
    "id": "booleanField",
    "type": "boolean",
    "label": "Yes/No",
    "required": false,
    "positions": [
      { "page": 0, "scale": 1, "x": 6.26, "y": 60.58 }
    ],
    "uuid": "35bee974-aab1-49a4-bccd-2be77a3928ec"
  }
]
```

---

### Create form link

Form link allow candidates to access the form created on DocQ, without having to create an account.

`POST /api/documenttemplate/formToken`

Payload:

```json
{
  "active": true,
  "allow_preview": false,
  "name": "Form link 1",
  "expire": null,
  "document_template_id": 137,
  "sr_module": {
    "request_emailrefid": false
  },
  "preload_last_data": "block"
}
```

(`document_template_id` is the `id` from the request above)

This will return:

```json
{
  "tokens": [
    {
      "active": true,
      "allow_preview": false,
      "created": "2021-05-14T13:35:48.538Z",
      "document_template_id": 137,
      "expire": null,
      "id": 100,
      "name": "Form link 1",
      "preload_last_data": "block",
      "sr_module": {
        "request_emailrefid": false
      },
      "token": "eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  ]
}
```

The field `token` is the string that goes in the URL for the cadidate to access the web form:

URL Example:

```
https://forms.docq.app/?domain={client}.docq.app&form=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
```
