How To Use The Rest API End Point - File Upload

Use this end-point to upload files to the global folder. Only 1 record at a time can be posted in the request.

At present, only the files associated with Client, Debtor, or Operator records are supported.

POST Type End-Point

/api/v1/collect/app/upload

Request Body

Content-Type: multipart/form-data

This is a multipart request consisting of 2 parts.

Useful Note The JSON must be submitted before the FILE.

Part 1

This part indicates which global folder to upload the file to.

Input Type: "Text"
Input Name: "json"
Input Value:

{"{record}": {rowid},"overwrite": "{parameter}"}

Supported Records:

debtor
client
nx_ operator

Supported Overwrite Parameters:

yes: overwrites and existing file
no: does not overwrite an existing file
inc: if a file of the same name exists, it will add an incremented number to the file name

If the overwrite is set to "inc" and the file exists, then the file name returned in the response body will have an incremental number added to the file name (EX: Test.txt may become Test-2.txt).

Input Value Examples

{"debtor": 123,"overwrite": "yes"}

{"client": 456,"overwrite": "inc"}

Part 2

This part is the file upload.

Input Type: "File"
Input Name: "file"
Input Value: {File Name}

The File Name is the name returned by the application used to add the file. For example, if you used a web browser with a File Type Input, this will be automatically generated.

Useful Note Only 1 file at a time can be submitted.

Postman Example

Response Body

The response will include a status value. 200 is good. Everything else is a failure. If the response is good, then the response will include the Record Type, the File Name, and the File or Client Number.

Useful Note If you are using the Incremental Overwrite Option, make note of the File Name, as it may be different from what you submitted.

Useful Note A 404 error is returned if the Debtor or Client is not found.

{
  "recordType": "{record}",
  "fileName": "{File Name}",
  "fileNumber": {File or Client Number}
}

Code	Description
recordType	This is the table name in the database.
fileName	This is the file name that was submitted. If the overwrite was set to Yes, then it should be the same. If the overwrite was set to Inc, then it may be altered to have a sequence number.
fileNumber OR operatorID	This is the Debtor File Number or Client Number for the record that was submitted. If operatorID is returned instead of fileNumber, then this will contain the Operator ID of the record that was submitted.

Example

{
  "recordType": "debtor",
  "fileName": "Test.txt",
  "fileNumber": 12345
}

If the Overwrite is set to No, and the file exists, then you will get an HTTP status of 423 (Locked) and the body will look like the below.

{
  "cvapi-error": "Target file exists and Overwrite is set to No."
}

Was this page helpful? Do you have any comments on this document? Can we make it better? If so how may we improve this page.

Please click this link to send us your comments: helpinfo@collect.org