Any questions?

Timify.me API Documentation

Your first API call

All API calls start with
https://timify.me
(for example
https://timify.me/v1/forms
) and support the following REST methods:
GET
,
POST
and
DELETE
. API always responds with a JSON object. Successful API calls always return status
200
.
To make your first test API call simply do:
GET
/v1/test

Example response

{ version: '1.0.0 beta' }

Authentication

The test method shown above is the only method that does not require authentication. To make other API calls you need to provide your API token that can be obtained from your Timify.me Dashboard. To get your API key, click on your email address in the right top corner and choose "Integrate via API" item. The token must be provided as an
X-API-KEY
header. You need to provide the token within every call (except the test one).
Once the token is provided you may test the successfull authentication by calling:
GET
/v1/session

Example response

{ account: 'john.doe@example.com' }

Error handling

If API returns a code other than
200
, then something went wrong. The JSON returned will contain an information about an error, here is an example:
{ code: 'unauthorized', message: 'Invalid form ID' }
If the method you try to access doesn't exist, then API will return the
400
code with the following JSON:
{ code: 'invalid_request', message: 'Unknown method or invalid method structure' }
If the data you are attempting to send is not a valid JSON, then API will return the
400
code with the following JSON:
{ code: 'invalid_request', message: 'The request must contain a valid JSON' }
There are also limits on the amount of calls per minute per method. Please refer to the Limitations section to learn more.

API Methods

The following API methods allow you to work with your forms and Timify.me links. Please do not forget to provide
X-API-KEY
header within every API call.

Get forms

This method allows you to fetch all imported forms.

GET
/v1/forms

Example response

{ object: 'list', data: [ { id: 1, name: 'Form name', url: 'https://timify.me/link/wefih3487', text_color: '998833', background_color: '883344', welcome_text: 'Hello world!', button_text: 'Start!' }, ... ] }

Get form

This method allows you to fetch a form by its ID.

GET
/v1/forms/{{Form ID}}

Example response

{ id: 1, name: 'Form name', url: 'https://docs.google.com/forms/d/3248', text_color: '998833', background_color: '883344', welcome_text: 'Welcome to my form', button_text: 'Start!' }

Create links

This method allows you to create links for a specified form.

POST
/v1/forms/{{Form ID}}/links/bulk

Request data

JSON parameterRequiredValue type
time_limitYesInteger
hide_timerNoBoolean
camera_trackingNoBoolean
auto_closeNoBoolean
respondentsYes
JSON parameterRequiredValue type
nameYes, if email not specifiedString
emailYes, if name not specifiedString, valid email

Please note, the amount of respondents is capped at 100. If you need to create more links, you will need to make several API calls.

Example request data

{ time_limit: 60, hide_timer: true, camera_tracking: true, auto_close: true, respondents: [ { name: 'John Doe', email: 'john.doe@example.com' }, { name: 'Jack Black' }, { email: 'rodney.mullen@example.com' } ] }

Example response

{ new_ids: [3, 4, 5] }

Error handling

StatusCodeMessage
400invalid_parameter_formatInvalid form ID format
400parameter_requiredNo time_limit provided
400invalid_parameter_formatInvalid auto_close format
400invalid_parameter_formatInvalid camera_tracking format
400invalid_parameter_formatInvalid hide_timer format
400invalid_request"hide_timer" and "auto_close" parameters cannot be "true" at the same time
400parameter_requiredNo respondents provided
400invalid_parameter_formatInvalid respondents format
400parameter_requiredNo either respondent email or name provided
400invalid_parameter_formatInvalid respondent (1) name format
400invalid_parameter_formatInvalid respondent (1) email format
403unauthorizedInvalid form ID
400invalid_parameter_formatThe number of links to create in one call is limited to 100
400invalid_parameter_formattime_limit parameter cannot be greater than 1440
400invalid_requestThere are duplicates for name-email pairs in the respondents list
400invalid_requestEither not yet sent or opened links with the same email addresses already exist for this form

Get links

This method allows you to fetch all links connected to a specified form.

GET
/v1/forms/{{Form ID}}/links
Query parameterRequiredValue type
filter_nameNoString *
filter_emailNoString *
filter_auto_closeNoBoolean
filter_hide_timerNoBoolean
filter_camera_trackingNoBoolean


* Case insensitive search. You can also use asterisks either at the start or the end of the string. For example, to match both Susanna and Randy, please use *an*. To match jessy@example.com and jenny@example.com, but not miss.jenny@example.com, simply use je*. To match strictly, omit the asterisks.

Example response

{ object: 'list', data: [ { id: 1, name: 'John Snow', email: 'john.doe@example.com', url: 'https://timify.me/link/1234', hide_timer: false, camera_tracking: true, auto_close: false, opened_at: 'Sun Mar 31 2019 14:31:38 GMT+0100', submitted_at: 'Sun Mar 31 2019 14:38:44 GMT+0100', unfocused: 2, score: 42, form_id: 1 }, ... ] }

Error handling

StatusCodeMessage
403unauthorizedInvalid form ID
400invalid_parameter_formatInvalid form ID format

Get link

This method allows you to fetch a link by its ID.

GET
/v1/links/{{Link ID}}

Example response

{ id: 3, name: 'John Snow', email: 'john.doe@example.com', url: 'https://timify.me/link/1234', hide_timer: false, camera_tracking: true, auto_close: false, opened_at: 'Sun Mar 31 2019 14:31:38 GMT+0100', submitted_at: 'Sun Mar 31 2019 14:38:44 GMT+0100', unfocused: 2, score: 42, form_id: 1 }

Error handling

StatusCodeMessage
403unauthorizedInvalid link ID
400invalid_parameter_formatInvalid link ID format

Delete link

This method allows you to delete a link by its ID.

DELETE
/v1/links/{{Link ID}}

Example response

{}

Error handling

StatusCodeMessage
403unauthorizedInvalid link ID
400invalid_parameter_formatInvalid link ID format

Limitations

Some API methods have limitations and the exact numbers depend on the plan you are currently subscribed for. The figures below represent the amounts of calls allowed per minute per each listed method. Other methods do not have limitations.
Method / PlanFREEAny personal planAny business plan
Get Forms1010600
Get Form1010600
Get Links1010600
Get Link1010600
Create Links0260
Delete Link1010600
If the limit is reached, API will return the following error:
StatusCodeMessage
406api_call_limit_errorThis method can be called only {{ X }} times per minute according to your current plan
If this error is returned, the call is not executed and you will need to wait to execute it again. Alternatively, you may upgrade your plan or simply contact us to dicsuss custom limitation figures.


Timify.me © 2017-2019 - All rights reserved
Terms & Conditions | Privacy Policy & Cookies | FAQ