Upsert form submission

curl --request POST \
  --url https://app.azalt.co/api/v1/form-submissions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "year": 123,
  "values": [
    {
      "periodUnit": 123,
      "elementId": "<string>",
      "elementKey": "<string>",
      "elementMetadataKey": "<string>",
      "elementMetadataValue": "<string>",
      "value": "<unknown>",
      "selectedUnitId": "<string>",
      "timestamp": "<string>"
    }
  ],
  "formId": "<string>",
  "formMetadataKey": "<string>",
  "formMetadataValue": "<string>",
  "siteId": "<string>",
  "siteMetadataKey": "<string>",
  "siteMetadataValue": "<string>"
}
'

import requests

url = "https://app.azalt.co/api/v1/form-submissions"

payload = {
    "year": 123,
    "values": [
        {
            "periodUnit": 123,
            "elementId": "<string>",
            "elementKey": "<string>",
            "elementMetadataKey": "<string>",
            "elementMetadataValue": "<string>",
            "value": "<unknown>",
            "selectedUnitId": "<string>",
            "timestamp": "<string>"
        }
    ],
    "formId": "<string>",
    "formMetadataKey": "<string>",
    "formMetadataValue": "<string>",
    "siteId": "<string>",
    "siteMetadataKey": "<string>",
    "siteMetadataValue": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    year: 123,
    values: [
      {
        periodUnit: 123,
        elementId: '<string>',
        elementKey: '<string>',
        elementMetadataKey: '<string>',
        elementMetadataValue: '<string>',
        value: '<unknown>',
        selectedUnitId: '<string>',
        timestamp: '<string>'
      }
    ],
    formId: '<string>',
    formMetadataKey: '<string>',
    formMetadataValue: '<string>',
    siteId: '<string>',
    siteMetadataKey: '<string>',
    siteMetadataValue: '<string>'
  })
};

