openapi: 3.1.0 servers: - description: Production url: 'https://api.codat.io' info: title: Files API description: |- > ### New to Codat? > > Our Files API reference is relevant only to our existing clients. > Please reach out to your Codat contact so that we can find the right product for you. An API for uploading and downloading files from 'File Upload' Integrations. The Accounting file upload, Banking file upload, and Business documents file upload integrations provide simple file upload functionality. ## Endpoints | Endpoints | Description | | :- |:- | | Files | Endpoints to manage uploaded files. | [Read more...](https://docs.codat.io/other/file-upload) [See our OpenAPI spec](https://github.com/codatio/oas) version: 3.0.0 contact: name: Codat email: support@codat.io termsOfService: 'https://www.codat.io/legals/' security: - auth_header: [] x-speakeasy-retries: strategy: backoff backoff: initialInterval: 500 maxInterval: 60000 maxElapsedTime: 3600000 exponent: 1.5 statusCodes: - 408 - 429 - 5XX retryConnectionErrors: true tags: - name: Files description: Endpoints to manage uploaded files. paths: '/companies/{companyId}/connections/{connectionId}/files': parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/connectionId' post: tags: - Files summary: Upload files for a company responses: '200': description: Success '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/FileUpload' description: |- The *Upload files* endpoint uploads multiple files provided by the SMB to Codat. This may include personal identity documents, pitch decks, contracts, or files with accounting and banking data. Uploaded files must meet the following requirements: - Up to 20 files can be uploaded at a time. - PDF, XLS, XLSX, XLSB, CSV, DOC, DOCX, PPT, PPTX, JPEG, JPG, and PNG files can be uploaded. - Each file can be up to 10MB in size. operationId: upload-files '/companies/{companyId}/files': parameters: - $ref: '#/components/parameters/companyId' get: tags: - Files summary: List all files uploaded by a company responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Files' examples: {} '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' description: "\uFEFFThe *List files* endpoint returns a list of all files uploaded to Codat by the SMB. " operationId: list-files '/companies/{companyId}/files/download': parameters: - $ref: '#/components/parameters/companyId' get: tags: - Files summary: Download all files for a company parameters: - name: date in: query schema: $ref: '#/components/schemas/DateTime' description: Only download files uploaded on this date. responses: '200': description: Success content: application/octet-stream: x-speakeasy-usage-example: true schema: title: Data type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Payment-Required' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Not-Found' '429': $ref: '#/components/responses/Too-Many-Requests' '500': $ref: '#/components/responses/Internal-Server-Error' '503': $ref: '#/components/responses/Service-Unavailable' description: The *Download files* endpoint downloads all files that have been uploaded by to SMB to Codat. A `date` may be specified to download any files uploaded on the date provided. operationId: download-files components: schemas: DateTime: title: Date time type: string examples: - 2022-10-23T00:00:00.000Z - 2022-10-23T00:00:00.000Z description: |- In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example: ``` 2020-10-08T22:40:50Z 2021-01-01T00:00:00 ``` When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information: - Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z` - Unqualified local time: `2021-11-15T01:00:00` - UTC time offsets: `2021-11-15T01:00:00-05:00` > Time zones > > Not all dates from Codat will contain information about time zones. > Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced. File: title: File type: object properties: fileName: type: string nullable: true description: The file's name. displayName: type: string nullable: true description: An optional display name for the file. sourceType: type: string nullable: true description: The source of the file uploaded. uploaded: $ref: '#/components/schemas/DateTime' additionalProperties: false Files: title: Files type: array items: $ref: '#/components/schemas/File' FileUpload: title: Attachment upload type: object x-internal: true required: - file properties: file: $ref: '#/components/schemas/FileUpload/definitions/codatFile' definitions: codatFile: type: string description: The file to be uploaded as an attachment. format: binary parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid example: 8a210b68-6988-11ed-a1eb-0242ac120002 description: Unique identifier for your SMB in Codat. description: Unique identifier for a company. connectionId: name: connectionId in: path required: true schema: type: string format: uuid example: 2e9d2c44-f675-40ba-8049-353bfcb5e171 description: Unique identifier for a company's data connection. description: Unique identifier for a connection. responses: BadRequest: description: The request made is not valid. content: application/json: schema: $ref: '#/components/responses/Forbidden/content/application~1json/schema' examples: Malformed query: value: statusCode: 400 service: PublicApi error: Error processing request - not valid. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Unauthorized: description: Your API request was not properly authorized. content: application/json: schema: $ref: '#/components/responses/Forbidden/content/application~1json/schema' examples: Unauthorized: value: statusCode: 401 service: PublicApi error: Unauthorized correlationId: 7eb40d6b415d7bcd99ce658268284056 canBeRetried: Unknown detailedErrorCode: 0 Payment-Required: description: | An account limit has been exceeded. The type of limit is described in the error property: - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io. content: application/json: schema: $ref: '#/components/responses/Forbidden/content/application~1json/schema' examples: Conflict: value: statusCode: 429 service: PublicApi error: You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Forbidden: description: You are using an outdated API key or a key not associated with that resource. content: application/json: schema: title: Error message type: object x-internal: true properties: statusCode: type: integer description: The HTTP status code returned by the error. service: type: string description: Codat's service the returned the error. error: type: string description: A brief description of the error. correlationId: type: string description: Unique identifier used to propagate to all downstream services and determine the source of the error. validation: $ref: '#/components/responses/Forbidden/content/application~1json/schema/definitions/errorValidation' canBeRetried: type: string description: '`True` if the error occurred transiently and can be retried.' detailedErrorCode: type: integer description: Machine readable error code used to automate processes based on the code returned. definitions: errorValidation: title: Validation error type: object nullable: true description: 'A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.' properties: errors: type: array nullable: true items: $ref: '#/components/responses/Forbidden/content/application~1json/schema/definitions/errorValidationItem' warnings: type: array nullable: true items: $ref: '#/components/responses/Forbidden/content/application~1json/schema/definitions/errorValidationItem' errorValidationItem: title: Validation error item type: object properties: itemId: type: string nullable: true description: Unique identifier for a validation item. message: type: string nullable: true description: A message outlining validation item's issue. validatorName: type: string nullable: true description: Name of validator. examples: Conflict: value: statusCode: 403 service: PublicApi error: You are using an outdated API key or a key not associated with that resource. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Not-Found: description: |- One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted. content: application/json: schema: $ref: '#/components/responses/Forbidden/content/application~1json/schema' examples: Data connection not found: value: statusCode: 404 service: PublicApi error: Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found correlationId: 8fa2b5f4794970a4ee73758f612e8df0 canBeRetried: Unknown detailedErrorCode: 0 Company not found: value: statusCode: 404 service: ClientsApi error: No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 No data available: value: statusCode: 404 service: PublicApi error: No data available for accounts for ID e5889b459f544926ac5b8e6756df2s correlationId: 0a40c2f31fc8f992fb88b0853e4166f3 canBeRetried: Unknown detailedErrorCode: 0 Too-Many-Requests: description: Too many requests were made in a given amount of time. Wait a short period and then try again. content: application/json: schema: $ref: '#/components/responses/Forbidden/content/application~1json/schema' examples: Conflict: value: statusCode: 429 service: PublicApi error: You have made too many requests in a given amount of time; please retry later. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Internal-Server-Error: description: There is a problem with our server. Please try again later. content: application/json: schema: $ref: '#/components/responses/Forbidden/content/application~1json/schema' examples: Conflict: value: statusCode: 500 service: PublicApi error: There is a problem with our server. Please try again later. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 Service-Unavailable: description: The Codat API is temporarily offline for maintenance. Please try again later. content: application/json: schema: $ref: '#/components/responses/Forbidden/content/application~1json/schema' examples: Conflict: value: statusCode: 500 service: PublicApi error: The Codat API is temporarily offline for maintenance. Please try again later. correlationId: bc997528a9d7abb9161ef45f05d38599 canBeRetried: Unknown detailedErrorCode: 0 securitySchemes: auth_header: name: Authorization description: 'The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/accounting-api#/schemas/apiKeys) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/codat-api#/api-keys/api-keys-list), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.' type: apiKey in: header x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)