Developers

Ovoform API Documentation

The Ovoform API lets applications authenticate users with OAuth 2.0 and read or manage their forms, responses, and webhooks. It powers Ovoform’s official integrations — including Zapier — and follows standard REST conventions with JSON request and response bodies.

Base URL: https://api.ovoform.com · All endpoints are versioned under /api/v1.

Authentication

Ovoform is an OAuth 2.0 provider. Integrations use the Authorization Code grant to obtain an access token on behalf of a user, then send it as a Bearer token on every API request. Refresh tokens are supported for long-lived access.

OAuth client credentials (client ID and secret) are provisioned by Ovoform. For the official Zapier integration these are managed inside Zapier; to register a new OAuth client for another integration, contact support.

OAuth endpoints

Method	Endpoint	Description
GET	/api/v1/oauth/authorize	Start the Authorization Code flow. Query: client_id, redirect_uri, response_type=code, scope, state.
POST	/api/v1/oauth/token	Exchange an authorization code for tokens (grant_type=authorization_code), or refresh them (grant_type=refresh_token). Client credentials may be sent in the body or via HTTP Basic auth.
GET	/api/v1/oauth/userinfo	Return the authenticated user’s profile for a valid access token. Requires a Bearer token.
POST	/api/v1/oauth/revoke	Revoke an access or refresh token (RFC 7009).

Scopes

Scope	Grants
profile	Basic profile information (name, avatar).
email	The user’s email address.
forms:read	Read forms and their questions.
forms:write	Create and modify forms.
responses:read	Read form responses.
webhooks:write	Create and remove response webhooks (REST Hooks).

Exchanging a code for tokens

curl -X POST https://api.ovoform.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<authorization_code>",
    "redirect_uri": "<your_redirect_uri>",
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>"
  }'

Example response (field values are illustrative):

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile email forms:read forms:write responses:read webhooks:write"
}

To refresh, POST to the same token endpoint with grant_type=refresh_token and your refresh_token.

Making requests

Send the access token in the Authorization header on every API call:

curl https://api.ovoform.com/api/v1/zapier-v2/forms \
  -H "Authorization: Bearer <access_token>"

Forms, responses & webhooks

These endpoints back Ovoform’s integration triggers, actions, and searches. All require a valid Bearer access token. A workspaceId may be supplied explicitly; if omitted, the user’s first workspace is used.

Data & triggers

Method	Endpoint	Description
GET	/api/v1/zapier-v2/workspaces	List the workspaces the authenticated user can access.
GET	/api/v1/zapier-v2/forms	List forms in a workspace. Query: workspaceId (optional — defaults to the user’s first workspace).
GET	/api/v1/zapier-v2/forms/{id}/questions	List a form’s questions (used for dynamic field dropdowns).
GET	/api/v1/zapier-v2/sample	Return recent responses (newest-first) for polling-based "New Response" triggers. Query: formId, workspaceId.
POST	/api/v1/zapier-v2/subscribe	Subscribe a REST Hook to receive new responses. Body: targetUrl (HTTPS), formId, workspaceId.
DELETE	/api/v1/zapier-v2/unsubscribe/{id}	Remove a previously subscribed REST Hook.

Actions & searches

Method	Endpoint	Description
POST	/api/v1/zapier-v2/forms	Create a new (empty) form. Body: title, workspaceId.
POST	/api/v1/zapier-v2/forms/{id}/duplicate	Duplicate an existing form. Body: workspaceId.
PUT	/api/v1/zapier-v2/forms/{id}/questions/{questionId}/options	Update a choice question’s options. Body: options, workspaceId.
GET	/api/v1/zapier-v2/forms/{id}/responses	Look up responses for a form (search). Query: search, workspaceId.

Webhooks (REST Hooks)

For real-time triggers, subscribe an HTTPS callback URL with POST /api/v1/zapier-v2/subscribe. Ovoform delivers a JSON payload to that URL whenever a new response is submitted to the chosen form, and stops delivering once you call the matching unsubscribe endpoint. Callback URLs must use HTTPS.

Rate limiting & errors

API requests are rate-limited per token (standard endpoints allow roughly 300 requests per minute; authentication endpoints are stricter). Exceeding a limit returns 429 Too Many Requests.

Errors return a JSON body with an error code and HTTP status:

{
  "error": "invalid_token",
  "error_description": "Token is invalid or expired",
  "statusCode": 401
}

Support

Questions, OAuth client requests, or integration help? Contact Ovoform support.