Teleform Docs

Appearance

API Documentation ​

Backend of Teleform is written in Go and uses Gin as a web framework. It provides a simple JSON REST API for frontend application.

Autorization ​

To authorize, just pass signed init data in X-Init-Data HTTP header:

http
X-Init-Data: query_id=AAHdF6IQAAAAAN0XohDhrOrc&...
X-Init-Data: query_id=AAHdF6IQAAAAAN0XohDhrOrc&...

If you set environment variable SKIP_INIT_DATA_VALIDATION to true, backend will trust this data without checking signature.

Methods ​

GET /api/getForm

Get form by ID.

Example Request ​

http
GET /api/getForm?form_id=123e4567-e89b-12d3-a456-426614174000
GET /api/getForm?form_id=123e4567-e89b-12d3-a456-426614174000

Example Response ​

json
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    
    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",
    
    "author": 63121552,
    
    "responses": 100,
    
    "questions": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174001",
            "type": "regular_input",
            "mandatory": true,
            "content": {
                "text": "What is your name?",
                "placeholder": "John Doe"
            }
        },
        {
            "id": "123e4567-e89b-12d3-a456-426614174002",
            "type": "T-Shirt Size",
            "content": {
                "text": "What is your T-Shirt size?",
                "multichoice": true,
                "options": [
                    "S",
                    "M",
                    "L",
                    "XL"
                ]
            }
        }
    ] 
}
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    
    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",
    
    "author": 63121552,
    
    "responses": 100,
    
    "questions": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174001",
            "type": "regular_input",
            "mandatory": true,
            "content": {
                "text": "What is your name?",
                "placeholder": "John Doe"
            }
        },
        {
            "id": "123e4567-e89b-12d3-a456-426614174002",
            "type": "T-Shirt Size",
            "content": {
                "text": "What is your T-Shirt size?",
                "multichoice": true,
                "options": [
                    "S",
                    "M",
                    "L",
                    "XL"
                ]
            }
        }
    ] 
}
GET /api/getMyForms

Get all forms created by the current user.

Example Request ​

http
GET /api/getMyForms
GET /api/getMyForms

Example Response ​

json
[
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        
        "emoji": "📝",
        "title": "My Form",
        "created_at": "2023-10-08T18:55:24.096845335Z",
        
        "author": 63121552,
        "responses": 100,
        
        "questions": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174001",
                "type": "regular_input",
                "mandatory": true,
                "content": {
                    "text": "What is your name?",
                    "placeholder": "John Doe"
                }
            },
            {
                "id": "123e4567-e89b-12d3-a456-426614174002",
                "type": "T-Shirt Size",
                "content": {
                    "text": "What is your T-Shirt size?",
                    "multichoice": true,
                    "options": [
                        "S",
                        "M",
                        "L",
                        "XL"
                    ]
                }
            }
        ] 
    }
]
[
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        
        "emoji": "📝",
        "title": "My Form",
        "created_at": "2023-10-08T18:55:24.096845335Z",
        
        "author": 63121552,
        "responses": 100,
        
        "questions": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174001",
                "type": "regular_input",
                "mandatory": true,
                "content": {
                    "text": "What is your name?",
                    "placeholder": "John Doe"
                }
            },
            {
                "id": "123e4567-e89b-12d3-a456-426614174002",
                "type": "T-Shirt Size",
                "content": {
                    "text": "What is your T-Shirt size?",
                    "multichoice": true,
                    "options": [
                        "S",
                        "M",
                        "L",
                        "XL"
                    ]
                }
            }
        ] 
    }
]
POST /api/createForm

Create new form.

Example Request ​

http
POST /api/createForm

{
   "title": "My Form",
}
POST /api/createForm

{
   "title": "My Form",
}

Example Response ​

json
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    
    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",
    
    "author": 63121552,
    
    "questions": [] 
}
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    
    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",
    
    "author": 63121552,
    
    "questions": [] 
}
POST /api/editForm

Edit your form.

