Accessing the Yandex Forms API

API requests are made on behalf of a user. To perform actions through the API, the user on whose behalf the request is made must have the appropriate permissions in Forms. For example, if the user does not have permission to retrieve form responses, the corresponding API requests will be unavailable.

The Yandex Forms API is available to Yandex Forms for Business users. For more information, see About Yandex Forms for Business.

To access the Yandex Forms API, you can use one of these authorization methods:

• OAuth 2.0 protocol — can be used in both Yandex 360 for Business and Yandex Cloud Organization organizations. For more information, see Accessing the API via OAuth 2.0.

• IAM token — can only be used in Yandex Cloud organizations. For more information, see Accessing the API with an IAM token.

Headers

In requests, specify these headers:

• Host: api.forms.yandex.net

• Authorization header:

  • Authorization: OAuth <OAuth-token> — when using the OAuth 2.0 protocol.

  • Authorization: Bearer <IAM-token> — when using an IAM token.

• Organization ID:

  • X-Org-Id — for a Yandex 360 for Business organization.
  • X-Cloud-Org-Id — for a Yandex Cloud Organization organization.

  To find your organization ID, open the Administration → Organizations page in Yandex Tracker and copy the value from the ID field.

Example:

Host: api.forms.yandex.net
Authorization: OAuth y0__xAbc*********
X-Org-Id: 1234******

Accessing the API via OAuth 2.0

To get a token:

1. Click the link https://oauth.yandex.com.

2. On the Your apps page, click Create.

3. In the window that opens, select For API access or debugging and click Go to creation.

4. Enter the app name and your contact email.

5. Add permissions for accessing user data. To select a permission, start typing its name in the Permission name field:

   • Изменение настроек форм (forms:write) — all operations with data: creation, deletion, and editing.
   • Просмотр настроек форм (forms:read) — reading only.

6. Click Create app.

7. In your Yandex OAuth account, select the previously created application and copy its ID from the ClientID field.

8. Generate a link to request a token:

   https://oauth.yandex.com/authorize?response_type=token&client_id=<application_ID>
   

9. Log in to the account you will use to work with the API, then follow the generated link.

   A sequence of characters will appear on the page — this is your OAuth token. Copy and save it.

See how to set up your app in Yandex ID Help:

• How to create an OAuth app for accessing the API.
• How to obtain a token.

To check if you have access to the API, send any request. If access has not been granted, the request will return a response with code 401 Unauthorized.

For example, to retrieve information about the current user with curl:

curl -X GET 'https://api.forms.yandex.net/v1/users/me/' \
     -H 'Authorization: OAuth y0__xAbc******' \
     -H 'X-Org-Id: 1234******'

curl -X GET "https://api.forms.yandex.net/v1/users/me/" ^
     -H "Authorization: OAuth y0__xAbc******" ^
     -H "X-Org-Id: 1234******"

Accessing the API with an IAM token

If you are using Forms as part of a Yandex Cloud organization, you can authorize with the API using an IAM token.

An IAM token is a unique sequence of characters issued to a user after authentication. The user uses this token to authorize with the Yandex Forms API and perform operations on resources. For more information about this authentication method, see the documentation of the identity and access management service.

• How to get an IAM token for a Yandex account

• How to get an IAM token for a federated account