Documents

The documents object enables merchants and partners to upload supporting documentation for applications and disputes. Documents must be under 8MB and conform to specific formats. See the documents object for more information.

Documents Object

Parameter

Description

Type

Req

document_id

A unique string used to represent a document. For example, doc_31wef05ABpV2eZvKYlo54.

string

R

resource

The object resource the document pertains to. Supported values include the following:

application
dispute
bankaccount

string

R

resource_id

The identification number of the associated resource. For example, app_109630, dsp_31wef05ABpV2eZvKYlo54, or bac_XBvmvvUAG0ur5Tl4-5eBnA.

string

R

type

The type of document. Supported values include the following:

jpeg
png
tiff
txt
bmp
pdf
wav
mp3


NOTE: Files in wav or mp3 format can only be uploaded for echeck Proof of Authorization (POA) disputes.

string

O

description

A brief description of the document (e.g., receipt or voided check). [max length = 512 characters]

string

O

size

The size of the document in bytes. The maximum file size for a document is 8MB (i.e., 8,000,000 bytes).

int

O

received_date

The date that Forte received the document.

date

O

file

The name of the document file you're uploading to Forte.

string

O

POST Text Document

				
					{{baseURI}}/organizations/org_{{organizationID}}/documents/
To successfully upload a document that supports a merchant application or dispute, your request must include a multipart/form-data content type. A multipart/form-data message contains a series of sections separated by boundary strings. Boundary strings can be any combination of letters or numbers up to 70 characters as long as the string does not appear in the request body of the message. Each instance of a boundary string must be preceded by at least two dashes (--boundarystring), while the last boundary string must be preceded and followed by two dashes (--boundarystring--).

The section of a multipart/form-data message that contains the upload file must include a Content-Disposition header that indicates whether the file should be displayed as inline or, in our case, as an attachment. You must also add a field name (i.e., file) and a default filename to the attachment by using the name="file"; filename="filename.jpg" directives within the Content-Disposition header.

In curl, POST requests to upload documents use the -F or -form command as in the following example:
				
					curl 
    -H "Authorization: Basic {encoded APIAccessID:APISecureKey string}" 
    -H "X-Forte-Auth-Organization-Id: org_300005" 
    -F document={"resource":"application","resource_id":"app_103448","description":"receipt"};type=application/json 
    -F file:@filename.jpg  
"/organizations/org_300005/documents"
This request would generate a HTTP request to Forte similar to the following:
				
					POST /api/v3/organizations/org_300005/documents HTTP/1.1
Host: sandbox.forte.net
User-Agent: curl/7.46.0
Accept: application/json; charset=utf-8
Content-Type: multipart/mixed; boundary=--abcdefghijklmnopqrstuvwxyz
Content-Length: 8469
Authorization: Basic {encoded APIAccessID:APISecureKey string} 
X-Forte-Auth-Organization-Id: org_300005
--abcdefghijklmnopqrstuvwxyz
Content-Disposition:form-data; filename="filename.jpg"
Content-Type: image/jpeg
<binary content of filename.jpg>
--abcdefghijklmnopqrstuvwxyz
Content-Type: application/json 
{"resource":"application","resource_id":"app_103448","description":"receipt"}
--abcdefghijklmnopqrstuvwxyz--
The following URI uploads the document to the Forte database. Documents must be under 8MB, must not be password protected or encrypted, and must be in one of the following formats:
  • jpeg
  • png
  • tiff
  • txt
  • bmp
  • pdf
  • wav
  • mp3
AUTHORIZATION Basic Auth
 
Username     {{apiaccessid}}
Password      {{apisecurekey}}
 
Bodyraw
 
				
					--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data

{"resource":"application","resource_id":"app_132416","description":"This is a test file."}
--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: text/plain
Content-Disposition: form-data; filename=exampleTextFile.txt


Example content of text file

--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581--

Example Request

				
					curl --location -g '{{baseURI}}/v3/organizations/org_{{organizationID}}/documents/' \
--header 'Authorization: {{authorization}}' \
--header 'Accept: application/json' \
--header 'Content-Length: 419' \
--header 'Content-Type: multipart/form-data; boundary="5ff9ef78-b4d7-4fb2-b179-1ff0b553b581"' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data '--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data

{"resource":"application","resource_id":"app_133181","description":"This is a test file."}
--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: text/plain
Content-Disposition: form-data; filename=exampleTextFile.txt


Example content of text file

--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581--
'

Example Response

Edit Content 
				
					{
  "document_id": "doc_cddf1aa1-d9a4-4da7-b7e1-66283cb94b7c",
  "resource": "application",
  "resource_id": "app_133181",
  "type": "txt",
  "file": "exampleTextFile.txt",
  "description": "This is a test file.",
  "size": 32,
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/documents/doc_cddf1aa1-d9a4-4da7-b7e1-66283cb94b7c"
  }
}
Edit Content
Headers (8)
Cache-Control

no-cache Tells all caching mechanisms from server to client whether they may cache this object. It is measured in seconds

Connection

keep-alive Options that are desired for the connection
Content-Length

376 The length of the response body in octets (8-bit bytes)

 

content-type

application/json; charset=utf-8 The mime type of this content

date

Tue, 14 Aug 2018 20:51:27 GMT The date and time that the message was sent

