Search files (v2)

Search for a bulk file by file number or file name. At least one of fileName or fileNumber must be provided; fileNumber accepts numeric values only.

Behavior

  • When fileNumber is provided, it is used as an exact-match lookup key on its own — the search always looks up that single file number rather than combining it with fileName as a search refinement.
  • If fileName is also provided alongside fileNumber, the file returned for that fileNumber is cross-checked against the supplied fileName (trimmed, case-insensitive). A mismatch is rejected — see the 409 response.
  • When only fileName is provided (no fileNumber), the search behaves like v1: a partial, paginated match on file name, restricted to files created in the last 6 months.
  • page / limit only affect the file-name search path. A fileNumber lookup always returns at most a single record and ignores the caller-supplied page / limit values.
  • The response shape is always the paginated list envelope (pagination + data[]), including for a fileNumber lookup — data will contain 0 or 1 entries in that case, not a bare object.
  • Requires the View Bulk Files permission. Note this differs from v1's /v1/files/search, which requires the Manage Bulk Files permission.
SecurityoAuth2
Request
query Parameters
page
integer
Default: 1

What page of results should be returned? Only applies to a file-name search; ignored for a fileNumber lookup.

Example: page=1
limit
integer
Default: 10

Number of records to be included in each page. Only applies to a file-name search; ignored for a fileNumber lookup.

Example: limit=10
Request Body schema: application/json
required

Request payload for searching files. At least one of fileName or fileNumber must be provided. When fileNumber is provided it is used alone as an exact-match lookup key; fileName is only used to cross-check the result. The fileNumber field accepts only numeric values.

fileName
string

The name of the file to search for, or to cross-check against the record found for fileNumber when both are provided. At least one of fileName or fileNumber must be provided.

fileNumber
string^[0-9]+$

Number of the file to look up. Used as the sole lookup key when provided — it is not combined with fileName as a search filter. At least one of fileName or fileNumber must be provided.

Responses
200

Successfully processed request

400

Bad request

401

You are not authorized to access the resource

403

Accessing the resource you were trying to reach is forbidden

409

The file found for the given fileNumber does not match the fileName also supplied in the request.

500

Internal server error

503

Service unavailable

post/v2/files/search
Request samples
application/json
{
  • "fileName": "FEDWIRE_CSV_TEST",
  • "fileNumber": "1045"
}
Response samples
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}