Create a File

Before uploading a file, you need to create a File resource.

Once created, you can upload your file to the new File resource.

Request
Request Body schema: application/vnd.api+json
display_name
string

The name of the File you'll create.

linked_to
string

The resource ID that you want linked to the File (e.g. Merchant ID).

object

Key value pair for annotating custom meta data (e.g. order numbers).

type
string

The type of document. | Available values include:
Identity Verification

  • DRIVERS_LICENSE_FRONT
  • DRIVERS_LICENSE_BACK
  • IDENTIFICATION_CARD_FRONT
  • IDENTIFICATION_CARD_BACK
Bank account validation
  • BANK_STATEMENT
Business Verification
  • TAX_DOCUMENT
  • BUSINESS_REGISTRATION
  • BUSINESS_ADDRESS_VERIFICATION
Additional
  • OTHER
  • PCI_DOCUMENT
  • PASSPORT

Enum: "DRIVERS_LICENSE_FRONT" "DRIVERS_LICENSE_BACK" "IDENTIFICATION_CARD_FRONT" "IDENTIFICATION_CARD_BACK" "BANK_STATEMENT" "TAX_DOCUMENT" "BUSINESS_REGISTRATION" "BUSINESS_ADDRESS_VERIFICATION" "OTHER" "PCI_DOCUMENT" "PASSPORT"
Responses
200

Single File object

Response Schema: application/vnd.api+json
id
string

The ID of the File resource.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

application_id
string

The ID of the Application that the File was created under.

display_name
string

The name of the File object. If you don't provide a name, Finix will name the object with the convention: FILE_(file_id).

extension
string or null

The extension of the file.

identity_id
string or null

ID of the Identity that created the File.

linked_to
string

The resource ID the File is linked to.

linked_type
string

Autofills to Merchant.

platform_id
string

The ID of the Platform that the File was created under.

status
string

