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 human-readable name to use for the File (e.g., Bank Statement (January 2024)).

linked_to
required
string

The ID of the resource the File will be linked to. This can be either a Merchant ID or Identity 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. (For example, order_number: 25, item_type: produce, department: sales)
type
required
string

The type of document

Enum: "BANK_STATEMENT" "BANK_STATEMENT_ONE_MONTH" "BANK_STATEMENT_THREE_MONTHS" "BUSINESS_ADDRESS_DOCUMENT" "BUSINESS_ADDRESS_VERIFICATION" … 18 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": "Bank Statement (January 2024)",
    "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    "type": "BANK_STATEMENT"
  }'
Response samples
application/json
{
  • "id": "FILE_puUe2Fxc6PyPxZzu4HwPyy",
  • "status": "REQUIRES_UPLOAD",
  • "created_at": "2024-08-28T21:30:27.442543Z",
  • "updated_at": "2024-08-28T21:30:27.46643Z",
  • "linked_type": "MERCHANT",
  • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
  • "extension": null,
  • "display_name": "Bank Statement (January 2024)",
  • "type": "BANK_STATEMENT",
  • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
  • "application_id": "APgPDQrLD52TYvqazjHJJchM",
  • "tags": { },
  • "identity_id": "ID82tmeBrw6ithr8DjDnAdVb"
}

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_puUe2Fxc6PyPxZzu4HwPyy",
  • "status": "REQUIRES_UPLOAD",
  • "created_at": "2024-08-28T21:30:27.442543Z",
  • "updated_at": "2024-08-28T21:30:27.46643Z",
  • "linked_type": "MERCHANT",
  • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
  • "extension": null,
  • "display_name": "Bank Statement (January 2024)",
  • "type": "BANK_STATEMENT",
  • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
  • "application_id": "APgPDQrLD52TYvqazjHJJchM",
  • "tags": { },
  • "identity_id": "ID82tmeBrw6ithr8DjDnAdVb"
}

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
required
string

Path to the file 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=@/Users/Desktop/finix_file.png"
Response samples
application/json
{
  • "id": "FILE_puUe2Fxc6PyPxZzu4HwPyy",
  • "status": "REQUIRES_UPLOAD",
  • "created_at": "2024-08-28T21:30:27.442543Z",
  • "updated_at": "2024-08-28T21:30:27.46643Z",
  • "linked_type": "MERCHANT",
  • "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
  • "extension": null,
  • "display_name": "Bank Statement (January 2024)",
  • "type": "BANK_STATEMENT",
  • "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
  • "application_id": "APgPDQrLD52TYvqazjHJJchM",
  • "tags": { },
  • "identity_id": "ID82tmeBrw6ithr8DjDnAdVb"
}

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
boolean

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

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
{}