API > How do I launch a process via the API?

This article walks a first-time API use through starting a process, assuming you have a blueprint already.

1. Get your token

In order to perform any action within the Tallyfy API, you must first gain the access token, which you can find out about here.

2. Gather your information

In order to make any call to the API, you must first make sure you have the necessary information.

This includes: 

• The name you are going to give this process
• The ID of the template you are going to use (note that blueprints are called templates in the API).
• Any kick-off field ID's (or prerun fields) and what you want to put in them
• Tags of template you are going to use
• Tasks of template you are going to use

3. Prepare your JSON

   {
   "name": "name of Process",
   "checklist_id": "<Blueprint Id>",
   "summary": "Process summary",
   "owner_id": 0,
   "tasks":  {
       "<Step ID or Step alias>": {
       "position": "<Task position, start from 1>",
       "deadline": "2016-01-01 00:00:00"
       }
    },
    "prerun": [
          {
              "<prerun_id (if textfields)>": "Text Field Value"
          },
          {
              "<prerun_id (if images)>": [
                 {
                     "id": "<Id>",
                     "filename": "Image.png",
                     "version": 1,
                     "url": "tallyfy.com/example-image.png",
                     "uploaded_from": "ko_field",
                     "subject": {
                          "id": "<Subject Id>",
                          "type": "Checklist"
                     }
                 }
              ]
          },
          {
              "<prerun_id (if checklist)>": {
                   "id": 1,
                   "text": "abc.",
                   "value": "null",
                   "selected": true
              }
          },
          {
              "<prerun_id (if dropdown)>": {
                   "id": 1,
                   "text": "abc.",
                   "value": "null"
              }
          },
          {
              "<prerun_id (if radio button)>": "Radio Button Value"
          },
          {
              "<prerun_id (if date)>": "2019-12-12T17:18:55.000Z"
          }
    ],
    "tags":  [
         "<Tag Id>"
    ]
 }

4. Make your call

About the actual call:

Request type: 

POST

URL: 

go.tallyfy.com/api/organizations/{your_org_id}/runs

Headers: 

'Accept: application/json', 'Authorization: Bearer {your_auth_token}'

5. Response - 201

  {
      "data": {
            "id": "<Process id>",
            "checklist_id": "<checklist id>",
            "name": "name of Process",
            "summary": "Process summary",
            "status": "active",
            "progress": {
                   "complete": 1,
                   "total": 4,
                   "percent": 25
             },
             "started_by": 12345,
             "prerun": [
                  {
                      "<prerun_id (if textfields)>": "Text Field Value"
                  },
                  {
                      "<prerun_id (if images)>": [
                         {
                             "id": "<Id>",
                             "filename": "Image.png",
                             "version": 1,
                             "url": "tallyfy.com/example-image.png",
                             "uploaded_from": "ko_field",
                             "subject": {
                                  "id": "<Subject Id>",
                                  "type": "Checklist"
                             }
                         }
                      ]
                  },
                  {
                      "<prerun_id (if checklist)>": {
                           "id": 1,
                           "text": "abc.",
                           "value": "null",
                           "selected": true
                      }
                  },
                  {
                      "<prerun_id (if dropdown)>": {
                           "id": 1,
                           "text": "abc.",
                           "value": "null"
                      }
                  },
                  {
                      "<prerun_id (if radio button)>": "Radio Button Value"
                  },
                  {
                      "<prerun_id (if date)>": "2019-12-12T17:18:55.000Z"
                  }
            ],
            "starred": false,
            "created_at": "YYYY-mm-ddTHH:ii:ssZ",
            "due_date": "YYYY-mm-ddTHH:ii:ssZ",
            "owner_id": 0,
            "started_at": "YYYY-mm-ddTHH:ii:ssZ",
            "last_updated": "YYYY-mm-ddTHH:ii:ssZ",
            "completed_at": "YYYY-mm-ddTHH:ii:ssZ",
            "archived_at": "YYYY-mm-ddTHH:ii:ssZ",
            "due_date_passed": false,
            "collaborators": [
                    12345
            ],
            "due_soon": true,
            "max_task_deadline": "YYYY-mm-ddTHH:ii:ssZ"
            }
 }