Arengu REST API (1.4)

Download OpenAPI specification:Download

Overview

This document contains all the existing web services that we offer to our clients guaranteeing a minimum quality of service and backward compatibility. In case you want to be aware of changes before deployments, send us an email asking us to subscribe you to our changelog and we will notify you of any change that can affect you.

The operations are grouped in two main groups of web services:

  • Public operations: It contains all the available operations that allow people to submit forms or execute flows. They do not require any kind of authentication mechanism since they are public.
  • Private operations: These web services require a valid an active session to be invoked or our server will block the request. It is composed of several operations that allow you to monitor and export processed data.

Authentication

Currently, we only support one authentication mechanism based on JWT. We are already working on API keys to facilitate the integration of external systems with our application while keeping your data safe.

jsonwebtoken

JWT can be generated calling to Create a session operation. Their expiration date is set, by default, to one hour. A valid token is enough to generate a new one calling to Refresh a session operation.

Protected operations requires you to provide the JWT through Authentication header using Bearer schema. If it is not set or it is expired, server will reject the operation returning an error.

Authentication: Bearer <JWT>
Security scheme type: HTTP
HTTP Authorization Scheme bearer

Forms

Create new submissions following the defined structure of the form.

Submit a form

Submits the specified form triggering associated validation flows and events.

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

Any unexpected error caused by validation flow aborts the operation and forces server to return a generic error message. Details of the specific error are not visible to client for security reasons but available in control panel.

path Parameters
formId
required
string
Example: "154832175553844371"

Identifier of the form you want to submit

Request Body schema: application/json
fieldId1
any (SubmissionFieldValue)

Value provided by user.

fieldIdN
any (SubmissionFieldValue)

Value provided by user.

hiddenFieldId1
any (SubmissionFieldValue)

Value provided by user.

hiddenFieldIdN
any (SubmissionFieldValue)

Value provided by user.

Responses

200

Submission persisted successfully.

400

Provided input is not valid

404

Form not found

500

Unexpected error processing the submission

4XX

Validation flow does not accept the request.

post /forms/{formId}/submissions/

Production server

https://api.arengu.com/forms/{formId}/submissions/

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Janet Doe",
  • "email": "janet.doe@example.com",
  • "message": "I want more information",
  • "referer": "user456"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "154893737310954041",
  • "message": "Your message has been processed!",
  • "delay": 1000,
  • "response":
    {
    }
}

Flows

Execute a flow

Executes the specified flow passing the request headers and body as input.

The response and way of execution depends on flow definition:

  • Asynchronous flows are not executed inmediately but queued to be executed later in background. This web service returns a fixed status code and no body.
  • Synchronous flows execute the actions in foreground and do not return a response until it is completed. Both status code and body are calculated based on the business rules of the flow.

In case the execution causes any kind of unexpected error, the web service returns a generic server error. Details of the specific error are not visible to client for security reasons but available in control panel.

path Parameters
flowId
required
string
Example: "154884383973679344"

Identifier of the flow you want to execute

Request Body schema: application/json

Responses

200

Default response for synchronous executions.

202

Flow queued to be executed later.

404

Flow not found

500

Unexpected error executing the flow.

2XX

Custom successful response.

4XX

Custom error response.

post /flows/{flowId}/executions/

Production server

https://api.arengu.com/flows/{flowId}/executions/

Request samples

application/json
Copy
Expand all Collapse all
{
  • "message": "Hello world",
  • "from": "ES",
  • "to": "EN"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": "ERR_ENTITY_NOT_FOUND",
  • "message": "Entity not found",
  • "details":
    {
    }
}

Sessions

Create a temporal session using the credentials provided on registration.

Create a session

Creates a new session associated with the specified user.

Request Body schema: application/json
type
required
string
Default: "credentials"
Value:"credentials"

Specifies the type of credentials you provide.

credentials
required
object

Data that proves you own that account.

Responses

200

Session created successfully

400

Provided input is not valid

401

User not found or wrong password

post /private/sessions/

Production server

https://api.arengu.com/private/sessions/

Request samples

application/json
Copy
Expand all Collapse all
{
  • "type": "credentials",
  • "credentials":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "userId": "154808587686619321",
  • "planId": "FREE2019",
  • "token": "eyJhbGciOiJIUzUxMiIsInR5c",
  • "createdAt": "2019-01-23T12:08:42.951Z",
  • "expiresAt": "2019-01-23T13:08:42.951Z"
}

Refresh a session

Creates a new session if all these conditions are satisfied:

  • Current session is not expired.
  • The related user did not change the password since the session was created.
Authorizations:

Responses

200

Session created successfully

401

Operation requires an active session

403

Current session cannot be refreshed

post /private/sessions/refresh

Production server

https://api.arengu.com/private/sessions/refresh

Response samples

application/json
Copy
Expand all Collapse all
{
  • "userId": "154808587686619321",
  • "planId": "FREE2019",
  • "token": "eyJhbGciOiJIUzUxMiIsInR5c",
  • "createdAt": "2019-01-23T12:08:42.951Z",
  • "expiresAt": "2019-01-23T13:08:42.951Z"
}