The status of the file's review. The statuses available includes:

  • REQUIRES_UPLOAD: A file still needs to be uploaded to the file object.
  • PENDING: Finix's underwriting team is still reviewing the uploaded files.
  • INVALID: The file couldn't be read.
  • UPLOADED: The file has been uploaded to the resource.

  • object

    Key value pair for annotating custom meta data (e.g. order numbers).

    type
    string

    The type of document.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    post/files
    Request samples
    Response samples
    application/vnd.api+json
    {
    • "id": "FILE_abki8bFEjq51eZ5w2pYFik",
    • "status": "REQUIRES_UPLOAD",
    • "created_at": "2022-08-16T18:50:25.770825Z",
    • "updated_at": "2022-08-16T18:50:25.807321Z",
    • "linked_type": "MERCHANT",
    • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    • "extension": null,
    • "display_name": "license_file",
    • "type": "DRIVERS_LICENSE_FRONT",
    • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
    • "application_id": "APgPDQrLD52TYvqazjHJJchM",
    • "tags": {
      • "test_key_100": "test_val_100"
      },
    • "identity_id": null
    }

    List All Files

    List all the File resources you've created.

    Request
    query Parameters
    sort
    string

    Specify key to be used for sorting the collection.

    after_cursor
    string

    Return every resource created after the cursor value.

    limit
    integer

    The numbers of items to return.

    Example: limit=10
    id
    string

    Filter by id.

    created_at.gte
    string

    Filter where created_at is after the given date.

    Example: created_at.gte=created_at.gte=2019-06-15
    created_at.lte
    string

    Filter where created_at is before the given date.

    Example: created_at.lte=created_at.lte=2019-06-15
    updated_at.gte
    string

    Filter where updated_at is after the given date.

    updated_at.lte
    string

    Filter where updated_at is before the given date.

    before_cursor
    string

    Return every resource created before the cursor value.

    Responses
    200

    List of File objects

    Response Schema: application/vnd.api+json
    object

    Details the page that's returned.

    object

    List of File objects.

    object

    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    get/files
    Request samples
    curl https://finix.sandbox-payments-api.com/files \
      -H "Content-Type: application/vnd.json+api" \
      -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
    
    Response samples
    application/vnd.api+json
    {
    • "_embedded": {
      • "files": [
        ]
      },
    • "page": {
      • "limit": 10,
      • "next_cursor": "FILE_abki8bFEjq51eZ5w2pYFik"
      }
    }

    Fetch a File

    Retrieve the details of a File resource.

    Request
    path Parameters
    file_id
    required
    string

    Your File ID.

    Responses
    200

    Single File object

    Response Schema: application/vnd.api+json
    id
    string

    The ID of the File resource.

    created_at
    string <date-time>

    Timestamp of when the object was created.

    updated_at
    string <date-time>

    Timestamp of when the object was last updated.

    application_id
    string

    The ID of the Application that the File was created under.

    display_name
    string

    The name of the File object. If you don't provide a name, Finix will name the object with the convention: FILE_(file_id).

    extension
    string or null

    The extension of the file.

    identity_id
    string or null

    ID of the Identity that created the File.

    linked_to
    string

    The resource ID the File is linked to.

    linked_type
    string

    Autofills to Merchant.

    platform_id
    string

    The ID of the Platform that the File was created under.

    status
    string

    The status of the file's review. The statuses available includes:

  • REQUIRES_UPLOAD: A file still needs to be uploaded to the file object.
  • PENDING: Finix's underwriting team is still reviewing the uploaded files.
  • INVALID: The file couldn't be read.
  • UPLOADED: The file has been uploaded to the resource.

  • object

    Key value pair for annotating custom meta data (e.g. order numbers).

    type
    string

    The type of document.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    get/files/{file_id}
    Request samples
    curl https://finix.sandbox-payments-api.com/files/FILE_abki8bFEjq51eZ5w2pYFik \
      -H "Content-Type: application/vnd.json+api" \
      -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
    
    Response samples
    application/vnd.api+json
    {
    • "id": "FILE_abki8bFEjq51eZ5w2pYFik",
    • "status": "REQUIRES_UPLOAD",
    • "created_at": "2022-08-16T18:50:25.770825Z",
    • "updated_at": "2022-08-16T18:50:25.807321Z",
    • "linked_type": "MERCHANT",
    • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    • "extension": null,
    • "display_name": "license_file",
    • "type": "DRIVERS_LICENSE_FRONT",
    • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
    • "application_id": "APgPDQrLD52TYvqazjHJJchM",
    • "tags": {
      • "test_key_100": "test_val_100"
      },
    • "identity_id": null
    }

    Upload files Directly

    Upload files directly with a multipart/form-data request.

    Request
    path Parameters
    file_id
    required
    string

    The ID of the File that was created to upload the file.

    Request Body schema: multipart/form-data
    file
    string <binary>

    Path to the file you want to upload
    (e.g. /Users/Desktop/finix_file.png).

    Responses
    200

    Single File object

    Response Schema: application/vnd.api+json
    id
    string

    The ID of the File resource.

    created_at
    string <date-time>

    Timestamp of when the object was created.

    updated_at
    string <date-time>

    Timestamp of when the object was last updated.

    application_id
    string

    The ID of the Application that the File was created under.

    display_name
    string

    The name of the File object. If you don't provide a name, Finix will name the object with the convention: FILE_(file_id).

    extension
    string or null

    The extension of the file.

    identity_id
    string or null

    ID of the Identity that created the File.

    linked_to
    string

    The resource ID the File is linked to.

    linked_type
    string

    Autofills to Merchant.

    platform_id
    string

    The ID of the Platform that the File was created under.

    status
    string

    The status of the file's review. The statuses available includes:

  • REQUIRES_UPLOAD: A file still needs to be uploaded to the file object.
  • PENDING: Finix's underwriting team is still reviewing the uploaded files.
  • INVALID: The file couldn't be read.
  • UPLOADED: The file has been uploaded to the resource.

  • object

    Key value pair for annotating custom meta data (e.g. order numbers).

    type
    string

    The type of document.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    post/files/{file_id}/upload
    Request samples
    Response samples
    application/vnd.api+json
    {
    • "id": "FILE_abki8bFEjq51eZ5w2pYFik",
    • "status": "REQUIRES_UPLOAD",
    • "created_at": "2022-08-16T18:50:25.770825Z",
    • "updated_at": "2022-08-16T18:50:25.807321Z",
    • "linked_type": "MERCHANT",
    • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    • "extension": null,
    • "display_name": "license_file",
    • "type": "DRIVERS_LICENSE_FRONT",
    • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
    • "application_id": "APgPDQrLD52TYvqazjHJJchM",
    • "tags": {
      • "test_key_100": "test_val_100"
      },
    • "identity_id": null
    }

    Download a file

    Download a file that was uploaded to a File resource.

    Request
    path Parameters
    file_id
    required
    string

    The ID of the File that was created to upload the file.

    Responses
    200

    Example response

    Response Schema: application/octet-stream
    string <binary>
    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    get/files/{file_id}/download
    Request samples
    curl https://finix.sandbox-payments-api.com/files/FILE_bJecqoRPasStGPVpvKHtgA/download \
      -H "Content-Type: application/vnd.json+api" \
      -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
    
    Response samples
    application/hal+json
    {
    • "total": 0,
    • "_embedded": {
      • "errors": [
        ]
      }
    }