This object represents files hosted on Stripe's servers. You can upload files with the create file request (for example, when uploading dispute evidence). Stripe also creates files independently (for example, the results of a Sigma scheduled query).
openapi: 3.0.0
info:
title: Stripe Files API
description: >-
This object represents files hosted on Stripe's servers. You can upload
files with the create file request (for example, when uploading dispute
evidence). Stripe also creates files independently (for example, the results
of a Sigma scheduled query).
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/files:
get:
description: >-
<p>Returns a list of the files that your account has access to. Stripe
sorts and returns the files by their creation dates, placing the most
recently created files at the top.</p>
operationId: getFiles
parameters:
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
Filter queries by the file purpose. If you don't provide a purpose,
the queries return unfiltered files.
in: query
name: purpose
required: false
schema:
enum:
- account_requirement
- additional_verification
- business_icon
- business_logo
- customer_signature
- dispute_evidence
- document_provider_identity_document
- finance_report_run
- identity_document
- identity_document_downloadable
- pci_document
- selfie
- sigma_scheduled_query
- tax_document_user_upload
- terminal_reader_splashscreen
maxLength: 5000
type: string
x-stripeBypassValidation: true
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetFilesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/FileResourceFileList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Files
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Files
- Get
post:
description: >-
<p>To upload a file to Stripe, you need to send a request of type
<code>multipart/form-data</code>. Include the file you want to upload in
the request, and the parameters for creating a file.</p>
<p>All of Stripe’s officially supported Client libraries support sending
<code>multipart/form-data</code>.</p>
operationId: postFiles
requestBody:
content:
multipart/form-data:
encoding:
expand:
explode: true
style: deepObject
file_link_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostFilesRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/file'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
servers:
- url: https://files.stripe.com/
summary: Stripe Post Files
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Files
- Post
/v1/files/{file}:
get:
description: >-
<p>Retrieves the details of an existing file object. After you supply a
unique file ID, Stripe returns the corresponding file object. Learn how
to <a href="/docs/file-upload#download-file-contents">access file
contents</a>.</p>
operationId: getFilesFile
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: file
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetFilesFileRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/file'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Files File
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Files
- Get
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
file:
description: >-
This object represents files hosted on Stripe's servers. You can upload
files with the [create file](https://stripe.com/docs/api#create_file)
request
(for example, when uploading dispute evidence). Stripe also
creates files independently (for example, the results of a [Sigma
scheduled
query](#scheduled_queries)).
Related guide: [File upload guide](https://stripe.com/docs/file-upload)
properties:
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
expires_at:
description: The file expires and isn't available at this time in epoch seconds.
format: unix-time
nullable: true
type: integer
filename:
description: The suitable name for saving the file to a filesystem.
maxLength: 5000
nullable: true
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
links:
description: >-
A list of [file links](https://stripe.com/docs/api#file_links) that
point at this file.
nullable: true
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/file_link'
type: array
has_more:
description: >-
True if this list has another page of items after this one that
can be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/file_links
type: string
required:
- data
- has_more
- object
- url
title: FileResourceFileLinkList
type: object
x-expandableFields:
- data
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- file
type: string
purpose:
description: >-
The [purpose](https://stripe.com/docs/file-upload#uploading-a-file)
of the uploaded file.
enum:
- account_requirement
- additional_verification
- business_icon
- business_logo
- customer_signature
- dispute_evidence
- document_provider_identity_document
- finance_report_run
- identity_document
- identity_document_downloadable
- pci_document
- selfie
- sigma_scheduled_query
- tax_document_user_upload
- terminal_reader_splashscreen
type: string
x-stripeBypassValidation: true
size:
description: The size of the file object in bytes.
type: integer
title:
description: A suitable title for the document.
maxLength: 5000
nullable: true
type: string
type:
description: The returned file type (for example, `csv`, `pdf`, `jpg`, or `png`).
maxLength: 5000
nullable: true
type: string
url:
description: Use your live secret API key to download the file from this URL.
maxLength: 5000
nullable: true
type: string
required:
- created
- id
- object
- purpose
- size
title: File
type: object
x-expandableFields:
- links
x-resourceId: file
GetFilesRequest:
type: object
properties: {}
FileResourceFileList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/file'
type: array
has_more:
description: >-
True if this list has another page of items after this one that can
be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/files
type: string
PostFilesRequest:
type: object
required:
- file
- purpose
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
file:
description: >-
A file to upload. Make sure that the specifications follow RFC 2388,
which defines file transfers for the `multipart/form-data` protocol.
format: binary
type: string
file_link_data:
description: >-
Optional parameters that automatically create a [file
link](https://stripe.com/docs/api#file_links) for the newly created
file.
properties:
create:
type: boolean
expires_at:
format: unix-time
type: integer
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
required:
- create
title: file_link_creation_params
type: object
purpose:
description: >-
The [purpose](https://stripe.com/docs/file-upload#uploading-a-file)
of the uploaded file.
enum:
- account_requirement
- additional_verification
- business_icon
- business_logo
- customer_signature
- dispute_evidence
- identity_document
- pci_document
- tax_document_user_upload
- terminal_reader_splashscreen
type: string
x-stripeBypassValidation: true
GetFilesFileRequest:
type: object
properties: {}
securitySchemes:
basicAuth:
description: >-
Basic HTTP authentication. Allowed headers-- Authorization: Basic
<api_key> | Authorization: Basic <base64 hash of `api_key:`>
scheme: basic
type: http
bearerAuth:
bearerFormat: auth-scheme
description: >-
Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
<api_key>
scheme: bearer
type: http
tags:
- name: Files
- name: Get
- name: Post