DocForm represents documents in the elDoc system. This REST API Reference describes available methods for the DocForm objects.

API overview

Method	API endpoint
Get document data	`GET api/v2/docForm/{id}`
Get document attachment	`GET api/v2/docForm/{id}/file/{fileId}`
Get documents in the view	`GET api/v2/docForm/view/{viewId}`
Process workflow action & update document and response	`PUT api/v2/docForm/{id}/docResponse/{respId}`
Manage document status and workflow phase	`POST api/v2/docForm/{id}/docResponse`
Create new document	`POST api/v2/docForm/form/{formName}`

Common request parameters and common headers overview

Majority of the GET methods provide support for the common parameters

Param Type Description Sample values

{id} Path param Short id (stored in the _id_web property) or full id (24 hex-character value stored in the _id property) of the DocForm F12, 59d4582e42a6273b107abcb0

{fields}

Query param

Filters fields which are to be included in the response. Fields listed in this parameter also affect fields of the embedded entities, requested using "embed" parameter

&fields=_id,_id_web,state

{embed}

Query param

Additional entities to be included in response as embedded objects:

docResponse - document response for the current user and document process phase
filesList - list of file attachments
valuesByTags - field values arranged by field tags. Table type fields always have first row which represents column names defined in the RecoForm
refByDocs - list of references to the current document from other documents (ids of DocForms where current document contained in the refdocs field)
recoData - list of recognition data models (applicable for Recognition Document only)
recoResult - recognition result identified for the given document (used only within embedded recoData)

&embed=docResponse,recoData,recoResult

All API endpoints provide support for the listed below request headers

Header name Description Sample values

eldoc-run-as

Switches Service Account security context to run on behalf of the given user account (user account has to be active). Can be provided as System ID of the user or user's email.

usr-cea83159-751f-49fc-b997-7c802794b3d4,

user@email.domain.com

Get document data

URL & Method & Description

GET api/v2/docForm/{id}

Retrieves document data.

Request:

Request (sample)

GET https://eldoc.domain.com/api/v2/docForm/{id}?fields=_id,_id_web,state,status,step,recoForm,pageIdxStart,pageIdxEnd,validated&embed=recoData,recoResult,valuesByTags,filesList

Response:

Response headers

Content-Type: application/json

Response body (sample)

{
    "_id": "5f3cd74236332879f7b3e723",
    "_id_web": "2950",
    "state": 3,
    "step": 3,
    "status": 1,
    "valuesByTags": {
        "DOC_TOPIC": "Application documents submission",
        "DATE_CREATED": "2020-08-19T07:39:46Z"
    },
    "filesList": [
        {
            "id": "5f3cd74236332879f7b3e729",
            "fileName": "application_multi_doc.pdf"
        }
    ],
    "recoData": [
        {
            "_id": "5f3cd7b436332879f7b3e7d1",
            "pageIdxEnd": 0,
            "pageIdxStart": 0,
            "validated": false,
            "recoForm": {
                "form": null,
                "id": "5f3caa5680dd6b2c3b7898c2",
                "name": "Transcript_v1"
            },
            "valuesByTags": {
                "DOC_TYPE": "Advanced",
                "GRADES": [
                    ["Subject eng", "Subject grade"],
                    ["GEOGRAPHY ", "E(e)"]
                ],
                "YEAR": "2012"
            },
            "recoResult": {
                "recoForm": {
                    "form": null,
                    "id": "5f3caa5680dd6b2c3b7898c2",
                    "name": "Transcript_v1"
                },
                "recoFormConfidence": 100.0
            }
        },
        {...}
    ]
}

Response body description:

Property

Type

Description

valuesByTags

Object

Document level fields arranged by their tags. During the manual validation step these values can be altered by user.

filesList

Array

Document level file-attachments

recoData

Array

For the Recognition Documents "recoData" field contains recognition related data. In case several RecoForms were identified in the file-attachment during IDP - all those results will be stored as entries of the "recoData" field

See RecoData data model description.

Get document attachment

URL & Method & Description

GET api/v2/docForm/{id}/file/{fileId}

Retrieves document attachment file.

Request:

Request (sample)

GET https://eldoc.domain.com/api/v2/docForm/{id}/file/{fileId}

Param	Type	Description	Sample values (comma separated)
`{fileId}`	Path param	Full id (24 hex-character) of the file. Retrieved using query with param: `fields=filesList`	5e60c3e47b827239691c6dea

Response:

Response headers

Content-Type: application/octet-stream
Content-Disposition: attachment; filename*=UTF-8''attachment_file_name.ext
Content-Length: 0

Response body (sample)

// Binary file content

Get documents in the view

URL & Method & Description

