API access
The Yandex Forms API is available to Yandex Forms for Business users. For more information, see 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 Getting access to the API via OAuth 2.0.
-
IAM token. Can only be used in Yandex Cloud organizations. For more information, see Access the API with an IAM token.
You can't use a Yandex Cloud service account for authorization in the Yandex Forms API. Send requests only from a user account.
In requests, specify these headers:
-
Host: api.forms.yandex.net -
Authorization: OAuth <OAuth_token>: If OAuth 2.0 is used.Authorization: Bearer <IAM_token>— when using an IAM token.For example:
Authorization: Bearer t1.ab123cd45*****************.
You don't need to transmit the organization ID in the request: Forms automatically detects the organization based on the form code and verifies that the user making the request is a member of that organization.
Getting access to the API via OAuth 2.0
To access Yandex Forms API, you need to obtain an OAuth token. This token grants the same permissions that the user account has in Yandex Forms. For example, if the user doesn't have permissions to receive form answers, the user can't make API requests to retrieve them with this token.
Use the obtained token in the Authorization header when making requests to Yandex Forms API.
For information about basic OAuth concepts and the Yandex implementation of the protocol, see the OAuth for Yandex ID documentation.
Setting up token issuance for users
Suppose you want to integrate your app or system with Yandex Forms. For example, you may need the system to retrieve form answers via the API on behalf of your organization's users. In this case, each user must be issued a token to access Yandex Forms API.
To set up token issuance for users:
-
Follow the link https://oauth.yandex.ru/client/new/ or register your app in the OAuth service. For instructions, see the Register your app section in Yandex ID Help.
Note: The link specified in Yandex ID Help is https://oauth.yandex.ru/client/new/id/.
To set up integration with Yandex Forms, create an app at https://oauth.yandex.ru/client/new/. -
Under Data access, add permissions for working with the Yandex Forms API. To select a permission, start typing its name in the Access name field:
-
Editing form settings (forms:write): Allow all data operations, such as creating, deleting, and editing.
-
Viewing form settings (forms:read): Allow read-only data access.
-
-
Select and configure a method for obtaining an OAuth token. See the Get an OAuth token section in Yandex ID Help.
Get an OAuth token
If you need access to the Yandex Forms API for testing, debugging, or automation purposes, obtain a debug OAuth token:
-
Follow this link: https://oauth.yandex.ru/client/new/.
-
Under Platforms, select Web services.
-
Hover over the Redirect URI field and click Enter URL for debugging in the tooltip. This will set the field value to
https://oauth.yandex.ru/verification_code. -
Under Permissions, add the Editing form settings (forms:write) and Viewing form settings (forms:read) permissions.
-
To get a debug token:
-
In your Yandex OAuth account, select the previously created application and copy its ID from the ClientID field.
-
Next, generate a link to request a token:
https://oauth.yandex.ru/authorize?response_type=token&client_id=<application_ID>- Follow the link and copy the OAuth token. For more information, see Yandex ID Help.
-
To check if you have access to the API, send any request. If no access permission is granted, you will get a response with the 401 Unauthorized code.
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 ABC-def12GH_******'
curl -X GET "https://api.forms.yandex.net/v1/users/me/" ^
-H "Authorization: OAuth ABC-def12GH_******"
Access the API with an IAM token
If you're 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 needs this token to authorize with the Yandex Forms API and access resources. Read more about this authentication method in the documentation of the identification and access control service.
The IAM token is valid for no more than 12 hours and is limited by the cookie lifetime for the federation. When the token expires, the 401 Unauthorized error is returned.