Submissions

Process the data received from a published form.

Search submissions

Retrieves the latest received submissions sorted by descending processing date.

Authorizations:
Request Body schema: application/json
formId
required
string

Identifier associated with the form.

filter
object

Excludes non relevant submissions.

pagination
object (PageRequest)

Specifies the page you want to retrieve.

Responses

200

Submissions retrieved successfully

400

Provided input is not valid

401

Operation requires an active session

404

Form not found

post /private/submissions/search

Production server

https://api.arengu.com/private/submissions/search

Request samples

application/json
Copy
Expand all Collapse all
{
  • "formId": "154832175553844371"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "pagination":
    {
    },
  • "items":
    [
    ]
}

Export submissions

Exports all the received submissions sorted by descending processing date.

The Content-Type header depends on the format you specify.

Authorizations:
Request Body schema: application/json
formId
required
string

Identifier associated with the form.

format
string
Default: "JSON"
Enum:"CSV" "JSON"

Format you want to export the data

Responses

200

Submissions exported successfully

400

Provided input is not valid

401

Operation requires an active session

404

Form not found

post /private/submissions/export

Production server

https://api.arengu.com/private/submissions/export

Request samples

application/json
Copy
Expand all Collapse all
{
  • "formId": "154832175553844371",
  • "format": "CSV"
}

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Get a submission

Retrieves the specified submission.

Authorizations:
path Parameters
submissionId
required
string
Example: "154878962885858808"

Identifier of the implicated submission

Responses

200

Submissions retrieved successfully

401

Operation requires an active session

404

Submission not found

get /private/submissions/{submissionId}

Production server

https://api.arengu.com/private/submissions/{submissionId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "154878962885858808",
  • "formId": "154878753193365963",
  • "workspaceId": "4504116097187840",
  • "formData":
    {
    },
  • "metaData":
    {
    },
  • "createdAt": "2019-01-29T19:20:28.858Z"
}

Delete a submission

Deletes the specified submission.

Authorizations:
path Parameters
submissionId
required
string
Example: "154878962885858808"

Identifier of the implicated submission

Responses

200

Submission deleted successfully

401

Operation requires an active session

404

Submission not found

delete /private/submissions/{submissionId}

Production server

https://api.arengu.com/private/submissions/{submissionId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "154878962885858808",
  • "formId": "154878753193365963",
  • "workspaceId": "4504116097187840",
  • "formData":
    {
    },
  • "metaData":
    {
    },
  • "createdAt": "2019-01-29T19:20:28.858Z"
}

Executions

Check all the requests received by existing flows.

Search executions

Retrieves the latest processed requests sorted by descending processing date.

Authorizations:
Request Body schema: application/json
flowId
required
string

Identifier associated with the flow.

filter
object (ExecutionSearchFilter)

Excludes non relevant executions.

pagination
object (PageRequest)

Specifies the page you want to retrieve.

Responses

200

Executions retrieved successfully

400

Provided input is not valid

401

Operation requires an active session

404

Flow not found

post /private/executions/search

Production server

https://api.arengu.com/private/executions/search

Request samples

application/json
Copy
Expand all Collapse all
{
  • "flowId": "154878388287661012"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "pagination":
    {
    },
  • "items":
    [
    ]
}

Get a execution

Retrieves the specified execution.

Authorizations:
path Parameters
executionId
required
string
Example: "154878272714586010"

Identifier of the implicated execution.

query Parameters
debug
boolean
Default: false

If true, debug information is included into the response.

Responses

200

Executions retrieved successfully

401

Operation requires an active session

404

Execution not found

get /private/executions/{executionId}

Production server

https://api.arengu.com/private/executions/{executionId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "154878272714586010",
  • "flowId": "154878267316346394",
  • "flowName": "User onboarding",
  • "workspaceId": "4504116097187840",
  • "status": "COMPLETED",
  • "createdAt": "2019-01-29T17:25:27.145Z",
  • "startedAt": "2019-01-29T17:25:27.126Z",
  • "endedAt": "2019-01-29T17:25:28.302Z",
  • "updatedAt": "2019-01-29T17:25:28.303Z"
}

Delete a execution

Deletes the specified execution.

Authorizations:
path Parameters
executionId
required
string
Example: "154878272714586010"

Identifier of the implicated execution.

Responses

200

Execution deleted successfully

401

Operation requires an active session

404

Execution not found

delete /private/executions/{executionId}

Production server

https://api.arengu.com/private/executions/{executionId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "154878272714586010",
  • "flowId": "154878267316346394",
  • "flowName": "User onboarding",
  • "workspaceId": "4504116097187840",
  • "status": "COMPLETED",
  • "createdAt": "2019-01-29T17:25:27.145Z",
  • "startedAt": "2019-01-29T17:25:27.126Z",
  • "endedAt": "2019-01-29T17:25:28.302Z",
  • "updatedAt": "2019-01-29T17:25:28.303Z"
}