GET api/v2/docForm/view/{viewId}

Retrieves documents available for the user in the specified view (documents folder / documents category).

Request:

Request (sample)

GET https://eldoc.domain.com/api/v2/docForm/view/{viewId}

Param	Type	Description	Sample values (comma separated)
`{viewId}`	Path param	Name of the view. Currently supported views: `inbox` - documents in inbox of querying service account `mydocs` - documents created by querying service account or by querying service account on behalf of different user `repository` - documents placed in repository and accessible by service account `archive` - documents placed in archive and accessible by service account `all` - all documents which are accessible by service account	viewId=inbox; viewId=mydocs; viewId=all
`{first}`	Query param	First document index to be retrieved. First request usually starts from index 0. Default value is 0. Allowed range [0, 2147483646]	first=0; first=50
`{pageSize}`	Query param	Number of documents to be retrieved per request. Default value is 10. Allowed range [1, 100]	pageSize=1; pageSize=10
`{state}`	Query param	Indicates document process phase to be queried. Default value is not set, Allowed range [0, 100]	state=0; state=1; state=95
`{step}`	Query param	Indicates document step on the phase to be queried. Default value is not set, Allowed range [0, 100]	step=0; step=3
`{iteration}`	Query param	Indicates document iteration on the phase to be queried. Default value is not set, Allowed range [0, 100]	iteration=1; iteration=3
`{status}`	Query param	Indicates document status to be queried. Default value is not set, Allowed range [1, 10]	status=1; status=2
`{form}`	Query param	Indicates document form id to be queried. Supports multiple values (treated as OR-condition) separated by comma.	form=frd1; form=fd1,fd2,frd3
`{author}`	Query param	Indicates document author systemId to be queried. Supports multiple values (treated as OR-condition) separated by comma.	author=systemId1; author=systemId2,systemId3
`{tags}`	Query param	Indicates document tags to be queried. Supports multiple values (treated as AND-condition) separated by comma.	tags=tag1; tags=tag2,tag3

Response:

Response headers

Content-Type: application/json
X-Total-Count: 0

Response body (sample)

[
    {
        "_id": "59b803ba60e9ab2c6e7b7564",
        "_id_web": "C0A",
        "filesList": [
            {
                "id": "59b803ba60e9ab2c6e7b7560",
                "fileName": "DMS Solutions Overview 1.pptx"
            }
        ]
    },
    {
        "_id": "59b803ba60e9ab2c6e7b7569",
        "_id_web": "C1A",
        "filesList": [
            {
                "id": "59b803ba60e9ab2c6e7b7565",
                "fileName": "DMS Solutions Overview 2.pptx"
            }
        ]
    }
]

Process workflow action & update document and response

URL & Method & Description

PUT api/v2/docForm/{id}/docResponse/{respId}

Processes workflow action by adding respective DocResponse and may update document fields as well. This action is intended to be executed by a document workflow participant on the specific document workflow phase and stage

DocResponse generation

In order to retrieve respective {respId} execute GET request for retrieving DocForm with &embed=docResponse param. System will generate DocResponse for the current Service Account according to the document's workflow configuration for the current document phase.

Request:

Request (sample)

PUT https://eldoc.domain.com/api/v2/docForm/{id}/docResponse/{respId}

Request headers

Content-Type: application/json

Param	Type	Description	Sample values (comma separated)
`{respId}`	Path param	Full id (24 hex-character) of the DocResponse	59d4582e42a6273b107abcb0

Request body (sample)

{
    "docForm" : {
		"valuesByTags": {
		    "{TAG}": "{VALUE}"
		}
    },
    "docResponse" : {
		"taskstatus" : {taskStatus},
        "content" : "{content}"
    }
}

Request body keys:	Description	Sample values (comma separated)
`docForm`	{ "valuesByTags": { "{TAG}": "{VALUE}" }, "_tags": ["tag1", "tag2"] } `valuesByTags` - Provide values to be assigned to the document fields based on TAGs `_tags` - system field for storing document tags	{ "valuesByTags": { "TAG1": "Value 1", "TAG2_DATE": "2020-03-05T08:06:09Z" }, "_tags": ["ReportingQ3"] }
`docResponse`	{ "taskstatus": {taskStatus}, "content": "{content}" } `taskStatus` - Action to be performed with the given document (DocResponse task status). Available task statuses (document workflow response actions): 2 - Approve 3 - Approve with edits 4 - Decline 5 - Execution (follow-up) done 8 - Sign `content` - optionally document response action description can be added	{ "taskstatus": 5, "content": "Document posted successfully" }

Response:

Response Codes	Description
`200 - OK`	Document was successfully updated & processed
`422 - UNPORCESSABLE ENTITY`	Request was successfully executed but no data was updated

