API Reference

Introduction

This API enables you to manage basic aspects when you use Arengu. It offers endpoints to submit the form, execute a flow, get submission details, and more.

Endpoits are grouped in two main groups:

Public endpoints: they do not require any kind of authentication mechanism since they are public.
Private endpoints: they require a valid and active session to be invoked.

Authentication

Currently we only support consuming our private endpoits with JSON Web Token (JWT) through Authorization header using Bearer schema. If it is not set or it is expired, server will reject the operation returning an error.

Authorization: Bearer

Base URL

All URLs referenced in this documentation have the following base URL:

https://api.arengu.com

Public endpoints

Submit a form

Submits the specified form triggering linked flows.

If the specified form has a linked flow and the flow execution is not successful, the operation will be aborted and the server will return an error message defined by the user.

Any other unexpected error caused by the flow will abort the operation and return a generic error message. For security reasons, error details are only available in your flow debugger.

Operation example

> POST /forms/:formId/submissions/
> Content-Type: application/json
{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@arengu.com",
  "password": "foobar"
}

< HTTP/1.1 200 OK
< Content-Type: application/json
{
  "effect": {
    "type": "THANK_YOU",
    "submissionId": "160754815022185406",
    "message": "You have successfully signed up!"
  }
}

Execute a flow

Executes the specified flow.

> POST /flows/:flowId/executions/
> Content-Type: application/json
{
  "email": "jane.doe@arengu.com"
}

< HTTP/1.1 202 Accepted
< Content-Type: application/json

Operation example

Private endpoints

Retrieve submissions

Retrieves the latest received submissions sorted by descending date.

Operation example

> POST /private/submissions/search/
> Content-Type: application/json
{
  "formId": "120672204813308",
  "pagination": {
    "size": 10,
    "page": 1
  }
}

< HTTP/1.1 200 OK
< Content-Type: application/json
{
  "items": [
    {
      "id": "160735365151089561",
      "traceId": "6e34573f41160e0a86bf75a6a5b85d52",
      "formId": "120672204813308",
      "workspaceId": "12905879685",
      "stepId": "step_DyOe",
      "formData": {
        "email": {
          "type": "EMAIL",
          "value": "jane.doe@arengu.com"
        }
      },
      "createdAt": "2020-12-07T15:07:31.510Z",
      "updatedAt": "2020-12-07T15:07:31.510Z",
      "deletedAt": null
    }
  ],
  "pagination": {
    "hasBefore": false,
    "hasNext": false
  }
}

View submission details

View details of the specified submission.

Operation example

> GET /private/submissions/:submissionId
> Content-Type: application/json

< HTTP/1.1 200 OK
< Content-Type: application/json
{
  "id": "160735365151089561",
  "formId": "120672204813308",
  "workspaceId": "12905879685",
  "stepId": "step_DyOe",
  "status": null,
  "comment": null,
  "metaData": {
    "ip": "80.10.200.42",
    "view": {
      "screen": {
        "width": 1280,
        "height": 800
      },
      "window": {
        "width": 1280,
        "height": 609
      }
    },
    "navigator": {
      "language": "en",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_0_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.198 Safari/537.36"
    },
    "navigation": {
      "referer": "https://www.arengu.com/",
      "location": {
        "hash": "",
        "host": "www.arengu.com",
        "href": "https://www.arengu.com/use-cases/passwordless-forms",
        "port": "",
        "search": "",
        "hostname": "www.arengu.com",
        "pathname": "/use-cases/passwordless-forms",
        "protocol": "https:",
        "searchParams": {}
      },
      "analytics": {
        "ga": {}
      }
    }
  },
  "formData": {
    "email": {
      "type": "EMAIL",
      "value": "jane.doe@arengu.com"
    }
  },
  "createdAt": "2020-12-07T15:07:31.510Z",
  "updatedAt": "2020-12-07T15:07:31.510Z"
}

Retrieve executions

Retrieves the latest executed flows sorted by descending date.

Operation example

> POST /private/executions/search/
> Content-Type: application/json
{
  "flowId": "1363496765875105",
  "pagination": {
    "size": 10,
    "page": 1
  }
}

< HTTP/1.1 200 OK
< Content-Type: application/json
{
  "items": [
    {
      "id": "160754813510864333",
      "traceId": "19f994f8a8d9721663620a7bc79c8750",
      "flowId": "1363496765875105",
      "flowName": "My awesome flow",
      "workspaceId": "12905879685",
      "status": "COMPLETED",
      "createdAt": "2020-12-09T21:08:55.108Z",
      "startedAt": "2020-12-09T21:08:55.123Z",
      "updatedAt": "2020-12-09T21:08:55.147Z",
      "endedAt": null,
      "deletedAt": null
    }
  ],
  "pagination": {
    "hasBefore": false,
    "hasNext": false
  }
}

View execution details

View details of the specified flow execution.

Operation example

> GET /private/executions/:executionId?debug=true
> Content-Type: application/json

< HTTP/1.1 200 OK
< Content-Type: application/json
{
  "id": "160754813510864333",
  "traceId": "19f994f8a8d9721663620a7bc79c8750",
  "flowName": "My awesome flow",
  "status": "COMPLETED",
  "createdAt": "2020-12-09T21:08:55.108Z",
  "startedAt": "2020-12-09T21:08:55.123Z",
  "updatedAt": "2020-12-09T21:08:55.147Z",
  "endedAt": null,
  "deletedAt": null,
  "debug": {
    "input": {
      "body": {
        "email": "jane.doe@arengu.com"
      }
    },
    "output": {
      "type": "JUMP_TO_STEP",
      "params": {
        "stepId": "step_Mclp",
        "type": "JUMP_TO_STEP"
      },
      "cookies": [],
      "data": {},
      "state": {}
    },
    "error": null,
    "tracing": [
      {
        "id": "verifyEmail",
        "alias": null,
        "type": "EMAIL",
        "action": "VERIFY_EMAIL",
        "input": {
          "email": "jame.doe@arengu.com",
          "rules": {
            "requireMXRecord": true,
            "blockFreeEmails": true,
            "blockDisposableEmails": false,
            "blockAliases": false,
            "whitelist": [],
            "blacklist": []
          }
        },
        "output": {
          "headers": {},
          "status": 200,
          "body": {
            "valid": true,
            "cause": null
          },
          "success": true
        },
        "error": null
      }
    ],
    "state": {}
  }
}



Table of contents

API Reference guides & tutorials

Discover our step-by-step guides and tutorials to learn using Arengu with API Reference.

No items found.