Example Request ​

http
POST /api/editForm

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    
    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",
    
    "questions": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174001",
            "type": "regular_input",
            "mandatory": true,
            "content": {
                "text": "What is your name?",
                "placeholder": "John Doe"
            }
        }
    ] 
}
POST /api/editForm

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    
    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",
    
    "questions": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174001",
            "type": "regular_input",
            "mandatory": true,
            "content": {
                "text": "What is your name?",
                "placeholder": "John Doe"
            }
        }
    ] 
}

Example Response ​

json
{
    "id": "123e4567-e89b-12d3-a456-426614174000",

    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",

    "author": 63121552,

    "questions": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174001",
            "type": "regular_input",
            "mandatory": true,
            "content": {
                "text": "What is your name?",
                "placeholder": "John Doe"
            }
        }
    ]
}
{
    "id": "123e4567-e89b-12d3-a456-426614174000",

    "emoji": "📝",
    "title": "My Form",
    "created_at": "2023-10-08T18:55:24.096845335Z",

    "author": 63121552,

    "questions": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174001",
            "type": "regular_input",
            "mandatory": true,
            "content": {
                "text": "What is your name?",
                "placeholder": "John Doe"
            }
        }
    ]
}
POST /api/respondToForm

Create new form.

Example Request ​

http
POST /api/respondToForm

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
    
    "answers": [
        {
            "question_id": "123e4567-e89b-12d3-a456-426614174001",
            "content": ["John Doe"]
        },
        {
            "question_id": "123e4567-e89b-12d3-a456-426614174002",
            "content": ["S", "XL"]
        }
    ] 
}
POST /api/respondToForm

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
    
    "answers": [
        {
            "question_id": "123e4567-e89b-12d3-a456-426614174001",
            "content": ["John Doe"]
        },
        {
            "question_id": "123e4567-e89b-12d3-a456-426614174002",
            "content": ["S", "XL"]
        }
    ] 
}

Example Response ​

json
{
    "status": "OK"
}
{
    "status": "OK"
}
POST /api/deleteForm

Delete your form.

Example Request ​

http
POST /api/deleteForm

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
}
POST /api/deleteForm

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
}

Example Response ​

json
{
    "status": "ok"
}
{
    "status": "ok"
}
POST /api/getFormResponses

Get responses to your form.

Example Request ​

http
POST /api/getFormResponses

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
}
POST /api/getFormResponses

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
}

Example Response ​

json
{
    "responses": [
        {
            "form_id": "123e4567-e89b-12d3-a456-426614174000",

            "user_id": 63121552,

            "answers": [
                {
                    "id": "123e4567-e89b-12d3-a456-426614174001",
                    "content": ["John Doe"]
                },
                {
                    "id": "123e4567-e89b-12d3-a456-426614174002",
                    "content": ["S", "XL"]
                }
            ]
        }
    ],

    "users": {
        "63121552": {
            "name": "John Doe",
            "avatar": "https://example.com/avatar.png"
        }
    }
}
{
    "responses": [
        {
            "form_id": "123e4567-e89b-12d3-a456-426614174000",

            "user_id": 63121552,

            "answers": [
                {
                    "id": "123e4567-e89b-12d3-a456-426614174001",
                    "content": ["John Doe"]
                },
                {
                    "id": "123e4567-e89b-12d3-a456-426614174002",
                    "content": ["S", "XL"]
                }
            ]
        }
    ],

    "users": {
        "63121552": {
            "name": "John Doe",
            "avatar": "https://example.com/avatar.png"
        }
    }
}
POST /api/exportFormResponses

Delete your form.

Example Request ​

http
POST /api/exportFormResponses

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
    "format": "csv"
}
POST /api/exportFormResponses

{
    "form_id": "123e4567-e89b-12d3-a456-426614174000",
    "format": "csv"
}

Example Response ​

json
{
    "status": "ok"
}
{
    "status": "ok"
}

After that, bot will send you a file with responses in the specified format.