Submittable API Client¶

A Python client for the Submittable.com REST API.

Submittable.com is a service that allows you to post application and submission forms for users to fill in. They allow you to collect payments for submissions, assign staff to review submissions, and generally provide the needed workflow for accepting applications or submissions for your organization.

This API client is designed to leverage the Submittable REST API via Python scripts for various tasks and management duties. The API provided by Submittable.com is currently read-only, so this client does not cover creating any data.

Contents¶

Quickstart Guide¶

This library generally installs and works like many others.

Installation¶

Install the library via pip:

pip install submittable_api_client

Basic Usage¶

Load up an API client with credentials:

In [1]: from submittable_api_client.submittable_api_client import SubmittableAPIClient
In [2]: client = SubmittableAPIClient(username='you@example.com', apitoken='555')

Note: you will need to use your own Submittable.com username and API Token.

Once the client is created it can be used to make multiple calls to the Submittable.com API. Here are some examples of the calls that can be made:

In [3]: cats = client.categories()
https://api.submittable.com/v1/categories/

In [4]: dir(cats)
Out[4]:
['__doc__',
 '__init__',
 '__module__',
 'count',
 'current_page',
 'data',
 'items',
 'items_per_page',
 'provision_categories',
 'provision_category',
 'provision_category_form',
 'provision_category_submitters',
 'provision_payments',
 'provision_submission',
 'provision_submission_assignments',
 'provision_submission_form',
 'provision_submission_history',
 'provision_submission_labels',
 'provision_submissions',
 'provision_submitters',
 'total_items',
 'total_pages',
 'type',
 'url']

In [5]: cats.count
Out[5]: 2

In [6]: for item in cats.items:
   ...:     print item.name
   ...:
Category One Name
Second Category Name

In [7]: dir(cats.items[0])
Out[7]:
['__doc__',
 '__init__',
 '__module__',
 'active',
 'blind_level',
 'blind_value',
 'category_id',
 'description',
 'expire_date',
 'form_url',
 'formfields',
 'name',
 'order',
 'start_date']

API Endpoints¶

The following API endpoints are available through this client.

Categories
Submissions
Payments
Submitters

Each one supports the sorting/filtering parameters made available by Submittable.com.

Submittable API Client Module¶

The following documentation is generated from the Submittable API Client module.

Submittable API Client¶

This module is designed to provide easy Python access to the API provided by https://submittable.com. Additional information about this API can be found at https://apidoc.submittable.com.

Requires existence of Python requests module: http://docs.python-requests.org/

class submittable_api_client.SubmittableAPIClient(username=None, apitoken=None, per_page=20)¶

The primary class instantiated to make an API call.

Parameters:	username (str) – Submittable.com username apitoken (str) – Submittable.com API token per_page (int) – Per page item limit (defaults to 20)
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

categories()¶

Returns a list of Categories. Allows no pagination.

Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

category(cat_id=None)¶

Returns information about a single Category.

Parameters:	cat_id (int) – ID of Category
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

category_form(cat_id=None)¶

Returns the form info associated with the Category.

Parameters:	cat_id (int) – ID of Category
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

category_submitters(cat_id=None, page=None, per_page=None)¶

Returns user records that have submitted this form.

Parameters:	cat_id (int) – ID of Category page (int) – Page number to start on. per_page (int) – Number of items per page to return.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

payments(year=None, month=None)¶

Returns Assignments attached to a single Submission.

Parameters:	year (int) – Year (YYYY) value to filter against. month (int) – Numeric month (MM) value to filter against.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

submission(sub_id=None)¶

Returns information about a single Submission.

Parameters:	sub_id (int) – ID of Submission object to retrieve.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

submission_assignments(sub_id=None)¶

Returns Assignments attached to a single Submission.

Parameters:	sub_id (int) – ID of Submission object to retrieve.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata

submission_file(sub_id=None, file_guid=None)¶

Returns a File attached to a single Submission.

Parameters:	sub_id (int) – ID of Submission object to retrieve. file_guid (str) – GUID for File object attached to Submission object.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

submission_form(sub_id=None)¶

Returns Form attached to a single Submission.

Parameters:	sub_id (int) – ID of Submission object to retrieve.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

submission_history(sub_id=None)¶

Returns history for a single Submission.

Parameters:	sub_id (int) – ID of Submission object to retrieve.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

submission_labels(sub_id=None)¶

Returns labels for a single Submission.

Parameters:	sub_id (int) – ID of Submission object to retrieve.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

submissions(sort='submitted', direction='desc', page=1, per_page=20, status='inprogress')¶

Returns a list of Submissions. Allows pagination, sorting and filters.

Parameters:	sort (str) – Keyword for attribute to sort against. direction (str) – Keyword for direction of sort (asc or desc). page (int) – Page number to start on. per_page (int) – Number of items per page to return. status (str) – Keyword for Status value to filter against.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

submitters(page=1, per_page=20)¶

Returns Submitters for an Organization.

Parameters:	page (int) – Page number to start on. per_page (int) – Number of items per page to return.
Returns:	`SubmittableAPIResponse` containing a list of content-specific objects and related metadata.

Submittable API Client Response¶

class submittable_api_client.SubmittableAPIResponse(response=None, obj_type=None)¶

The response object from the Submittable API. Expects reponse from requests module.

Parameters:	response (obj) – Response object from `requests` module. obj_type (str) – String keyword for type of object being requested.
Returns:	None

provision_categories()¶: Build Category-specific metadata and item objects.

provision_category()¶: Build Category-specific metadata and item objects.

provision_category_form()¶: Build category form objects.

provision_category_submitters()¶: Build category form objects.

provision_payments()¶: Build Payment-specific metadata and item objects.

provision_submission()¶: Build Submission-specific metadata and item objects.

provision_submission_assignments()¶: Build Assignment-specific metadata and item objects.

provision_submission_form()¶: Build submitted form-specific metadata and item objects.

provision_submission_history()¶: Build submission history metadata and item objects.

provision_submission_labels()¶: Build submission label metadata and item objects.

provision_submissions()¶: Build submission listing metadata and item objects.

provision_submitters()¶: Build Submitter-specific metadata and item objects.

Item Objects¶

class submittable_api_client.Category(data)¶

Item object container for Categories.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.SubmittedFormContainer(data)¶

Representation of the Submitted Form container as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.SubmissionHistory(data)¶

Representation of Submission History as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.LabelsContainer(data)¶

Representation of Labels Container as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.SubmissionLabel(data)¶

Representation of Submission Label as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.Votes(data)¶

Representation of Votes data as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.File(data)¶

Representation of files container as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.Submission(data)¶

Representation of Submission as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.Payment(data)¶

Representation of Payment as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.SubmittedFormField(data)¶

Item container for a submitted form.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.Submitter(data)¶

Item object container for Submitters.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.AssignmentsContainer(data)¶

Representation of Assignments Container as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.Assignment(data)¶

Representation of Assignment as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.FormFieldContainer(data)¶

Representation of the formfields dictionary as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

class submittable_api_client.FormFieldItem(data)¶

Representation of a formfield as a Python object.

Parameters:	data (str) – Data dictionary in JSON format.

Submittable API Client¶

Contents¶

Quickstart Guide¶

Installation¶

Basic Usage¶

API Endpoints¶

Submittable API Client Module¶

Submittable API Client¶

Submittable API Client Response¶

Item Objects¶

Indices and tables¶