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.
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": {}
}
}