1. REST API for Content Capture
  2. Tasks
  3. Attachments

List all Document Attachments

get

/capture/api/v1.1/documents/{docId}/attachments

This operation will return the collection of attachments, if any, of the document specified by docId.

The q parameter can be used to filter the results in this collection. The orderBy parameter provides a means to sort the collection. The totalResults parameter will return the total number of results that match the query. The other parameters, limit and offset, are used for paging of the results.

If there are no attachments of the document, or they don't match the filtering criteria, an empty collection will be returned.

Note: If the OAuth token represents an account that is a Capture Administator, the response will contain all attachments matching any specified query arguments regardless of procedure, batch, or step. If the OAuth token does not represent an account that is a Capture Administator, meaning it is just a Capture User, the response will contain the attachments of the document if it is currently in a step in in which the account has been granted explict access.

Request

Supported Media Types
Path Parameters
Query Parameters

  • The limit parameter accepts a non-negative integer and is used to control the size of the resulting attachment collection.

    Default Value: 50

  • The offset parameter accepts a non-negative integer and is used to control the start index of the attachment collection of the query.

    Default Value: 0

  • The orderBy parameter is used to control the ordering (ascending/descending) of results in the attachment collection. This parameter is optional as an attachment collection has a default sort order of updatedDate descending.

    This parameter accepts the attribute name, and can be separated by a colon (:) for which the user wants to sort the results (ascending/descending). If a sort order it not specified, it will be sorted in ascending order. Note : asc stands for ascending and desc for descending. Multiple sort orders can be separated by semicolon (;). For example, orderBy={attributeName1}:{asc/desc};{attributeName2}:{asc/desc}. Also, there can also be mulitple orderBy query parameters, and they are applied in query string parameter order.

    All the attributes of an attachment are supported in an orderBy with the exception of:

    • stateToken
    • mediaType

    Examples:

    • ?orderBy=batch.id
    • ?orderBy=documentId;updatedDate:asc
    • ?orderBy=title&orderBy=createdDate:desc
    • ?orderBy=size:asc
    • ?orderBy=type.name;size:asc

  • The q parameter accepts a query expression condition that matches the attribute values of the attachment, and is used for filtering results in collection. The value of the parameter can be a simple expression in the form of {attribute name} {condition operator} {attribute value}, or it can muliple expressions grouped and combined with logical operators.

    The following conditional operators are supported:

    • eq - Equals
    • ne - Not Equals
    • lt - Less Than
    • gt - Greater Than
    • le - Less Than or Equal to
    • ge - Greater Than or Equal to

    Only the conditional operators eq and ne can be used with string attributes; and, string attributes must be enclosed in quote characters ("). Likewise, boolean data types can only use the conditional operators eq and ne. All conditional operators can be used with other attribute data types.

    Date/time attributes must have their value represented as a string in ISO-8601 Date Time format, governed by RFC 3339. For example, "2021-04-12" or "2021-04-15T04:27:15-06:00". Even though the values are in a string format, they will support numerical type operators, such as lt and gt.

    Conditional expressions can be joined by the logical operators of and or or. And, can also be grouped using parentheses (). For example: (({expression}) and ({expression})). This forms more complex filters.

    Multiple q query parameters are supported, and imply the and logical operator.

    All simple attributes of an attachment are supported in a q expression with the exception of:

    • stateToken
    • mediaType

    Child resource attributes, such as batch.id and type.name, are also supported.

    Examples:

    • ?q=(step.id eq "06ed7cb1-6b1b-4828-b4ba-c8ab31a45903" and createdDate ge "2021-05-01")
    • ?q=(step.id eq "06ed7cb1-6b1b-4828-b4ba-c8ab31a45903")&q=(createdDate ge "2021-05-01")
    • ?q=(type.name eq "Example Attachment Type") and (size lt 50000)
    • ?q=(updatedDate ge "2021-05-26")
    • ?q=(batch.id eq "636") or (batch.id eq "637")

  • The totalResults parameter accepts a boolean flag. If specified as true, then the returned result will include the total number of attachments in the query.

    Default Value: false
Back to Top

Response

Supported Media Types

200 Response

A list of all the attachments for the document specified by docId.

Body ()
Root Schema : Attachment Collection
Type: object
Title: Attachment Collection

This represents a collection of Attachment objects.

Show Source
Nested Schema : items
Type: array

The array of Attachment objects.

This will in the order specified by orderBy, or the default sort order of descending by updatedDate if orderBy was not used.

Show Source
  • Attachment
    Title: Attachment

    An Attachment in Capture is a file that contains auxiliary content for a Document. In essence, its structure is very similar to that of a Document; however, there are no metadata fields.

Nested Schema : Attachment
Type: object
Title: Attachment

An Attachment in Capture is a file that contains auxiliary content for a Document. In essence, its structure is very similar to that of a Document; however, there are no metadata fields.

Show Source
Nested Schema : batch
Type: object

The Capture Batch that contains this attachment's parent document.

Match All
Show Source
  • Capture Batch
    Title: Capture Batch

    A collection of documents in Capture that represent a unit of work in a procedure.

Nested Schema : createdBy
Type: object

The user that created the attachment.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : step
Type: object

The current processing step, if any, this attachment's parent document is undergoing.

Match All
Show Source
Nested Schema : type
Type: object

The attachment type that has been assigned to this attachment.

Match All
Show Source
  • Attachment Type
    Title: Attachment Type

    An Attachment Type can be used to categorize, and provides process filtering, of attachents of documents.

Nested Schema : updatedBy
Type: object

The last user that updated the attachment.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : Capture Batch
Type: object
Title: Capture Batch

A collection of documents in Capture that represent a unit of work in a procedure.

Show Source
  • createdBy

    The user that created the batch.

  • This identifies when the batch was created. The date/time in ISO-8601 Date Time format (yyyy-MM-dd'T'HH:mm:ss.SSSZ) UTC, governed by RFC 3339.

  • The current error message of the batch, if any.

    If the batch is in the ERROR state, this will contain the error message detailing why the batch failed processing. This message will remain until the batch re-enters processing.

  • The unique identifier of the batch.

  • links
  • lock

    If the batch is locked (by a user creating/editing the batch or if Capture is currently processing the batch), this object will contain information about the lock. The state of the batch determines if this object exists.

  • The name given to the batch.

    When Capture creates a batch, the name is some defined prefix and a sequence number. For example, inv_4781

  • User supplied general notes associated with a batch.

  • Minimum Value: 0
    Maximum Value: 10
    Default Value: 0

    A user specified priority of the batch.

    This value is used prioritize the batch for a user's attention. Its used to filter and sort batches for viewing in the client.

  • procedure

    The Capture Procedure associated with this batch.

  • Default Value: READY

    The current state of the batch.

    • READY - The standard resting state of a batch. It is available to be locked by a client.
    • LOCKED - The batch is locked by a client for editing, such as adding/removing documents and setting metadata field values.
    • ERROR - An error occurred during processing. It is available to be locked by a client for edits to correct processing errors.
    • PROCESSING - Capture is presently processing the batch. The batch is in one of the jobs defined in the Capture procedure.

  • The current status assigned to the batch.

    The status values are defined in the procedure and can be assigned during batch creation, and during transitions between processing jobs.

  • updatedBy

    The last user that updated the batch. This can be the Capture system.

  • This identifies when the last time the batch was updated. The date/time in ISO-8601 Date Time format (yyyy-MM-dd'T'HH:mm:ss.SSSZ) UTC, governed by RFC 3339.

Nested Schema : createdBy
Type: object

The user that created the batch.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : lock
Type: object

If the batch is locked (by a user creating/editing the batch or if Capture is currently processing the batch), this object will contain information about the lock. The state of the batch determines if this object exists.

Show Source
Nested Schema : procedure
Type: object

The Capture Procedure associated with this batch.

Match All
Show Source
Nested Schema : updatedBy
Type: object

The last user that updated the batch. This can be the Capture system.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : User Information
Type: object
Title: User Information

This object contains information about a given user of Capture.

Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Show Source
Nested Schema : lockedBy
Type: object

If the batch is locked within a Capture Client instance, this attribute will contain the user that locked the batch.

Match All
Show Source
  • User Information
    Title: User Information

    This object contains information about a given user of Capture.

    Models use this object to denote some relation between a user and some other object. For instance, a model of the API may define the attribute updatedBy that is a user object. This indicates it was last updated by that given user.

Nested Schema : step
Type: object

If Capture is currently processing the batch, this object will contain current processing step the batch is undergoing.

Match All
Show Source
Nested Schema : Procedure Step
Type: object
Title: Procedure Step

A step in a procedure flow.

Show Source

  • The unique identifier of the step within the procedure.

  • The name given to the step when created. For instance, the name of the processing job or commit profile.

  • The type of step. Some example include: External Processor, TIFF Conversion Processor, Asset Lookup Processor, etc.

Nested Schema : Capture Procedure
Type: object
Title: Capture Procedure

A Capture Procedure defines metadata and procesing steps of a flow.

Show Source
Nested Schema : Attachment Type
Type: object
Title: Attachment Type

An Attachment Type can be used to categorize, and provides process filtering, of attachents of documents.

Show Source

400 Response

Bad Request

The request could not be processed because it contains missing or invalid information, such as a validation error on an input field or a missing required value. The response will be an Error Detail object.

404 Response

Not Found

The request includes a resource URI that does not exist. The response will be an Error Detail object.

500 Response

Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request. The response will be an Error Detail object.

Back to Top

Examples

Example 1:

The following example shows how to list all document attachments.

curl -X GET -H 'Accept: application/json' 'https://host:port/content/capture/api/v1/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1/attachments'

This gets a list of all the attachments for the document with the ID of 'dcf65d45-4f53-4f82-998c-5e189de1b6a1' and the document has no attachments.

Response Body

{
   "limit": 0,
   "count": 0,
   "hasMore": false,
   "offset": 0,
   "items": []
 }

Example 2:

curl -X GET -H 'Accept: application/json' 'https://host:port/content/capture/api/v1/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1/attachments'

This gets a list of all the attachments for the document with the ID of 'dcf65d45-4f53-4f82-998c-5e189de1b6a1' and the document has attachments.

Response Body

{
   "limit": 1,
   "count": 1,
   "hasMore": false,
   "offset": 0,
   "items": [
               {
                 "id": "b22046ce-2c30-49b3-b734-25f62dea5403",
                 "documentId": "dcf65d45-4f53-4f82-998c-5e189de1b6a1",
                 "title": "InvoiceNote1.txt",
                 "batch": {
                            "id": "864",
                            "name": "ep_53"
                        },
                 "step": {
                            "id": "a82321c2-f288-4545-8795-e3c0f035f7ba",
                            "name": "Find Invoice Date",
                            "type": "External Processor"
                        },
                 "type": {
                            "id": "1d3340ca-3fcb-43f7-9304-89cfedb1ac69",
                            "name": "Invoice Notes"
                        },
                 "stateToken": "62a90ec2b7aa4915c04fd271dfb72a1",
                 "mediaType": "text/plain",
                 "sourceName": "notes.txt",
                 "size": 4875,
                 "createdBy": {
                            "name": "ssvrint.mtadmin"
                            },
                 "createdDate": "2021-01-19T20:05:14.215Z",
                 "updatedBy": {
                            "name": "ssvrint.mtadmin"
                            },
                 "updatedDate": "2021-01-19T20:05:14.215Z",
                 "links": [
                            {
                             "rel": "canonical",
                             "href": "http://server.example.com/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1/attachments/b22046ce-2c30-49b3-b734-25f62dea5403",
                             "method": "GET",
                             "mediaType": "application/json"
                            },
                            {
                              "rel": "urn:oce:capture:attachment-content",
                              "href": "http://server.example.com/documents/dcf65d45-4f53-4f82-998c-5e189de1b6a1/attachments/b22046ce-2c30-49b3-b734-25f62dea5403/content",
                              "method": "GET",
                              "mediaType": "text/plain"
                            }
                        ]
                    }
                ]
            }
        }
Back to Top