fetch('https://app.azalt.co/api/v1/form-submissions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.azalt.co/api/v1/form-submissions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'year' => 123,
    'values' => [
        [
                'periodUnit' => 123,
                'elementId' => '<string>',
                'elementKey' => '<string>',
                'elementMetadataKey' => '<string>',
                'elementMetadataValue' => '<string>',
                'value' => '<unknown>',
                'selectedUnitId' => '<string>',
                'timestamp' => '<string>'
        ]
    ],
    'formId' => '<string>',
    'formMetadataKey' => '<string>',
    'formMetadataValue' => '<string>',
    'siteId' => '<string>',
    'siteMetadataKey' => '<string>',
    'siteMetadataValue' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.azalt.co/api/v1/form-submissions"

	payload := strings.NewReader("{\n  \"year\": 123,\n  \"values\": [\n    {\n      \"periodUnit\": 123,\n      \"elementId\": \"<string>\",\n      \"elementKey\": \"<string>\",\n      \"elementMetadataKey\": \"<string>\",\n      \"elementMetadataValue\": \"<string>\",\n      \"value\": \"<unknown>\",\n      \"selectedUnitId\": \"<string>\",\n      \"timestamp\": \"<string>\"\n    }\n  ],\n  \"formId\": \"<string>\",\n  \"formMetadataKey\": \"<string>\",\n  \"formMetadataValue\": \"<string>\",\n  \"siteId\": \"<string>\",\n  \"siteMetadataKey\": \"<string>\",\n  \"siteMetadataValue\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.azalt.co/api/v1/form-submissions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"year\": 123,\n  \"values\": [\n    {\n      \"periodUnit\": 123,\n      \"elementId\": \"<string>\",\n      \"elementKey\": \"<string>\",\n      \"elementMetadataKey\": \"<string>\",\n      \"elementMetadataValue\": \"<string>\",\n      \"value\": \"<unknown>\",\n      \"selectedUnitId\": \"<string>\",\n      \"timestamp\": \"<string>\"\n    }\n  ],\n  \"formId\": \"<string>\",\n  \"formMetadataKey\": \"<string>\",\n  \"formMetadataValue\": \"<string>\",\n  \"siteId\": \"<string>\",\n  \"siteMetadataKey\": \"<string>\",\n  \"siteMetadataValue\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.azalt.co/api/v1/form-submissions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"year\": 123,\n  \"values\": [\n    {\n      \"periodUnit\": 123,\n      \"elementId\": \"<string>\",\n      \"elementKey\": \"<string>\",\n      \"elementMetadataKey\": \"<string>\",\n      \"elementMetadataValue\": \"<string>\",\n      \"value\": \"<unknown>\",\n      \"selectedUnitId\": \"<string>\",\n      \"timestamp\": \"<string>\"\n    }\n  ],\n  \"formId\": \"<string>\",\n  \"formMetadataKey\": \"<string>\",\n  \"formMetadataValue\": \"<string>\",\n  \"siteId\": \"<string>\",\n  \"siteMetadataKey\": \"<string>\",\n  \"siteMetadataValue\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "formSiteId": "<string>",
  "userId": "<string>",
  "organizationId": "<string>",
  "values": [
    {
      "formElementSubmissionId": "<string>",
      "elementId": "<string>",
      "periodUnit": 123,
      "status": "COMPLETED",
      "value": "<unknown>",
      "originalValue": null,
      "selectedUnitId": "<string>",
      "userId": "<string>",
      "userName": "<string>",
      "userEmail": "<string>",
      "userImage": "<string>",
      "recordedAt": "<string>"
    }
  ],
  "deletedAt": "<string>"
}

{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}

{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}

{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

FormSubmission

Upsert form submission

Create or update a form submission. You have flexible options for identifying forms, sites, and form elements:

Form Identification (choose one):

formId: Direct form ID (e.g., “form-abc123”)
formMetadataKey + formMetadataValue: Lookup by metadata (e.g., “erpFormId” = “form123”)

Site Identification (choose one):

siteId: Direct site ID (e.g., “site-xyz789”)
siteMetadataKey + siteMetadataValue: Lookup by metadata (e.g., “erpSiteId” = “123”)

Form Element Identification (choose one per element):

elementId: Direct element ID (e.g., “formel-def456”)
elementKey: Element key within the form (e.g., “energy_consumption”)
elementMetadataKey + elementMetadataValue: Lookup by metadata (e.g., “extId” = “ext01”)

TIMESTAMP elements:

Provide values[].timestamp (ISO 8601). The server requires it for TIMESTAMP elements, derives periodUnit from the UTC month, and validates that the timestamp year matches the submission year.
Upsert semantics: entries are de-duplicated by (formSubmissionId, formElementId, recordedAt). Sending the same timestamp updates the existing entry; otherwise, a new entry is inserted.
To delete a TIMESTAMP entry, send value: null with the same timestamp.

Example request (TIMESTAMP):

{
  "formId": "form-123",
  "siteId": "site-1",
  "year": 2024,
  "values": [
    { "elementId": "el-ts", "value": 42, "timestamp": "2024-03-15T10:30:00Z", "periodUnit": 3 }
  ]
}

Example response (trimmed):

{
  "id": "fs-1",
  "formSiteId": "fs-site-1",
  "values": [
    { "elementId": "el-ts", "periodUnit": 3, "value": 42, "recordedAt": "2024-03-15T10:30:00.000Z" }
  ]
}

This flexibility allows integration with external systems using their own IDs via metadata, while also supporting direct internal ID references.

POST

form-submissions

Upsert form submission

curl --request POST \
  --url https://app.azalt.co/api/v1/form-submissions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "year": 123,
  "values": [
    {
      "periodUnit": 123,
      "elementId": "<string>",
      "elementKey": "<string>",
      "elementMetadataKey": "<string>",
      "elementMetadataValue": "<string>",
      "value": "<unknown>",
      "selectedUnitId": "<string>",
      "timestamp": "<string>"
    }
  ],
  "formId": "<string>",
  "formMetadataKey": "<string>",
  "formMetadataValue": "<string>",
  "siteId": "<string>",
  "siteMetadataKey": "<string>",
  "siteMetadataValue": "<string>"
}
'

import requests

url = "https://app.azalt.co/api/v1/form-submissions"

payload = {
    "year": 123,
    "values": [
        {
            "periodUnit": 123,
            "elementId": "<string>",
            "elementKey": "<string>",
            "elementMetadataKey": "<string>",
            "elementMetadataValue": "<string>",
            "value": "<unknown>",
            "selectedUnitId": "<string>",
            "timestamp": "<string>"
        }
    ],
    "formId": "<string>",
    "formMetadataKey": "<string>",
    "formMetadataValue": "<string>",
    "siteId": "<string>",
    "siteMetadataKey": "<string>",
    "siteMetadataValue": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    year: 123,
    values: [
      {
        periodUnit: 123,
        elementId: '<string>',
        elementKey: '<string>',
        elementMetadataKey: '<string>',
        elementMetadataValue: '<string>',
        value: '<unknown>',
        selectedUnitId: '<string>',
        timestamp: '<string>'
      }
    ],
    formId: '<string>',
    formMetadataKey: '<string>',
    formMetadataValue: '<string>',
    siteId: '<string>',
    siteMetadataKey: '<string>',
    siteMetadataValue: '<string>'
  })
};

