{ "openapi": "3.0.0", "info": { "title": "fetchdocs API", "description": "

Authentication

\n There are two ways to access protected API endpoints. You can use either of them.\n
\n
\n 1. API key \n
\n
\n This is the API key of an environment. It is generated by our supported team for each client.\n
\n To authenticate APIs, you have to send this API key with the X-API-KEY header.\n
\n
\n 2. Session token \n
\n
\n This is the token generated by UI session API, which identifiers the user's identity. It is valid for only 30 minutes.\n
\n You can access APIs releated to identities, integrations, connections and transactions with the help of this token.\n
\n To authenticate APIs, you have to send this token with the X-TOKEN header.\n
\n
\n

Localization

\n To set the app language, you can pass `Lang` header via any request to the API.\n
\n Currently the allowed languages are `en` and `de`.\n
\n
\n

Dates and Datetimes

\n For all `dates` and `datetimes` we use the RFC 3339 standard. It is mostly compatible with ISO 8601 but allows\n less odd formats (see: RFC 3339 vs ISO 8601).", "version": "1.0" }, "servers": [ { "url": "http://localhost" } ], "paths": { "/v1/connections": { "get": { "tags": [ "Connections" ], "summary": "List connections", "description": "List all connections of the authenticated user.", "operationId": "e6542f10da02de31749a03f836a78f7b", "parameters": [ { "name": "integration", "in": "query", "description": "Filter for connections of a specific integration.", "required": false, "schema": { "type": "string" }, "example": "aws_s3" }, { "name": "webhook", "in": "query", "description": "Filter for connections with or without a registered webhook.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "example": "true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ListConnections" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] }, "post": { "tags": [ "Connections" ], "summary": "Create a new connection (step 1)", "operationId": "6be5dcdd052c5ede31bfa038b70ecc75", "requestBody": { "content": { "application/json": { "schema": { "required": [ "integration_id", "name", "fields" ], "properties": { "integration_id": { "title": "Integration ID", "description": "The ID of the integration the connection should be created for.", "type": "string", "example": "aws_s3" }, "name": { "title": "Name", "description": "The name of the connection. This can be a human-readable name for the connection and can later be shown to the user. It is fine to allow the user to define the name of the connection.", "type": "string", "example": "AWS S3 Marketing" }, "identity_uuid": { "title": "Identity UUID", "description": "The identitiy uuid is required when created by an environment (authentication via API Key). The identity must belong to the environment.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "fields": { "title": "Fields", "description": "Fields required by the integration from step 1. The fields are different for each integration and provided as a key-value pair, using the field id as key and the user input as value.", "type": "object", "example": { "username": "mustermann", "password": "123456" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ConnectionCreatedStep1" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [], "ApiKeyAuth": [] } ] } }, "/v1/connections/{uuid}": { "get": { "tags": [ "Connections" ], "summary": "Get a connection", "description": "This endpoint provides the details of a connection.", "operationId": "9972b249094638a4f6211d9c817233f8", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection that should be fetched.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GetConnection" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [], "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Connections" ], "summary": "Update a connection", "description": "This endpoint updates a connection. The fields of the first step are updated. If the integration has a second step, the fields of the second step are provided in the response and can be updated with the _update a connection (step 2)_ endpoint.", "operationId": "0a6b2d32fc5183d51a762b713c1d39d3", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection that should be updated.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fields": { "title": "Fields", "description": "Fields of the first step that should be updated. The fields are different for each integration and provided as a key-value pair, using the field id as key and the user input as value.", "type": "object", "example": { "path": "foo/bar/" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ConnectionUpdated" } }, "type": "object" } } } }, "204": { "description": "Updated, but no response content provided" }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] }, "delete": { "tags": [ "Connections" ], "summary": "Delete a connection", "description": "This endpoint deletes a connection and all its related data. This step is irreversible.", "operationId": "8b79d93091abd800fed34949f22ccbd3", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection that should be deleted.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "responses": { "204": { "description": "No Content (Success)" }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [], "ApiKeyAuth": [] } ] } }, "/v1/connections/{uuid}/disable": { "put": { "tags": [ "Connections" ], "summary": "Disable a connection", "description": "This endpoint disables a connection. No new transactions can be created with a disabled connection.", "operationId": "bd3ccda5c3eaf80cceb2ffcc400174d8", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection that should be disabled.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "responses": { "204": { "description": "No Content (Success)" }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [], "ApiKeyAuth": [] } ] } }, "/v1/connections/{uuid}/enable": { "put": { "tags": [ "Connections" ], "summary": "Enable a connection", "description": "This endpoint enables a connection. New transactions can be created with an enabled connection.", "operationId": "b9a9f84d95f77402f361badfba5986ff", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection that should be enabled.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "responses": { "204": { "description": "No Content (Success)" }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [], "ApiKeyAuth": [] } ] } }, "/v1/connections/{uuid}/fetch-now": { "post": { "tags": [ "Connections" ], "summary": "Trigger a manual fetch", "description": "Triggers an on-demand fetch for the given connection. Manual fetches are limited to 5 per hour per connection and are rejected if a scheduled fetch is already due within the next minute.", "operationId": "565c4b7c454df96fa3d671a69fd6f66e", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection that should be fetched.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "responses": { "202": { "description": "Accepted - the fetch has been queued for processing.", "content": { "application/json": { "schema": { "properties": { "uuid": { "description": "The UUID of the newly created fetch.", "type": "string", "format": "uuid", "example": "b1f6f0a2-1f1c-4d39-9c70-2d3b4f5e6789" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "409": { "description": "Conflict - a scheduled fetch is already due within the next minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity - the connection is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "429": { "description": "Too Many Requests - rate limit of 5 manual fetches per hour per connection exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [], "ApiKeyAuth": [] } ] } }, "/v1/connections/{uuid}/information": { "get": { "tags": [ "Connections" ], "summary": "Get the connection information", "description": "This endpoint provides a read-only, human-readable view of the data a user entered when setting up a connection (step 1 and step 2 fields), without ever exposing secrets. Opaque identifiers (e.g. folder ids) are accompanied by a resolved `display_value` when one has been stored. No live provider calls are made.", "operationId": "b51e2fac08fb3842cfaaf2a7eed78c3b", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection whose information should be fetched.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GetConnectionInformation" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [], "ApiKeyAuth": [] } ] } }, "/v1/connections/{uuid}/step2": { "get": { "tags": [ "Connections" ], "summary": "Get connection step 2 fields", "description": "Get connections step 2 fields. This is especially relevant for OAuth integrations, where the fields can not be part of the create response.", "operationId": "df02fd4bef81710dc40bf20cf3200e8b", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection the fields should be fetched for.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "responses": { "200": { "description": "Successfull", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GetConnectionStep2Fields" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] }, "put": { "tags": [ "Connections" ], "summary": "Update a connection (step 2)", "operationId": "0e3cc5f431eef2368e15c944f564f1f9", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection that should be updated.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fields": { "title": "Fields", "description": "Fields required by the integration from step 2. The fields are different for each integration and provided as a key-value pair, using the field id as key and the user input as value", "type": "object", "example": { "path": "foo/bar/" } }, "isUpdateFlow": { "title": "Is Update Flow", "description": "Indicates whether this is an update flow or a new connection", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated and requires additional OAuth flow", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ConnectionUpdated" } }, "type": "object" } } } }, "204": { "description": "No Content (Success)" }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] } }, "/v1/connections/{uuid}/step2/{field_id}/more": { "post": { "tags": [ "Connections" ], "summary": "Lazyload field options", "description": "Load more options for a field. This allows lazy loading of options for fields that have a lot of options, like folder trees.", "operationId": "5f1c9f825adc84af39ebc96e40cb6c9a", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the connection for which further options are to be retrieved.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, { "name": "field_id", "in": "path", "description": "ID of the field that should be loaded more options for", "required": true, "schema": { "type": "string" }, "example": "folder_id" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "parent_id": { "title": "Parent ID", "description": "Provide the parent id of the field that should be loaded more options for. This is used to load more options for a specific folder tree.", "type": "string", "example": "foo/bar" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfull", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GetConnectionStep2FieldsLoadMore" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] } }, "/v1/connections/migrate": { "post": { "tags": [ "Connections" ], "summary": "Migrate a connection", "description": "Create a new connection by migrating it from your application to fetchdocs. This endpoint creates a new connection and stores the credentials at fetchdocs. If the integration requires OAuth, the connection is created in status `INVALID_CREDENTIALS`. A `startdate` sent in `fields` is ignored: migrated connections always get the migration date as startdate, so only documents created on or after the migration are fetched.", "operationId": "ffe2aefb9366c34e9f59958ee53bc9e7", "requestBody": { "content": { "application/json": { "schema": { "required": [ "integration_id", "identity_uuid", "name", "fields" ], "properties": { "identity_uuid": { "title": "Identity UUID", "description": "The UUID of the identity the connection should be created for.", "type": "string", "format": "uuid", "example": "81c4de7f-cdba-4f45-ba2c-dd8060fde7e5" }, "integration_id": { "title": "Integration ID", "description": "The ID of the integration the connection should be created for.", "type": "string", "example": "aws_s3" }, "name": { "title": "Name", "description": "The name of the connection. Can later be shown to the user.", "type": "string", "example": "My Connection" }, "fields": { "title": "Fields", "description": "The fields required by the integration. The fields are dynamic and depend on the integration. The fields are validated by the integration itself.", "type": "object", "example": { "secret_id": "mustermann", "secret_key": "123456" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ConnectionMigratedResource" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/identities": { "post": { "tags": [ "Identities" ], "summary": "Create a new identity", "operationId": "92813e70ba3096a51a3a14f8bcc887b4", "requestBody": { "content": { "application/json": { "schema": { "required": [ "client_identifier" ], "properties": { "name": { "title": "Name", "description": "The name of the identity.", "type": "string", "example": "John Doe" }, "client_identifier": { "title": "Client identifier", "description": "Identifier of the identity in the client app. It is used to identify the identity and must be unique within an environment.", "type": "string", "example": "43y34h" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Identity" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/identities/search": { "get": { "tags": [ "Identities" ], "summary": "Search for an identity", "description": "Search for an identity by client identifier. Returns the identity if found, `404` if not found, and `406` when more then one identity is found.", "operationId": "562f8ff2f5af43ec0a8c82f7e7c23682", "parameters": [ { "name": "client_identifier", "in": "query", "description": "Identifier of the identity in the client app.", "required": false, "schema": { "type": "string" }, "example": "123456789" } ], "responses": { "200": { "description": "Found one identity", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Identity" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseExample" } } } }, "406": { "description": "Not Acceptable - More then one entry was found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAcceptableErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/integrations": { "get": { "tags": [ "Integration" ], "summary": "List integrations", "description": "List all available integrations", "operationId": "5a1f055bf835867767f7914921c215d1", "responses": { "200": { "description": "Successfull", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListIntegrations" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] } }, "/v1/log": { "post": { "tags": [ "Log" ], "summary": "Create log entry", "description": "Create a log entry for errors and debug in the frontend UI.", "operationId": "9428bd881c4762046fffbac95d6a9668", "requestBody": { "content": { "application/json": { "schema": { "required": [ "level", "message" ], "properties": { "level": { "title": "Level", "description": "The log level of the message.", "type": "string", "enum": [ "debug", "info", "notice", "warning", "error", "critical", "alert", "emergency" ], "example": "error" }, "message": { "title": "Message", "description": "Error message to log.", "type": "string", "example": "An error occured in main.js line 123." }, "environment": { "title": "Environment", "description": "The environment where the error occured. Useful for filtering and escaltion in the logs.", "type": "string", "example": "staging" }, "domain": { "title": "Domain", "description": "The domain under which the error occured. Useful for filtering in the logs.", "type": "string", "example": "https://example.fetchdocs.io" }, "context": { "title": "Context", "description": "Additional context to log. Useful for debugging.", "type": "array", "items": {}, "example": "{identity_uuid: 123}" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] } }, "/v1/token": { "post": { "tags": [ "Token" ], "summary": "Create a new token", "description": "Create a new token that is used for the frontend UI to authenticate the user (identity).", "operationId": "0fbf33d4a3729c8fc44208034e1d1bfa", "requestBody": { "content": { "application/json": { "schema": { "required": [ "identity_uuid", "return_url" ], "properties": { "identity_uuid": { "title": "Identity UUID", "description": "The UUID of the identity the token should be created for.", "type": "string", "example": "d2b2c5c0-0f1a-4e1a-9e1a-0e1a1a1a1a1a" }, "return_url": { "title": "Return URL", "description": "The URL the user will be redirected to after successful or unsuccessful usage of fetchdocs.", "type": "string", "example": "https://www.example.com/documents" }, "integration_id": { "title": "Integration ID", "description": "When providing an integration ID, the frontend renders directly in the create view for that integration.", "type": "string", "example": "aws_s3" }, "connection_uuid": { "title": "Connection UUID", "description": "When providing a connection UUID, the frontend renders directly in the update view for that connection.", "type": "string", "format": "uuid", "example": "ef44db65-22b3-4791-91ba-db62c28dbc07" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Token" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/token/verify": { "get": { "tags": [ "Token" ], "summary": "Verify a token", "description": "Verify a token that is used for the frontend UI to authenticate the user (identity). It returns the required information for the frontend UI.", "operationId": "49ea4fcccb947020a4a9d6b918142df8", "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VerifyToken" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] } }, "/v1/url/sign": { "post": { "tags": [ "URL Signing" ], "summary": "Sign a URL", "description": "For security reasons URLs redirecting back to the application must be signed to prevent tampering. This endpoint signs a URL and returns the signed URL. For singing the URL the environment's API key is used. That allows validating the signature on the client side as well.", "operationId": "76dc7a66635ea0d458c947918ef4c337", "requestBody": { "content": { "application/json": { "schema": { "required": [ "url" ], "properties": { "url": { "title": "URL", "description": "The URL to sign including all query parameters", "type": "string", "example": "https://example.com?foo=bar&baz=qux" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfull", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SignedUrl" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponseExample" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponseExample" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalErrorResponseExample" } } } } }, "security": [ { "TokenAuth": [] } ] } } }, "components": { "schemas": { "Environment": { "title": "Environment", "description": "Object that represents an environment.", "properties": { "uuid": { "title": "Environment UUID", "description": "The UUID of the environment.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "subdomain": { "title": "Subdomain", "description": "The subdomain of the environment under that the frontend UI is accessible.", "type": "string", "example": "demo-company" }, "theme": { "title": "Theme", "description": "The theme of the environment. We support multiple themes and also provide custom made themes for our customers.", "type": "string", "example": "default", "nullable": true }, "primary_color": { "title": "Primary Color", "description": "The primary color of the environment used for some themes in the frontend UI. The color is in HEX format.", "type": "string", "format": "hex", "example": "#ffffff", "nullable": true }, "secondary_color": { "title": "Secondary Color", "description": "The secondary color of the environment used for some themes in the frontend UI. The color is in HEX format.", "type": "string", "format": "hex", "example": "#ffffff", "nullable": true }, "border_radius": { "title": "Border Radius", "description": "The border radius of the environment used for some themes in the frontend UI.", "type": "string", "enum": [ "none", "sm", "md", "lg" ], "example": "sm", "nullable": true }, "shadow": { "title": "Shadow", "description": "The shadow of the environment used for some themes in the frontend UI.", "type": "string", "enum": [ "none", "sm", "md", "lg" ], "example": "sm", "nullable": true }, "background_image": { "title": "Background Image", "description": "Base64 encoded image of the background image of the environment.", "type": "string", "format": "base64", "example": "data:image/png;base64,iVBORw0KGgoAAAAN...ASUVORK5CYII=", "nullable": true }, "background_color": { "title": "Background Color", "description": "The background color of the environment used for some themes in the frontend UI. The color is in HEX format.", "type": "string", "format": "hex", "example": "#ffffff", "nullable": true }, "icon_set": { "title": "Icon Set", "description": "The icon set of the environment used for some themes in the frontend UI.", "type": "string", "enum": [ "fas", "far" ], "nullable": true }, "show_footer_link": { "title": "Show Footer Link", "description": "Flag to show or hide the link to the pushdocs website on the frontend UI footer.", "type": "boolean", "nullable": true }, "logo": { "title": "Logo", "description": "Base64 encoded image of the logo of the environment.", "type": "string", "example": "data:image/png;base64,iVBORw0KGgoAAAAN...ASUVORK5CYII=", "nullable": true } }, "type": "object" }, "Page": { "title": "Page", "description": "Page model", "properties": { "page": { "title": "Page", "description": "The nature of the page, like imprint or privacy policy.", "type": "string", "example": "imprint" }, "languages": { "title": "Languages", "description": "List of languages the page is associated with.", "type": "array", "items": { "type": "string" }, "example": [ "en", "de" ] }, "is_fallback": { "title": "Is Fallback", "description": "If this value is `true` it should be used as fallback for that nature of page, when no suitable page for the used languages is available.", "type": "boolean", "example": false }, "type": { "title": "Type", "description": "The type of the page, like Link or Content. Based on the type the _page_ is just a link or shows content.", "type": "string", "enum": [ "link", "content" ], "example": "link" }, "url": { "title": "URL", "description": "The URL of the page. This is only provided when the type is `link`.", "type": "string", "example": "https://www.example.com/imprint" }, "content": { "title": "Content", "description": "The content of the page in Markdown format. This is only provided when the type is `content`.", "type": "string", "example": "Lorem ipsum dolor sit amet, consectetur adipiscing elit." } }, "type": "object" }, "ConnectionCreatedStep1": { "title": "Connected created step 1", "description": "Connection created response (step 1)", "properties": { "uuid": { "title": "Connection UUID", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "fields": { "title": "Fields", "description": "Fields for the seconds step (only provided when there is a second step for the integration).", "type": "array", "items": { "$ref": "#/components/schemas/Field" } } }, "type": "object" }, "ConnectionMigratedResource": { "title": "Connection Migrated Resource", "properties": { "uuid": { "title": "Connection UUID", "description": "The UUID of the migrated connection.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" } }, "type": "object" }, "ConnectionUpdated": { "title": "Connected updated step 1", "description": "Connection updated response (step 1)", "properties": { "uuid": { "title": "Connection UUID", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "name": { "title": "Name", "description": "The name of the connection. Provided by the user on creation of the connection.", "type": "string", "example": "AWS S3" }, "status": { "title": "Status", "description": "The status of the connection.", "type": "string", "enum": [ "active", "inactive", "incomplete", "invalid_credentials" ], "example": "active" }, "fields": { "title": "Fields", "description": "Fields for the seconds step (only profivded when there is a second step for the integration).", "type": "array", "items": { "$ref": "#/components/schemas/Field" } } }, "type": "object" }, "GetConnectionInformation": { "title": "Connection information", "description": "A read-only view of the data a user entered when setting up a connection, without secrets.", "properties": { "integration": { "description": "The integration the connection belongs to.", "properties": { "id": { "type": "string", "example": "google_drive" }, "name": { "type": "string", "example": "Google Drive" }, "logo": { "description": "The integration logo as a base64 data URI.", "type": "string", "example": "data:image/svg+xml;base64,PHN2Zy4uLg==" } }, "type": "object" }, "fields": { "description": "The non-sensitive fields of the connection with their stored value and, where available, a resolved human-readable label. Fields with neither a value nor a display value are omitted. Checkbox fields are always present with a boolean value.", "type": "array", "items": { "properties": { "id": { "type": "string", "example": "path" }, "label": { "description": "The localized field name. If the requested language is not provided, use `en` as fallback.", "properties": { "en": { "type": "string", "example": "Folder" }, "de": { "type": "string", "example": "Ordner" } }, "type": "object" }, "type": { "type": "string", "example": "foldertree" }, "value": { "description": "The raw value stored in the connection configuration, or `null` when not set.", "example": "0AB...|1xY...", "nullable": true }, "display_value": { "description": "A human-readable label for the stored value, or `null` when none could be resolved.", "type": "string", "example": "Invoices / 2026", "nullable": true } }, "type": "object" } } }, "type": "object" }, "GetConnection": { "title": "Get a connection", "description": "An object representing a connection.", "properties": { "uuid": { "title": "Connection UUID", "description": "The UUID of the connection.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "name": { "title": "Name", "description": "The name of the connection. Provided by the user on creation of the connection.", "type": "string", "example": "AWS S3" }, "status": { "title": "Status", "description": "The status of the connection. The status mean the following:\n * `ACTIVE`: The connection is active and can be used.\n * `INACTIVE`: The connection is inactive and can not be used. New transanctions are being declined.\n * `INCOMPLETE`: The connection is incomplete and can not be used. That happends when the user cancells the creation process. Incomplete connection are automatically deleted after a certain time.\n * `INVALID_CREDENTIALS`: The credentials are invalid and need to be updated. New transactions are accepted but are not processed until the credentials are updated.", "type": "string", "enum": [ "ACTIVE", "INACTIVE", "INCOMPLETE", "INVALID_CREDENTIALS" ], "example": "ACTIVE" }, "webhook_enabled": { "title": "Webhook enabled", "description": "Whether a webhook is registered for this connection.", "type": "boolean", "example": false }, "start_date": { "title": "Start date", "description": "The configured start date from which documents should be fetched, when provided in the connection configuration. `null` when no start date is configured.", "type": "string", "format": "date", "example": "2026-05-20", "nullable": true }, "integration": { "$ref": "#/components/schemas/Integration" } }, "type": "object" }, "GetConnectionStep2FieldOptions": { "title": "Load connection step 2 field options", "description": "Object representing the options for a field of the second step of the connection.", "type": "object", "example": { "12345": "Max Mustermann GmbH", "54321": "Musterfirma AG" } }, "GetConnectionStep2FieldsLoadMore": { "title": "Load more connection step 2 field options", "type": "array", "items": { "properties": { "id": { "description": "The ID of the item.", "type": "string", "example": "12345678-1234-1234-1234-123456789012" }, "label": { "description": "The label of the item.", "type": "string", "example": "Incoming invoices" }, "children": { "type": "array", "items": {}, "example": "null", "nullable": true } }, "type": "object" } }, "GetConnectionStep2Fields": { "title": "Get Connection step 2 fields", "properties": { "uuid": { "title": "Connection UUID", "description": "The UUID of the connection.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "fields": { "title": "Fields", "description": "Fields for the seconds step (only profivded when there is a second step for the integration).", "type": "array", "items": { "$ref": "#/components/schemas/Field" } } }, "type": "object" }, "ListConnections": { "title": "List connections", "description": "An array of objects where each object represents a connection.", "type": "array", "items": { "properties": { "uuid": { "title": "Connection UUID", "description": "The UUID of the connection.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "name": { "title": "Name", "description": "The name of the connection. Provided by the user on creation of the connection. Can be used to show a human-readable name of the connection. It is not unique and MUST NOT be used for identification.", "type": "string", "example": "My AWS S3 Bucket" }, "status": { "title": "Status", "description": "The status of the connection.", "type": "string", "enum": [ "ACTIVE", "INACTIVE", "INCOMPLETE", "INVALID_CREDENTIALS" ], "example": "ACTIVE" }, "webhook_enabled": { "title": "Webhook enabled", "description": "Whether a webhook is registered for this connection.", "type": "boolean", "example": false }, "start_date": { "title": "Start date", "description": "The configured start date from which documents should be fetched, when provided in the connection configuration. `null` when no start date is configured.", "type": "string", "format": "date", "example": "2026-05-20", "nullable": true }, "integration": { "$ref": "#/components/schemas/Integration" } }, "type": "object" } }, "Identity": { "title": "Identity", "description": "Object that represents the identity.", "properties": { "uuid": { "title": "Identity UUID", "description": "The UUID of the identity.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "name": { "title": "Name", "description": "The name of the identity.", "type": "string", "example": "Max Mustermann" }, "client_identifier": { "title": "Client identifier", "description": "Identifier of the identity provided by the client. Most time this is an account number or ID used to identify the user in the client's system.", "type": "string", "example": "123456" } }, "type": "object" }, "Field": { "title": "Field", "description": "Field model", "properties": { "type": { "title": "Type", "description": "The field type. It is used to render the correct input field in the frontend.", "type": "string", "enum": [ "text", "secret", "select", "multiselect", "date", "foldertree", "textarea", "banner", "checkbox", "file", "phone", "iban" ], "example": "text" }, "id": { "title": "ID", "description": "The id of the field. Represents the unique identifier of the field (like in HTML the name attribute).", "type": "string", "example": "secret_id" }, "name": { "title": "Name", "description": "The name of the field. Provided in different languages. If the requested language is not provided, use `en` as fallback.", "properties": { "en": { "type": "string", "example": "Client ID" }, "de": { "type": "string", "example": "Client-ID" } }, "type": "object" }, "required": { "title": "Required", "description": "Determines if the field is required or not.", "type": "boolean", "example": false }, "disabled": { "title": "Disabled", "description": "Determines if the field is disabled or not.", "type": "boolean", "example": false }, "disabledOnEdit": { "title": "Disabled on Edit", "description": "Determines if the field is disabled on edit flow.", "type": "boolean", "example": false }, "icon": { "title": "Icon", "description": "Icon to be shown in the input field.", "type": "string", "example": "key" }, "length": { "title": "Length", "description": "The length of the field. It is used to validate the input.", "properties": { "min": { "description": "The minimum length of the field.", "type": "integer", "example": 3, "nullable": true }, "max": { "description": "The maximum length of the field.", "type": "integer", "example": 20, "nullable": true } }, "type": "object" }, "date": { "title": "Date", "description": "The min and max dates for a date field. It is used to validate the input.", "properties": { "min": { "description": "The minimum date of the field.", "type": "string", "example": "2023-01-01", "nullable": true }, "max": { "description": "The maximum date of the field.", "type": "string", "example": "2023-12-31", "nullable": true } }, "type": "object" }, "multiple": { "title": "Multiple", "description": "Determines if the field is a multiple field or not. If it is a multiple field, the user can select multiple values.", "type": "boolean", "example": false }, "suffix": { "title": "Suffix", "description": "The suffix of the field. It is used to show additional information at the end of the input field.", "type": "string", "example": "@posteingang.papierkram.de" }, "bannerType": { "title": "Banner Type", "description": "The type of the banner. It is used to render a banner as field in the frontend.", "type": "string", "example": "warning" }, "bannerContent": { "title": "Banner Content", "description": "The content of the banner. It is used to render a banner as field in the frontend.", "properties": { "en": { "type": "string", "example": "This is a warning banner" }, "de": { "type": "string", "example": "Dies ist ein Warnbanner" } }, "type": "object" }, "hint": { "title": "Hint", "description": "Additional hint for the field. It is shown below the input field. The text is provided in different languages. If the requested language is not provided, use `en` as fallback. The string itself is markdown.", "properties": { "en": { "type": "string", "example": "This is a example hint which is not very helpful. The real hint should be more helpful." }, "de": { "type": "string", "example": "Dieser Hinweis ist nicht sonderlich hilfreich. Der richtige Hinweis sollte hilfreicher sein." } }, "type": "object" }, "showOnlyOnEdit": { "title": "Show Only on Edit", "description": "Determines if the banner should only be shown on edit page and not on create.", "type": "boolean", "example": false }, "options": { "title": "Options", "description": "The options of the field. It is used to render a select field in the frontend. It is an array of objects where each object is one option.", "type": "array", "items": { "properties": { "id": { "description": "The id of the option. It must be sent to the backend when the user selects the option as the value of the select field.", "oneOf": [ { "type": "integer", "example": 12345 }, { "type": "string", "example": "eu-central-1" } ] }, "name": { "description": "The name of the option. It can be provided as string or object including different languages. If the requested language is not provided, use `en` as fallback.", "oneOf": [ { "type": "object", "example": { "en": "Munich", "de": "München" } }, { "type": "string", "example": "München" } ] } }, "type": "object" } }, "selectables": { "title": "Selectables", "description": "The selectable values of the textarea field. It is used to render selectable predefined options for users, to fill with a click into the textarea field.", "type": "array", "items": { "type": "string" }, "example": [ "[[VAT]]", "[[DOCUMENT_DATE]]" ] }, "fileTypes": { "title": "FileTypes", "description": "The allowed file types for the file field. It is used to validate the file input.", "type": "array", "items": { "type": "string" }, "example": [ "pdf", "png" ] }, "maxFileSizeInMB": { "title": "Max File Size in MB", "description": "The maximum file size in megabytes for the file field. It is used to validate the file input.", "type": "integer", "example": 5, "nullable": true }, "idc": { "title": "International Dialing Code", "description": "The international dialing code for the phone number field.", "type": "string", "example": "+49", "nullable": true }, "placeholder": { "title": "Placeholder", "description": "The placeholder of the field. It is used to show a hint in the input field.", "type": "string", "example": "Enter your client id here", "nullable": true }, "pattern": { "title": "Pattern", "description": "The pattern of the field. It is used to validate the input with a regex pattern.", "type": "string", "example": "^[a-zA-Z0-9]+$", "nullable": true }, "default": { "title": "Default", "description": "The default value of the field. It is used to prefill the input field.", "type": "string", "example": "default_value", "nullable": true }, "dependsOn": { "title": "Depends On", "description": "The field depends on another field. It is used to show or hide the field based on the value of another field. The format is `field_id:value` or `field_id1:value1|field_id2:value2` for multiple conditions (AND logic).", "type": "string", "example": "auth_type:oauth", "nullable": true }, "dependsDynamicallyOn": { "title": "Depends Dynamically On", "description": "The field depends dynamically on another field. It is used to show or hide the field based on the value of another field. The format is `field_id`. The field will be shown if the other field has a value (not null or empty).", "type": "string", "example": "folder_id", "nullable": true }, "isAdvanced": { "title": "Is Advanced", "description": "Determines if the field is an advanced field or not. Advanced fields are hidden by default and can be shown by the user.", "type": "boolean", "example": false }, "onlyOnCreate": { "title": "Only on Create", "description": "Determines if the field should only be shown on the create page and not on edit.", "type": "boolean", "example": false, "nullable": true }, "showPath": { "title": "Show Path", "description": "Determines if the full path should be shown in the folder tree field.", "type": "boolean", "example": true, "nullable": true }, "introText": { "title": "Intro Text", "description": "Introductory text for the field. It is shown above the input field. The text is provided in different languages. If the requested language is not provided, use `en` as fallback. The string itself is markdown.", "properties": { "en": { "type": "string", "example": "This is a example intro text which is not very helpful. The real intro text should be more helpful." }, "de": { "type": "string", "example": "Dieser Einführungstext ist nicht sonderlich hilfreich. Der richtige Einführungstext sollte hilfreicher sein." } }, "type": "object" }, "wrapper": { "title": "Wrapper", "description": "Additional wrapper attributes for the field. It can be used to add custom classes or styles to the field wrapper.", "properties": { "class": { "type": "string", "example": "my-custom-class" }, "style": { "type": "string", "example": "margin-bottom: 20px;" } }, "type": "object" }, "isSensitive": { "title": "Is Sensitive", "description": "Determines if the field is sensitive or not. Sensitive fields are not logged in the backend.", "type": "boolean", "example": false }, "value": { "title": "Value", "description": "The value of the field. It is used to prefill the input field. It can be a string or an integer.", "nullable": true, "oneOf": [ { "type": "string", "example": "my_value" }, { "type": "integer", "example": 12345 } ] }, "lazyLoad": { "title": "Lazy Load", "description": "Determines if the options should be loaded lazily or not. If true, the options will be loaded when the user opens the select field.", "type": "boolean", "example": false }, "sortFolders": { "title": "Sort Folders", "description": "Determines if the folders should be sorted alphabetically or not. Only relevant for folder tree fields.", "type": "boolean", "example": true }, "step": { "title": "Step", "description": "The step of the field. It is used to show fields in a stepped wizard. It is translated.", "properties": { "en": { "type": "string", "example": "This is a example help text which is not very helpful. The real help text should be more helpful." }, "de": { "type": "string", "example": "Dieser Hilfetext ist nicht sonderlich hilfreich. Der richtige Hilfetext sollte hilfreicher sein." } }, "type": "object" }, "rows": { "title": "Rows", "description": "The number of rows for the textarea field.", "type": "integer", "default": 4, "maximum": 10, "minimum": 1, "example": 4, "nullable": true }, "folders": { "title": "Folders", "description": "The options of the folder tree field. When lazy loading is enabled it only provides the first folder level. More can be loaded with the _more endpoint_ (`/v1/connections/{uuid}/step2/{field_id}/more`).", "type": "array", "items": { "properties": { "label": { "description": "The label of the folder.", "type": "string" }, "id": { "description": "The id of the folder. It must be sent to the backend when the user selects the folder.", "type": "string" }, "children": { "description": "The children of the folder. If lazy loading is enabled, this will be `null`.", "type": "array", "items": { "properties": { "label": { "description": "The label of the folder.", "type": "string" }, "id": { "description": "The id of the folder. It must be sent to the backend when the user selects the folder.", "type": "string" }, "children": { "description": "More children folders.", "type": "array", "items": {}, "example": null, "nullable": true } }, "type": "object" }, "nullable": true } }, "type": "object" }, "example": [ { "label": "Marketing", "children": [ { "label": "Social Media" } ] } ] }, "lazy_loading": { "title": "Lazy Loading", "description": "Determines if lazy loading is enabled. If yes, more data can be fetched with the more endpoint. Especially relevant for folder tree fields.", "type": "boolean", "example": false }, "helptexts": { "title": "Helptexts", "description": "Additional helptexts for the integration. That help the user to understand what the integration is about. The text is provided in different languages. If the requested language is not provided, use 'en' as fallback. The string itself is markdown.", "properties": { "en": { "type": "string", "example": "This is a example help text which is not very helpful. The real help text should be more helpful." }, "de": { "type": "string", "example": "Dieser Hilfetext ist nicht sonderlich hilfreich. Der richtige Hilfetext sollte hilfreicher sein." } }, "type": "object" } }, "type": "object" }, "Integration": { "title": "Integration", "description": "An object representing an integration.", "properties": { "id": { "title": "ID", "description": "The ID of the integration.", "type": "string", "example": "aws_s3" }, "name": { "title": "Name", "description": "The name of the integration. It is not translated because most of the time it is a brand name.", "type": "string", "example": "AWS S3" }, "tags": { "title": "Tags", "description": "Tags are additional keywords used for searching.", "type": "array", "items": { "type": "string" }, "example": [ "amazon", "simple storage services" ] }, "logo": { "title": "Logo", "description": "The logo of the integration. It is a data URI with a base64 encoded string. Most of the time it is a SVG image, but PNG and JPG are also allowed.", "type": "string", "example": "data:image/svg;base64,iVBORw0KGgoAA.....hEUgAAABAAAAAQCAY=" }, "helptexts": { "title": "Helptexts", "description": "Additional helptexts for the integration. That helps the user to understand what the integration is about. The text is provided in different languages. If the requested language is not provided, use `en` as fallback. The string itself is markdown.", "properties": { "en": { "type": "string", "example": "This is a example help text which is not very helpful. The real help text should be more helpful." }, "de": { "type": "string", "example": "Dieser Hilfetext ist nicht sonderlich hilfreich. Der richtige Hilfetext sollte hilfreicher sein." } }, "type": "object" }, "existingConnectionsCount": { "title": "Number of existing connections", "description": "The number of existing connections to this integration. This is useful to show the user how often they already connected this integration. If the user already connected the integration, they can see the existing connections and can manage them. The counter does not include _incomplete_ connections.", "type": "number", "example": 3 }, "fields": { "description": "The fields of the integration. The fields are used to authenticate the user and to provide additional information for the integration.", "type": "array", "items": { "$ref": "#/components/schemas/Field" } } }, "type": "object" }, "ListIntegrations": { "$ref": "#/components/schemas/Integration" }, "Token": { "title": "Token", "description": "Object that represent the token details.", "properties": { "token": { "title": "Token", "description": "The JWT token that is used to authenticate the user (identity) in the frontend UI.", "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }, "expires_at": { "title": "Expires at", "description": "The date and time when the token expires. This is also included in the JWT token itself.", "type": "string", "format": "date-time", "example": "2019-02-01T03:45:27+00:00" } }, "type": "object" }, "VerifyToken": { "title": "Verify Token Response", "description": "Verify token response including information for the frontend UI.", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "redirect": { "properties": { "url": { "description": "The URL where the user should be redirected after going through the fetchdocs process.", "type": "string", "example": "https://www.example.com/return-url" } }, "type": "object" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/Page" } } }, "type": "object" }, "TransactionBatchStatus": { "title": "Transaction Batch Status", "description": "An object including the requested transaction UUIDs and their status. If a transaction does not exist or does not belong to the authenticated environment, it will not be included in the response. **The following UUIDs are examples.**", "properties": { "3598b23c-31db-4be9-9e6b-6aa1d5b60335": { "title": "Transaction UUID > Status", "description": "The status of the transaction.", "type": "string", "enum": [ "pending", "new", "retry", "processing", "uploaded", "completed", "failed" ], "example": "completed" }, "3598b23c-31db-4be9-9e6b-6aa1d5b60336": { "title": "Transaction UUID > Status", "description": "The status of the transaction.", "type": "string", "enum": [ "pending", "new", "retry", "processing", "uploaded", "completed", "failed" ], "example": "completed" } }, "type": "object" }, "Transaction": { "title": "Transaction", "description": "Object that represents a transaction.", "properties": { "uuid": { "title": "Transaction UUID", "description": "The UUID of the transaction.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "status": { "title": "Status", "description": "The status of the transaction. In general, new transactions are created in the status `new` and will be processed shortly. If the connection is in status `INVALID_CREDENTIALS` the transaction will be in status `pending` and will be processed as soon as the connection is in status `ACTIVE` again.", "type": "string", "enum": [ "pending", "new", "retry", "queued", "processing", "uploaded", "completed", "failed", "virus_detected" ], "example": "new" }, "reason": { "title": "Reason", "description": "A human-readable reason accompanying a terminal status. Set to `blocked: malware detected` when a document was blocked by the antivirus scan; `null` otherwise.", "type": "string", "example": "blocked: malware detected", "nullable": true }, "external_id": { "title": "External ID", "description": "The id of the document in the source system. Can be used for duplicate detection. `null` if the source system doesn't provide an id, f.e. for documents fetched from a mailbox or downloaded from a portal.", "type": "string", "example": "3223454947", "nullable": true } }, "type": "object" }, "TransactionStatus": { "title": "Transaction Status", "description": "Object that represents the status of a transaction.", "properties": { "uuid": { "title": "Transaction UUID", "description": "The UUID of the transaction.", "type": "string", "example": "3598b23c-31db-4be9-9e6b-6aa1d5b60335" }, "status": { "title": "Status", "description": "The status of the transaction.", "type": "string", "enum": [ "new", "retry", "processing", "uploaded", "completed", "failed" ], "example": "new" }, "error": { "title": "Error message", "description": "The error message if the transaction failed. The error messages are written in English and written in a human-readable format. You can show them to the user as they are.", "type": "string", "example": "The file is too large.", "nullable": true } }, "type": "object" }, "SignedUrl": { "title": "Signed URL", "description": "Provides a signed URL", "properties": { "signed_url": { "title": "Signed URL", "description": "The signed URL", "type": "string", "example": "https://example.com?foo=bar&baz=qux&signature=1234567890" } }, "type": "object" }, "ForbiddenErrorResponseExample": { "title": "Forbidden error response", "description": "The error response is returned when the user is not authorized to perform the action. The user might not have the necessary permissions or the action is not allowed in the current state of the system.", "properties": { "error": { "description": "The error code is a machine readable code describing the error.", "type": "string", "example": "UNAUTHORIZED" }, "message": { "description": "The error message is a human readable message describing the error. It is mainly used for understanding the error by developers. It is not meant to be shown to real users.", "type": "string", "example": "This action is unauthorized." }, "suggestion": { "description": "For many errors we provide suggestions how you can resolve the error on your own.", "type": "string", "example": "You are not authorized to perform this request. Please make sure you have the correct permissions and try again." }, "trace_id": { "description": "The trace ID is a unique identifier for the request. It is used to trace the request through the system. Please provide the `trace_id` when reporting an error to our support team.", "type": "string", "example": "1b935d50c2393af77b1dc92e675876a83f92ffd6" }, "help": { "description": "This parameter provides a way to contact support. It is mainly used for developers. It is not meant to be shown to real users.", "type": "string", "example": "If you need help, email support@fetchdocs.io and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6." } }, "type": "object" }, "InternalErrorResponseExample": { "title": "Internal error response", "description": "The error response is returned when an unknown server error occurred. Unfortunately, there is nothing you can do to resolve the error on your own. Please try again later or contact support and provide the `trace_id`.", "properties": { "error": { "description": "The error code is a machine readable code describing the error.", "type": "string", "example": "UNKNOWN_SERVER_ERROR" }, "message": { "description": "The error message is a human readable message describing the error. It is mainly used for understanding the error by developers. It is not meant to be shown to real users.", "type": "string", "example": "An unknown server error occurred. Please try again later or contact support." }, "suggestion": { "description": "For many errors we provide suggestions how you can resolve the error on your own.", "type": "string", "example": "Either you didn't pass an API key or it is invalid. You can find or create a new API key in the environments section. It must be passed as X-API-Key header." }, "trace_id": { "description": "The trace ID is a unique identifier for the request. It is used to trace the request through the system. Please provide the `trace_id` when reporting an error to our support team.", "type": "string", "example": "1b935d50c2393af77b1dc92e675876a83f92ffd6" }, "help": { "description": "This parameter provides a way to contact support. It is mainly used for developers. It is not meant to be shown to real users.", "type": "string", "example": "If you need help, email support@fetchdocs.io and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6." } }, "type": "object" }, "NotAcceptableErrorResponseExample": { "title": "Not Acceptable Error Response", "properties": { "message": { "description": "Error message", "type": "string", "example": "Not Acceptable - More then one entry was found." } }, "type": "object" }, "NotFoundErrorResponseExample": { "title": "Internal error response", "description": "The error response is returned when either the resource was not found or the client is not authorized to access the resource. It can also mean that you tried to access an endpoint that does not exist.", "properties": { "error": { "description": "The error code is a machine readable code describing the error.", "type": "string", "example": "RESOURCE_NOT_FOUND" }, "message": { "description": "The error message is a human readable message describing the error. It is mainly used for understanding the error by developers. It is not meant to be shown to real users.", "type": "string", "example": "Resource not found." }, "suggestion": { "description": "For many errors we provide suggestions how you can resolve the error on your own.", "type": "string", "example": "The URL path is wrong or the resource you are looking for does not exist in our system. Please make sure the URL path is correct and resource UUID you have passed in the URL is valid." }, "trace_id": { "description": "The trace ID is a unique identifier for the request. It is used to trace the request through the system. Please provide the `trace_id` when reporting an error to our support team.", "type": "string", "example": "1b935d50c2393af77b1dc92e675876a83f92ffd6" }, "help": { "description": "This parameter provides a way to contact support. It is mainly used for developers. It is not meant to be shown to real users.", "type": "string", "example": "If you need help, email support@fetchdocs.io and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6." } }, "type": "object" }, "UnauthorizedErrorResponseExample": { "title": "Unauthorized error response", "description": "The error response is returned when the client is not authenticated. The client must provide a valid authentication key to access the resource.", "properties": { "error": { "description": "The error code is a machine readable code describing the error.", "type": "string", "example": "API_KEY_MISSING_OR_INVALID" }, "message": { "description": "The error message is a human readable message describing the error. It is mainly used for understanding the error by developers. It is not meant to be shown to real users.", "type": "string", "example": "API key is missing or invalid." }, "suggestion": { "description": "For many errors we provide suggestions how you can resolve the error on your own.", "type": "string", "example": "Either you didn't pass an API key or it is invalid. You can find or create a new API key in the environments section. It must be passed as X-API-Key header." }, "trace_id": { "description": "The trace ID is a unique identifier for the request. It is used to trace the request through the system. Please provide the `trace_id` when reporting an error to our support team.", "type": "string", "example": "1b935d50c2393af77b1dc92e675876a83f92ffd6" }, "help": { "description": "This parameter provides a way to contact support. It is mainly used for developers. It is not meant to be shown to real users.", "type": "string", "example": "If you need help, email support@fetchdocs.io and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6." } }, "type": "object" }, "ValidationErrorResponseExample": { "title": "Validation error response", "description": "The error response is returned when the client has provided invalid data in the request.", "properties": { "error": { "description": "The error code is a machine readable code describing the error.", "type": "string", "example": "VALIDATION_ERROR" }, "message": { "description": "The error message is a human readable message describing the error. It is mainly used for understanding the error by developers. It is not meant to be shown to real users.", "type": "string", "example": "The identity uuid field is required. | The return url field is required." }, "suggestion": { "description": "For many errors we provide suggestions how you can resolve the error on your own.", "type": "string", "example": "There might be some parameters are missing or the values of parameters you have passed are invalid. Please check the payload and make sure it conforms with the rules mentioned in API doc." }, "trace_id": { "description": "The trace ID is a unique identifier for the request. It is used to trace the request through the system. Please provide the `trace_id` when reporting an error to our support team.", "type": "string", "example": "1b935d50c2393af77b1dc92e675876a83f92ffd6" }, "errors": { "description": "The errors object contains a list of fields with their corresponding error messages.", "type": "object", "example": { "identity_uuid": [ "The identity uuid field is required." ], "return_url": [ "The return url field is required." ] } }, "help": { "description": "This parameter provides a way to contact support. It is mainly used for developers. It is not meant to be shown to real users.", "type": "string", "example": "If you need help, email support@fetchdocs.io and include the following Trace-ID in your message: 1b935d50c2393af77b1dc92e675876a83f92ffd6." } }, "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "API key of the environment", "name": "X-API-KEY", "in": "header" }, "TokenAuth": { "type": "apiKey", "description": "Token generated for a UI session", "name": "X-TOKEN", "in": "header" } } }, "tags": [ { "name": "Connections", "description": "Connections" }, { "name": "Identities", "description": "Identities" }, { "name": "Integration", "description": "Integration" }, { "name": "Log", "description": "Log" }, { "name": "Token", "description": "Token" }, { "name": "URL Signing", "description": "URL Signing" } ] }