Introduction

Our API allows you to gain access to your workspaces, forms and responses. If you are having problems accessing resources or have anything in mind we should add, let us know via support@deftform.com

Example: Access a workspace

$access_token = 't8ZMQLQiquuyMjHFqfqW0hlEvQsNioCQLLe9npgZ';
 
curl https://deftform.com/api/v1/workspace \
    -H "Authorization: Bearer $access_token" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Rate Limiting

You can make up to 60 requests per minute and 1,440 requests per day per authenticated user. You can check the returned HTTP headers of any API request to see your current per minute rate limit status:

Status: 200 OK
x-ratelimit-limit: 60
x-ratelimit-remaining: 59

If you keep hitting the limit, consider caching the results within your application.

Errors

When we detect an error in your request, we will return a HTTP 4xx response. Most common will be 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden) and 404 (Not Found).

For example, a 403 response will return the following information:

{
  "success": false,
  "message": "You have no access to the requested resource"
}

Please note that the response message might give you further details about what went wrong. A message is only returned for requests that resulted with an error. If you aren't receiving errors, but for example a login page, make sure you've set "Accept: application/json" in your request headers.

Response data

All responses from our API will be formatted as JSON. This is an example payload of the /api/v1/workspace endpoint, which gives you data about a workspace:

{
    "success": true,
    "data": {
        "name": "tinydub Forms",
        "logo": null,
        "logo_backend": null,
        "ogimage": null,
        "favicon": null,
        "after_message": "<p>Thank you, we'll be in touch.</p>",
        "after_redirect_url": null,
        "after_message_email_subject": null,
        "after_message_email": null,
        "field_errormessage": "This field is mandatory.",
        "slack_webhook_url": null,
        "discord_webhook_url": null,
        "webhook_secret": "PgJgzW3hdKCv",
        "replyto_email": "hello@tinydub.com",
        "checkout_canceled_message": null,
        "checkout_canceled_cta": null,
        "onboarding_completed": true,
        "timezone": "UTC",
        "locale": "de",
        "owner": {
            "name": "Andreas",
            "email": "user@example.com",
            "email_verified_at": "2024-03-28T20:08:58.000000Z",
            "two_factor_confirmed_at": null,
            "created_at": "2024-03-28T20:08:47.000000Z"
        },
        "members": [],
        "created_at": "2024-08-20T08:24:20.000000Z"
    }
}

Successful responses will return a HTTP 200 response. You can also check for a valid response by using the success state, which is either true or false.

The success state will be returned for all requests to valid endpoints.