fetch('https://app.azalt.co/api/v1/form-submissions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.azalt.co/api/v1/form-submissions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'year' => 123,
    'values' => [
        [
                'periodUnit' => 123,
                'elementId' => '<string>',
                'elementKey' => '<string>',
                'elementMetadataKey' => '<string>',
                'elementMetadataValue' => '<string>',
                'value' => '<unknown>',
                'selectedUnitId' => '<string>',
                'timestamp' => '<string>'
        ]
    ],
    'formId' => '<string>',
    'formMetadataKey' => '<string>',
    'formMetadataValue' => '<string>',
    'siteId' => '<string>',
    'siteMetadataKey' => '<string>',
    'siteMetadataValue' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.azalt.co/api/v1/form-submissions"

	payload := strings.NewReader("{\n  \"year\": 123,\n  \"values\": [\n    {\n      \"periodUnit\": 123,\n      \"elementId\": \"<string>\",\n      \"elementKey\": \"<string>\",\n      \"elementMetadataKey\": \"<string>\",\n      \"elementMetadataValue\": \"<string>\",\n      \"value\": \"<unknown>\",\n      \"selectedUnitId\": \"<string>\",\n      \"timestamp\": \"<string>\"\n    }\n  ],\n  \"formId\": \"<string>\",\n  \"formMetadataKey\": \"<string>\",\n  \"formMetadataValue\": \"<string>\",\n  \"siteId\": \"<string>\",\n  \"siteMetadataKey\": \"<string>\",\n  \"siteMetadataValue\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.azalt.co/api/v1/form-submissions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"year\": 123,\n  \"values\": [\n    {\n      \"periodUnit\": 123,\n      \"elementId\": \"<string>\",\n      \"elementKey\": \"<string>\",\n      \"elementMetadataKey\": \"<string>\",\n      \"elementMetadataValue\": \"<string>\",\n      \"value\": \"<unknown>\",\n      \"selectedUnitId\": \"<string>\",\n      \"timestamp\": \"<string>\"\n    }\n  ],\n  \"formId\": \"<string>\",\n  \"formMetadataKey\": \"<string>\",\n  \"formMetadataValue\": \"<string>\",\n  \"siteId\": \"<string>\",\n  \"siteMetadataKey\": \"<string>\",\n  \"siteMetadataValue\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.azalt.co/api/v1/form-submissions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"year\": 123,\n  \"values\": [\n    {\n      \"periodUnit\": 123,\n      \"elementId\": \"<string>\",\n      \"elementKey\": \"<string>\",\n      \"elementMetadataKey\": \"<string>\",\n      \"elementMetadataValue\": \"<string>\",\n      \"value\": \"<unknown>\",\n      \"selectedUnitId\": \"<string>\",\n      \"timestamp\": \"<string>\"\n    }\n  ],\n  \"formId\": \"<string>\",\n  \"formMetadataKey\": \"<string>\",\n  \"formMetadataValue\": \"<string>\",\n  \"siteId\": \"<string>\",\n  \"siteMetadataKey\": \"<string>\",\n  \"siteMetadataValue\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "formSiteId": "<string>",
  "userId": "<string>",
  "organizationId": "<string>",
  "values": [
    {
      "formElementSubmissionId": "<string>",
      "elementId": "<string>",
      "periodUnit": 123,
      "status": "COMPLETED",
      "value": "<unknown>",
      "originalValue": null,
      "selectedUnitId": "<string>",
      "userId": "<string>",
      "userName": "<string>",
      "userEmail": "<string>",
      "userImage": "<string>",
      "recordedAt": "<string>"
    }
  ],
  "deletedAt": "<string>"
}

{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}

{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}

{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

year

number

required

values

object[]

required

Show child attributes

formId

string

formMetadataKey

string

formMetadataValue

string

siteId

string

siteMetadataKey

string

siteMetadataValue

string

Response

Successful response

string

required

createdAt

string

required

updatedAt

string

required

formSiteId

string

required

userId

string | null

required

organizationId

string | null

required

values

object[]

required

Show child attributes

deletedAt

string | null

required

Activity

ActivityDefinition

ApiKey

Benchmark

Cron Jobs

Dashboard

DatasetItem

Dataset

File

FormElement

FormElementSubmissionActivity

FormElementSubmissionComment

FormElementSubmission

FormSite

FormSubmission

Form

Import

Indicator

Organization

Records

ReminderStatus

Site

Source imports

Target

Unit

User

Widget

Upsert form submission

Authorizations

Body

Response