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/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 or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

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" … 6 more
Responses
200

Single File object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/files
Request samples 
curl "https://finix.sandbox-payments-api.com/files" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '
  {
    "display_name": "My Drivers License",
    "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    "tags": {
      "key_1": "value_1"
    },
    "type": "DRIVERS_LICENSE_FRONT"
  }'
Response samples
application/json
{
  • "id": "FILE_abki8bFEjq51eZ5w2pYFik",
  • "created_at": "2022-08-16T18:50:25.770825Z",
  • "updated_at": "2022-08-16T18:50:25.807321Z",
  • "application_id": "APgPDQrLD52TYvqazjHJJchM",
  • "display_name": "license_file",
  • "extension": null,
  • "identity_id": null,
  • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
  • "linked_type": "MERCHANT",
  • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
  • "status": "REQUIRES_UPLOAD",
  • "tags": {
    • "test_key_100": "test_val_100"
    },
  • "type": "DRIVERS_LICENSE_FRONT"
}

List All Files

Retrieve a list of previously created files.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request
query Parameters
after_cursor
string

Return every resource created after the cursor value.

Example: after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
limit
integer

The numbers of items to return.

Example: limit=10
id
string

Filter by id.

created_at.gte
string <date-time>

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time>

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
updated_at.gte
string <date-time>

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23
updated_at.lte
string <date-time>

Filter where updated_at is before the given date.

Example: updated_at.lte=2023-01-21T10:17:22
before_cursor
string

Return every resource created before the cursor value.

Example: before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
Responses
200

List of File objects

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 "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/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.

header Parameters
Accept
string
Default: application/hal+json
Responses
200

Single File object

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 "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
{
  • "id": "FILE_abki8bFEjq51eZ5w2pYFik",
  • "created_at": "2022-08-16T18:50:25.770825Z",
  • "updated_at": "2022-08-16T18:50:25.807321Z",
  • "application_id": "APgPDQrLD52TYvqazjHJJchM",
  • "display_name": "license_file",
  • "extension": null,
  • "identity_id": null,
  • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
  • "linked_type": "MERCHANT",
  • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
  • "status": "REQUIRES_UPLOAD",
  • "tags": {
    • "test_key_100": "test_val_100"
    },
  • "type": "DRIVERS_LICENSE_FRONT"
}

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.

header Parameters
Accept
string
Default: application/hal+json
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

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/files/{file_id}/upload
Request samples 
curl "https://finix.sandbox-payments-api.com/files/FILE_bJecqoRPasStEPVpvKHtgA/upload" \
  -H "Content-Type: multipart/form-data" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -F file=string
Response samples
application/json
{
  • "id": "FILE_abki8bFEjq51eZ5w2pYFik",
  • "created_at": "2022-08-16T18:50:25.770825Z",
  • "updated_at": "2022-08-16T18:50:25.807321Z",
  • "application_id": "APgPDQrLD52TYvqazjHJJchM",
  • "display_name": "license_file",
  • "extension": null,
  • "identity_id": null,
  • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
  • "linked_type": "MERCHANT",
  • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
  • "status": "REQUIRES_UPLOAD",
  • "tags": {
    • "test_key_100": "test_val_100"
    },
  • "type": "DRIVERS_LICENSE_FRONT"
}

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.

query Parameters
stream
string

Stream the contents of the File so it's displayed inline in the user's web browser.

Enum: "true" "false"
header Parameters
Accept
string
Default: application/hal+json
Responses
200

Example response

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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/octet-stream
{}