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

Body
Headers

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

Body
Headers

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

Body
Headers

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

Body
Headers

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

Integrations

Peripherals

Merchant.docs

Partner.docs

Merchant.docs

Merchant.docs

Partner.docs

First Time Users

Quick Start

Transactional

Customer data

Tutorials

Response Code

Code samples

Third Party Modules

Plugins & More

Drivers

Additional Support

Documents

Documents Object

POST Text Document

GET All Documents for an Organization

GET Documents by ID

DELETE Documents

On this page

Your benefits:

What happens next?

Get Connected to our Team

Simplifying IT for a complex world.

Platform partnerships

Services

Business Challenges

Digital Transformation

Security

Automation

Gaining Efficiency

Industry Focus

Simplifying IT
for a complex world.