#FileThis Resource API
##Introduction
This document defines a subset of the FileThis REST API necessary and sufficient for partner integration.
The schemas for the request and response bodies below are defined using JSON Schema.
Examples can be validated against schemas here.
##Error Responses
When a request succeeds, the response will contain a HTTP 200 ('OK') status code, and the contents of the body of the response will be specific to the particular request, as described below for each request. If the request fails for any reason, then the response will contain one of a limited number of HTTP Client Error (4XX) status codes, and the body of the response will contain a JSON body of the following format:
Error response body schema:
{
"title": "ErrorResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"status":
{
"description": "HTTP status code. Will always match the response's HTTP status code",
"type": "integer",
"required": true
},
"message":
{
"description": "Message describing the error that occured",
"type": "string",
"required": true
}
}
}Error response body example:
{
"status": 409,
"message": "An account already exists with the specified 'partnerAccountId'"
}###General error resonses These error responses can occur in response to any of the requests described in this document:
Malformed request (400) error
Any request that does not conform to the specification of that request, or that provides data that is in some way invalid, will return a 400 ('Bad Request') status code, and the returned message will provide specific information as to what was wrong with the request.
Unauthenticated request (401) error
Any request that does not contain proper authentication information will return a 401 ('Unauthorized') status code.
Other errors may occur based on the current state of the calling partner's account data. These errors are noted below as part of the description of each type of request.
Forbidden request (403) error
A partner may operate only on acounts that it has created, and on objects associated with those accounts. If an attempt is made to operate on an object that is associated with an account that the partner does not own, then a response with a statis code of 403 ('Forbidden') will be returned.
###Other error responses
Error responses that will only occur for a subset of the requests decribed below will be noted in the description for each request.
##Account Operations
###Create account
POST /accounts
Resource: POST : https://filethis.com/api/v1/accounts
Request body schema:
{
"title": "AccountCreateRequest",
"type": "object",
"additionalProperties": false,
"properties":
{
"partnerAccountId":
{
"description": "An externally-defined unique id to be stored in account",
"type": "string",
"required": false
}
}
}Notes: The partnerAccountId parameter is not required by the API.
Request body example:
{
"partnerAccountId": "userAccount123"
}Response body schema:
{
"title": "AccountCreateResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "The FileThis-defined unique id for the newly-created account",
"type": "string",
"required": true
}
}
}Response body example:
{
"id": "filethisAccount456"
}Error responses:
409 ('Conflict') - Will occur if a partner attempts to create a new account by providing a 'partnerAccountId' value that matches one of that partner's existing accounts. Each account for a particular partner must have a unique 'partnerAccountId' value.
###Delete account
Delete FileThis user account and all associated objects and data.
This includes connection and question records and any files not yet delivered.
Resource: DELETE : https://filethis.com/api/v1/account/<account_id>
Error responses:
404 ('Not Found') - Will occur if a partner attempts to delete a non-existent account.
###Create source/institution connection
When a connection is successfully created, FileThis will automatically initiate the first fetch of documents.
POST /accounts/<account_id>/connections
Resource: POST : https://filethis.com/api/v1/accounts/<account_id>/connections
Request body schema:
{
"title": "ConnectionCreateRequest",
"type": "object",
"additionalProperties": false,
"properties":
{
"sourceId":
{
"description": "The FileThis unique id for the source/institution to which it will connect",
"type": "string",
"required": true
},
"username":
{
"description": "Username for user's institution account, Base64-encoded",
"type": "string",
"required": true
},
"password":
{
"description": "Password for user's institution account, Base64-encoded",
"type": "string",
"required": true
}
}
}Request body example:
{
"sourceId": "verizon123",
"username": "YXQgYnkgYSBwZXJzZ",
"password": "YmxlIGdlbmVyYXR"
}Response body schema:
{
"title": "ConnectionCreateResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "The FileThis-defined unique id for the newly-created connection",
"type": "string",
"required": true
}
}
}Response body example:
{
"id": "connection456"
}Error responses:
404 ('Not Found') - Will occur if a partner attempts to create a connection for a non-existent account or specifies a 'sourceId' that does not map to an exising source.
409 ('Conflict') - Will occur if a partner attempts to create a connection that already exists in the specified account or if the number of allowed connections for an account has already been reached.
###Get a connection
GET /accounts/<account_id>/connections/<connection_id>
Resource: GET : https://filethis.com/api/v1/accounts/<account_id>/connections/<connection_id>
Response body schema:
{
"title": "ConnectionGetResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Unique id for connection",
"type": "string",
"required": true
},
"sourceId":
{
"description": "Unique id of connections source/institution",
"type": "string",
"required": true
},
"state":
{
"description": "The current state of the connection",
"type": "string",
"enum" : ["waiting", "connecting", "question", "error"],
"required": true
}
}
}Note: There are a few other intermediate states that can be ignored.
Response body example:
{
"id": "connection789",
"sourceId": "source789",
"state": "error"
}Error responses:
404 ('Not Found') - Will occur if a request is made for an account or a connection that does not exist.
###Get all connections
GET /accounts/<account_id>/connections
Resource: GET : https://filethis.com/api/v1/accounts/<account_id>/connections
Response body schema:
{
"title": "ConnectionsGetResponse",
"type": "array",
"items":
{
"title": "Connection",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Unique id for connection",
"type": "string",
"required": true
},
"sourceId":
{
"description": "Unique id of connections source/institution",
"type": "string",
"required": true
},
"state":
{
"description": "The current state of the connection",
"type": "string",
"enum" : ["waiting", "connecting", "completed", "question", "error"],
"required": true
}
}
}
}Response body example:
[
{
"id": "connection123",
"sourceId": "source123",
"state": "waiting"
},
{
"id": "connection456",
"sourceId": "source456",
"state": "question"
},
{
"id": "connection789",
"sourceId": "source789",
"state": "error"
}
]###Update connection credentials
PUT /accounts/<account_id>/connections/<connection_id>/credentials
Resource: PUT : https://filethis.com/api/v1/accounts/<account_id>/connections/<connection_id>/credentials
Request body schema:
{
"title": "ConnectionPutRequest",
"type": "object",
"additionalProperties": false,
"properties":
{
"username":
{
"description": "Username for user's institution account, Base64-encoded",
"type": "string",
"required": true
},
"password":
{
"description": "Password for user's institution account, Base64-encoded",
"type": "string",
"required": true
}
}
}Request body example:
{
"username": "YXQgYnkgYSBwZXJzZ",
"password": "YmxlIGdlbmVyYXR"
}Error responses:
404 ('Not Found') - Will occur if a request is made for an account or a connection that does not exist.
###Delete connection
Any files not yet delivered are also deleted.
DELETE /accounts/<account_id>/connections/<connection_id>
Resource: DELETE : https://filethis.com/api/v1/accounts/<account_id>/connections/<connection_id>
###Get all questions in a connection
This returns all questions in a given connection, whether they are answered, or not. The "state" property of a question can be one of "pending", or "answered". Almost always there is a single "pending" question in the returned list, but callers should be prepared for the possibility of there being more than one, posing a sequence of user dialogs.
GET /accounts/<account_id>/connections/<connection_id>/questions
Resource: GET : https://filethis.com/api/v1/accounts/<account_id>/connections/<connection_id>/questions
Response body schema:
{
"title": "QuestionsGetResponse",
"type": "array",
"items":
{
"title": "Question",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Unique id for question",
"type": "string",
"required": true
},
"type":
{
"description": "The type of question",
"type": "string",
"enum" : ["complex", "credentials", "two_letter_state", "branch_code", "pin", "not_supported", "not_paperless", "user_locked_out", "user_action_required", "user_must_set_up_account", "general_security_problem"],
"required": true
},
"state":
{
"description": "What state the question is in.",
"type": "string",
"enum" : ["pending", "answered"]
},
"question":
{
"description": "The question data. Depends on the question kind.",
"type": "string",
"required": false
},
"persistent":
{
"description": "Whether the question can be answered at a later time, or not",
"type": "string",
"required": false
}
}
}
}Response body examples:
[
{
"id": "question789",
"type": "credentials",
"state": "pending",
"question": ""
},
{
"id": "question456",
"type": "two_letter_state",
"state": "answered",
"question": ""
}
]Error responses:
404 ('Not Found') - Will occur if a request is made for an account or a connection that does not exist.
###Get a single question
This returns a single question resource.
GET /accounts/<account_id>/connections/<connection_id>/questions/<question_id>
Resource: GET : https://filethis.com/api/v1/accounts/<account_id>/connections/<connection_id>/questions/<question_id>
Response body schema:
{
"title": "Question",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Unique id for question",
"type": "string",
"required": true
},
"type":
{
"description": "The type of question",
"type": "string",
"enum" : ["complex", "credentials", "two_letter_state", "branch_code", "pin", "not_supported", "not_paperless", "user_locked_out", "user_action_required", "user_must_set_up_account", "general_security_problem"],
"required": true
},
"state":
{
"description": "What state the question is in.",
"type": "string",
"enum" : ["pending", "answered"],
},
"question":
{
"description": "The question data. Depends on the question kind.",
"type": "string",
"required": false
},
"persistent":
{
"description": "Whether the question can be answered at a later time, or not",
"type": "string",
"required": false
}
}
}Response body examples:
{
"id": "question789",
"type": "credentials",
"state": "pending",
"question": ""
}Error responses:
404 ('Not Found') - Will occur if a request is made for an account, connection or question that does not exist.
###Answer pending question
This request can be use to answer a question and thereby unblock a connection whose state is "question". If the question is successfully updated, a fetch operation for the associated connection will be started, or resumed.
PUT /accounts/<account_id>/connections/<connection_id>/questions/<question_id>/answer
Resource: PUT : /api/v1/accounts/<account_id>/connections/<connection_id>/questions/<question_id>/answer
Request body schema:
{
"title": "QuestionAnswerRequest",
"type": "object",
"additionalProperties": false,
"properties":
{
"answer":
{
"description": "The answer to the given question, Base64-encoded",
"type": "string",
"required": true
}
}
}Request body example:
{
"answer": "IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1c3Qgb2Yg"
}Error responses:
404 ('Not Found') - Will occur if a request is made for an account, connection or question that does not exist.
###Create a new change notification subscriber
This request creates a subscriber endpoint to which notification requests will be sent. This endpoint must be a publicly available HTTPS service that accepts POST requests to the supplied URL. Records posted to this endpoint will consist of a JSON-encoded data structure containing one or more notification messages.
POST /subscribers
Resource: POST : /api/v1/subscribers
Request body schema:
{
"title": "NotificationSubscriberCreate",
"type": "object",
"additionalProperties": false,
"properties":
{
"name":
{
"description": "A descriptive name for this subscriber.",
"type": "string",
"required": true
},
"receiver":
{
"description": "URL of webhook receiver where FileThis will deliver change notifications.",
"type": "string",
"required": true
},
"format":
{
"description": "The change notification format you prefer.",
"type": "string",
"enum" : ["grouped", "chronological"],
"required": false,
"default": "chronological"
},
"connectionTimeout":
{
"description": "URL of webhook receiver where FileThis will deliver change notifications.",
"type": "integer",
"required": false
},
"socketTimeout":
{
"description": "URL of webhook receiver where FileThis will deliver change notifications.",
"type": "integer",
"required": false
},
"retryIntervals":
{
"description": "URL of webhook receiver where FileThis will deliver change notifications.",
"type": "string",
"required": false
},
}
}Request body example:
{
"name": "Acme Widgets Notification Receiver",
"receiver": "https://www.acmewidgets.com/apis/filethis/notifications",
"format": "grouped"
}Response body schema:
{
"title": "NotificationSubscriberCreateResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "The FileThis-defined unique id for the newly-created subscriber",
"type": "integer",
"required": true
}
}
}Response body example:
{
"id": 35
}Error responses:
409 ('Conflict') - Will occur if a partner attempts to create a subscriber with a 'receiver' value that matches an existing subscriber. Each of a partner's subscribers must have a unique 'receiver' value.
###Get information about a subscriber
This request retreives information about a previously created subscriber endpoint.
GET /subscribers/<subscriber_id>
Resource: GET : /api/v1/subscribers/<subscriber_id>
Response body schema:
{
"title": "NotificationSubscriberGetResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Id of subscriber",
"type": "string",
"required": true
},
"name":
{
"description": "A descriptive name for this subscriber",
"type": "string",
"required": true
},
"created":
{
"description": "Time subscriber was created",
"type": "string",
"required": true
},
"receiver":
{
"description": "URL of webhook receiver where FileThis will deliver change notifications",
"type": "string",
"required": true
},
"state":
{
"description": "The state of the subscriber",
"type": "string",
"enum": ["ready", "holding", "retrying"],
"required": true
},
"postpone":
{
"description": "Time the next notification will be attempted",
"type": "string",
"required": true
},
"checked":
{
"description": "Time we checked for pending notifications",
"type": "string",
"required": true
},
"attempted":
{
"description": "Time we attempted to send notifications",
"type": "string",
"required": true
},
"notified":
{
"description": "Time notifications were successfully delivered",
"type": "string",
"required": true
},
"error":
{
"description": "Description of last notification error",
"type": "string",
"required": true
},
"format":
{
"description": "The change notification format you prefer",
"type": "string",
"required": true
},
"tries":
{
"description": "The number of unsuccessful attempts to deliver notifications",
"type": "string",
"required": true
},
"connectionTimeout":
{
"description": "The webhook receiver socket connection timeout in milliseconds",
"type": "string",
"required": true
},
"socketTimeout":
{
"description": "The webhook receiver socket timeout in milliseconds",
"type": "string",
"required": true
},
"retryIntervals":
{
"description": "The webhook receiver retry intervals in seconds. A comma-separated list",
"type": "string",
"required": true
}
}
}Response body example:
{
"receiver":"http://respondto.it/filethis",
"error":"none",
"partnerId":"3",
"state":"ready",
"format":"chronological",
"attempted":"2013-09-21T15:28:55Z",
"id":"4",
"connectionTimeout":"5",
"postpone":"2013-09-21T00:10:27Z",
"retryIntervals":"1, 2, 4, 8, 16",
"socketTimeout":"5",
"created":"2013-09-21T00:10:27Z",
"name":"Main",
"notified":"2013-09-21T15:28:55Z",
"tries":"0",
"checked":"2013-09-23T00:25:40Z"
}Error responses:
404 ('Not Found') - Will occur if a request is made for an subscriber that does not exist.
###Get information about all subscribers
This request retreives information about all previously registered subscribers.
GET /subscribers
Resource: GET : /api/v1/subscribers
Response body schema:
{
"title": "NotificationSubscribersGetResponse",
"type": "array",
"items":
{
"title": "Subscriber",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Id of subscriber",
"type": "string",
"required": true
},
"name":
{
"description": "A descriptive name for this subscriber",
"type": "string",
"required": true
},
"created":
{
"description": "Time subscriber was created",
"type": "string",
"required": true
},
"receiver":
{
"description": "URL of webhook receiver where FileThis will deliver change notifications",
"type": "string",
"required": true
},
"state":
{
"description": "The state of the subscriber",
"type": "string",
"enum": ["ready", "holding", "retrying"],
"required": true
},
"postpone":
{
"description": "Time the next notification will be attempted",
"type": "string",
"required": true
},
"checked":
{
"description": "Time we checked for pending notifications",
"type": "string",
"required": true
},
"attempted":
{
"description": "Time we attempted to send notifications",
"type": "string",
"required": true
},
"notified":
{
"description": "Time notifications were successfully delivered",
"type": "string",
"required": true
},
"error":
{
"description": "Description of last notification error",
"type": "string",
"required": true
},
"format":
{
"description": "The change notification format you prefer",
"type": "string",
"required": true
},
"tries":
{
"description": "The number of unsuccessful attempts to deliver notifications",
"type": "string",
"required": true
},
"connectionTimeout":
{
"description": "The webhook receiver socket connection timeout in milliseconds",
"type": "string",
"required": true
},
"socketTimeout":
{
"description": "The webhook receiver socket timeout in milliseconds",
"type": "string",
"required": true
},
"retryIntervals":
{
"description": "The webhook receiver retry intervals in seconds. A comma-separated list",
"type": "string",
"required": true
}
}
}
}Response body example:
[
{
"receiver":"http://respondto.it/filethis",
"error":"none",
"partnerId":"3",
"state":"ready",
"format":"chronological",
"attempted":"2013-09-21T15:28:55Z",
"id":"4",
"connectionTimeout":"5",
"postpone":"2013-09-21T00:10:27Z",
"retryIntervals":"1, 2, 4, 8, 16",
"socketTimeout":"5",
"created":"2013-09-21T00:10:27Z",
"name":"Main",
"notified":"2013-09-21T15:28:55Z",
"tries":"0",
"checked":"2013-09-23T00:25:40Z"
}
]###Delete a subscriber
This request removes a previously registered subscriber, including all of its registered subscriptions, from the system.
DELETE /subscribers/<subscriber_id>
Resource: DELETE : /api/v1/subscribers/<subscriber_id>
Error responses:
404 ('Not Found') - Will occur if a an attempt is made to delete a subscriber that does not exist.
###Create a new change notification subscription
This request creates a subscription for a particular subscriber. A subscription is a request to recieve a notification when the state of a particular resource or type of resource is changed. Each subscription requests that a notification be sent when selected resources are created, modified or deleted (a separate subscription is necessary for each type of change).
POST /subscribers/<subscriber_id>/subscriptions
Resource: POST : /api/v1/subscribers/<subscriber_id>/subscriptions
Request body schema:
json
{
"title": "NotificationSubscriptionCreate",
"type": "object",
"additionalProperties": false,
"properties":
{
"changeType":
{
"description": "The type of change subscribed to",
"type": "string",
"enum": ["created", "updated", "deleted"]
"required": true
},
"resourcePattern":
{
"description": "The resource pattern to match",
"type": "string",
"required": true
}
}
}
Request body example:
{
"resourcePattern":"/deliveries/*",
"changeType":"created"
}Response body schema:
{
"title": "NotificationSubscriptionCreateResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "The FileThis-defined unique id for the newly-created subscription",
"type": "integer",
"required": true
}
}
}Response body example:
{
"id": 3135
}Error responses:
404 ('Not Found') - Will occur if a request is made for an subscriber that does not exist.
409 ('Conflict') - Will occur if a partner attempts to create a subscription with 'changeType' and 'resourcePattern' values that matches an existing subscription. Each of a partner's subscription must have unique 'changeType' and 'resourcePattern' values.
###Get information about a single subscription
This request retreives information about a previously created subscription.
GET /subscribers/<subscriber_id>/subscriptions/<subscription_id>
Resource: GET : /api/v1/subscribers/<subscriber_id>/subscriptions/<subscription_id>
Response body schema:
{
"title": "NotificationSubscriptionGetResponse",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Id of subscription",
"type": "string",
"required": true
},
"subscriberId":
{
"subscriberId": "Id of subscription's subscriber",
"type": "string",
"required": true
},
"changeType":
{
"description": "The type of changes subscribed to",
"type": "string",
"enum": ["created", "updated", "deleted"]
"required": true
},
"resourcePattern":
{
"description": "Pattern of resources subscribed to",
"type": "string",
"required": true
},
"created":
{
"description": "The time the subscription was created",
"type": "string",
"required": true
}
}
}Response body example:
{
"resourcePattern":"/subscribers/subscriptions/*",
"id":"9",
"changeType":"updated",
"created":"2013-09-23T00:33:40Z",
"partnerId":"3",
"subscriberId":"4"
}Error responses:
404 ('Not Found') - Will occur if a request is made to obtain information about a subscriber or subscription that does not exist.
###Get information about all subscriptions for a subscriber
This request retreives information about all previously registered subscribers.
GET /subscribers/<subscriber_id>/subscriptions
Resource: GET : /api/v1/subscribers/<subscriber_id>/subscriptions
Response body schema:
{
"title": "NotificationSubscriptionsGetResponse",
"type": "array",
"items":
{
"title": "Subscriptions",
"type": "object",
"additionalProperties": false,
"properties":
{
"id":
{
"description": "Id of subscription",
"type": "string",
"required": true
},
"subscriberId":
{
"subscriberId": "Id of subscription's subscriber",
"type": "string",
"required": true
},
"changeType":
{
"description": "The type of changes subscribed to",
"type": "string",
"enum": ["created", "updated", "deleted"]
"required": true
},
"resourcePattern":
{
"description": "Pattern of resources subscribed to",
"type": "string",
"required": true
},
"created":
{
"description": "The time the subscription was created",
"type": "string",
"required": true
}
}
}
}Response body example:
[
{
"resourcePattern":"/deliveries/*",
"id":"8",
"changeType":"created",
"created":"2013-09-23T00:29:47Z",
"partnerId":"3",
"subscriberId":"4"
},
{
"resourcePattern":"/subscribers/subscriptions/*",
"id":"9",
"changeType":"updated",
"created":"2013-09-23T00:33:40Z",
"partnerId":"3",
"subscriberId":"4"
}
]Error responses:
404 ('Not Found') - Will occur if a request is made to request information fo a subscriber that does not exist.
###Delete a subscription
This request removes a previously registered subscription from the system.
DELETE /subscribers/<subscriber_id>/subscriptions/<subscription_id>
Resource: DELETE : /api/v1/subscribers/<subscriber_id>/subscriptions/<subscription_id>
Error responses:
404 ('Not Found') - Will occur if an attempt is made to delete a subscription that does not exist.