Manage document status and workflow phase

URL & Method & Description

POST api/v2/docForm/{id}/docResponse

Manages document status and workflow phase. This action is intended to be executed by document Initiator or another user or service account with role [elAdminDocRW(D)]

Access rights requirement

Method requires [elAdminDocsRW] role for the Service Account when document author is not a Service Account which originated the request, or execute request by setting proper runAs context via request header.

Request:

Request (sample)

POST https://eldoc.domain.com/api/v2/docForm/{id}/docResponse

Request headers

Content-Type: application/json

Request body (sample)

{
    "docResponse" : {
		"taskstatus" : {taskStatus}
    }
}

Request body keys:	Description	Sample values (comma separated)
`docResponse`	{ "taskstatus": {taskStatus} } `taskStatus` - Action to be performed on the document workflow (DocResponse task status). Available task statuses: 100 - Send document to the Approval workflow phase 101 - Suspend document workflow 102 - Resume document workflow 103 - Cancel document workflow 104 - Send document to the workflow phase repeatedly 105 - Send document to the Sign workflow phase 106 - Send document to the Execution workflow phase 107 - Send document to the Archive workflow phase 108 - Send document to the Repository workflow phase 110 - Block document 111 - Delete document (performs 2 actions: blocks document and then deletes document)	{ "taskstatus": 100 }

Response:

Response Codes	Description
`200 - OK`	Document was successfully updated & processed
`422 - UNPORCESSABLE ENTITY`	Request was successfully executed but no data was updated

Create new document

URL & Method & Description

POST api/v2/docForm/form/{formName}

Creates new document in the system.

When docResponse provided with the action to be performed on the document on creation you need to check [state] field value of the created docForm in order to confirm that it was successfully sent to the workflow.

Additionally check the X-Error response header is not present / empty (even with the 201 response code).

Request:

Request (sample)

POST https://eldoc.domain.com/api/v2/docForm/form/{formName}

Request headers

Content-Type: multipart/form-data

Param	Type	Description	Sample values (comma separated)
`{formName}`	Path param	Short id of the document form to be used for creating a new document in the system	frd1, fd1, fd5
`{allowDupl}`	Query param	Flag defines whether check for file duplication to be done (based on SHA-256 file attachments hash-sum)	true\|false (default: true - duplicates are allowed in the system)
`{idpLngs}`	Query param	IDP: parameter for selecting languages for indexing file content with OCR	eng, eng+chi_tra, eng%2Bchi_tra (default: eng)
`{idpFrpr}`	Query param	IDP: flag for forcing elDoc to pre-process file-attachment (not recommended to enable for PDF-text based files, as text content will be replaced by performing OCR)	true\|false (default: false)

Form-data body parts:	Description	Sample values (comma separated)
`docForm`	{ "valuesByTags": { "{TAG}": "{VALUE}" }, "author": "{systemId}", "_tags": ["tag1", "tag2"] } `valuesByTags` - Provide values to be assigned to the document fields based on TAGs `author` (Deprecated): SystemId value of the document author on behalf of whom the document is to be created. May contain email address of the user. To be replaced with the [`eldoc-run-as]` request header. `_tags` - system field for storing document tags	{ "valuesByTags": { "DOC_TOPIC": "Doc topic content", "DATE_CREATED": "2020-03-05T08:06:09Z" }, "author": "usr-bf7ad850-8708-493d-96a5-7c064f9b8528", "_tags": ["Report-2021"] }
`docResponse`	{ "taskstatus": {taskStatus} } `taskStatus` - Action to be performed on the newly created document (DocResponse task status). Available task statuses: 100 - Send document to the Approval workflow phase 104 - Send document to the workflow phase repeatedly 105 - Send document to the Sign workflow phase 106 - Send document to the Execution workflow phase 107 - Send document to the Archive workflow phase 108 - Send document to the Repository workflow phase	{ "taskstatus": 106 }
`files`	Files to be attached to the created document

Response:

Response Codes	Description
`201 - Created`	Document was successfully created

Response headers

Content-Type: application/json

Response body (sample)

{
    "_id": "5e60c0fed1de2b6966aebcee",
    "_id_web": "1570",
    "_meta": {
        "_created": "2020-03-05T09:06:06Z",
        "_lastmodified": "2020-03-05T09:06:11Z",
        "_rev": 5
    },
    "author": "usr-bf7ad850-8708-493d-96a5-7c064f9b8528",
    "state": 3,
    "step": 1,
    "iteration": 1,
    "status": 1,
    "formsystype": 0,
    "datecreated": "2020-03-05T08:06:09Z",
    "datedue": "",
    "...": "..."
}