expires

-1 Gives the date/time after which the response is considered stale

pragma

no-cache Implementation-specific headers that may have various effects anywhere along the request-response chain.

server

A name for the server

GET All Documents for an Organization

				
					{{baseURI}}/organizations/org_{{organizationID}}/documents?filter=start_received_date+eq+'2015-01-01'+and+end_received_date+eq+'2015-01-31'

This URI returns all documents associated with an organization. To narrow your search data using specific criteria, use the following filter parameters.

  • start_received_date / end_received_date

  • type

  • resource

NOTE: All date filter parameters are time aware.

Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.

AUTHORIZATION Basic Auth
 
Username     {{apiaccessid}}
Password      {{apisecurekey}}
 
PARAMS
 
filter                   start_received_date+eq+’2018-12-07’+and+end_received_date+eq+’2018-12-12′

Example Request

				
					curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/documents?filter=start_received_date%2Beq%2B%272015-01-01%27%2Band%2Bend_received_date%2Beq%2B%272015-01-31%27' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'

Example Response

Edit Content 
				
					{
  "number_results": 2,
  "search_criteria": {
    "page_size": 50,
    "page_index": 0,
    "home_organization_id": "org_334316",
    "resource_specific": {
      "start_received_date": "2015-01-01T00:00:00",
      "end_received_date": "2015-01-31T00:00:00"
    }
  },
  "results": [
    {
      "document_id": "doc_3131dddgwef0gpV2eYlo5",
      "resource": "application",
      "resource_id": "app_456789",
      "type": "jpeg",
      "description": "receipt",
      "size": 158,
      "received_date": "2015-01-25"
    },
    {
      "document_id": "doc_3131dddgweAgpV2eYlo5",
      "resource": "dispute",
      "resource_id": "dsp_32355435-e4ae-4ff4-a91e-abd8kjjfjffffc",
      "type": "jpeg",
      "description": "voided check",
      "size": "200",
      "received_date": "2015-01-31"
    }
  ],
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/documents/?filter=start_received_date+eq+%272015-01-01%27+and+end_received_date+eq+%272015-01-31%27"
  }
}
Edit Content
Headers (12)

cache-control

no-cache

connection

keep-alive

content-type

application/json; charset=utf-8

date

Wed, 25 Oct 2017 19:32:30 GMT

expires

-1

pragma

no-cache

server

Microsoft-IIS/8.5

transfer-encoding

chunked

x-aspnet-version

4.0.30319

x-cdn

Incapsula

x-iinfo

10-21811483-21811492 NNNN CT(38 78 0) RT(1508959949807 41) q(0 0 1 1) r(3 3) U16

x-powered-by

ASP.NET

GET Documents by ID

				
					{{baseURI}}/organizations/org_{{organizationID}}/documents/doc_{{documentID}}

This URI returns the details of the document record specified in the route by the document_id parameter.

AUTHORIZATION Basic Auth
 
Username     {{apiaccessid}}
Password      {{apisecurekey}}

Example Request

				
					curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/documents/doc_{{documentID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'

Example Response

Edit Content 
				
					{
  "document_id": "doc_3131dddgwef0gpV2eYlo5",
  "resource": "application",
  "resource_id": "app_1568555",
  "type": "jpeg",
  "description": "voided check",
  "size": 458,
  "received_date": "2015-01-15",
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/documents/doc_3131dddgwef0gpV2eYlo5"
  }
}
Edit Content
Headers (13)

cache-control

no-cache

connection

keep-alive

content-type

application/json; charset=utf-8

date

Wed, 25 Oct 2017 19:43:37 GMT

expires

-1

pragma

no-cache

server

Microsoft-IIS/8.5

transfer-encoding

chunked

x-aspnet-version

4.0.30319

x-cdn

Incapsula

x-iinfo

10-21866274-21946699 NNNN CT(36 68 0) RT(1508960218699 398015) q(0 0 1 -1) r(2 2) U16

x-powered-by

ASP.NET

DELETE Documents

				
					{{baseURI}}/organizations/org_{{organizationID}}/documents/doc_{{documentID}}

This URI deletes the document record specified in the route by the document_id parameter.

AUTHORIZATION Basic Auth
 
Username     {{apiaccessid}}
Password      {{apisecurekey}}

Example Request

				
					curl --location -g --request DELETE 'https://api.forte.net/v3/organizations/org_{{organizationID}}/documents/doc_{{documentID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'

Example Response

Edit Content 
				
					{
  "document_id": "doc_3131dddgwef05AgpV2eYlo5",
  "resplete Successful."
  }
}
Edit Content
Headers (14)
access-control-allow-origin
 

*

cache-control

no-cache

connection

keep-alive

content-lenght

138

content-type

application/json; charset=utf-8

date

Wed, 25 Oct 2017 20:21:37 GMT

expires

-1

pragma

no-cache

server

Microsoft-IIS/8.5

www-authenticate

Basic realm="sandbox.forte.net"

x-aspnet-version

4.0.30319

x-cdn

Incapsula

x-iinfo

4-17944848-17985085 NNNN CT(35 74 0) RT(1508962677899 218741) q(0 0 1 -1) r(2 2) U6

x-powered-by

ASP.NET
On this page