The attachment service is used to retrieve attachments such as drawings, chemistry files, full page images, and other non-textual files delivered by patent offices from the CLAIMS Direct data warehouse.

1 /attachment/list
- 1.1 Single UCID
  - 1.1.1 Response JSON
  - 1.1.2 Response XML
- 1.2 Multiple UCIDs
  - 1.2.1 Response JSON
  - 1.2.2 Response XML
2 /attachment/fetch
- 2.1 Request
- 2.2 Response
- 2.3 Request (with scaling and conversion)
3 /attachment/fetchall
- 3.1 Request
- 3.2 Response
4 /attachment/pdf
- 4.1 Request
- 4.2 Response
5 /attachment/abimage
- 5.1 Request
- 5.2 Response

Searching the Attachment Collection

Bulk Attachments Service (API)

/attachment/list

List all attachments associated with one or more ucids. Responses are available in JSON and XML. See Requests and Responses for more information.

Method	GET

Method	GET
Path	`/attachment/list`
Parameters		Values	Description
	@ucid	String: e.g., US-20100077592-A1	Document identifier.
	@multi	Boolean: 1\|0	Specifies an alternative response format suitable for multi-ucid input, e.g., ?ucid=US-5551212-A,EP-0700000-A2 There is a limit of 100 ucids per batch.

Single UCID

wget -O- \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/attachment/list?ucid=US-20100077592-A1'

Response JSON

{
   "status" : "success",
   "time" : "0.076931"
   "count" : 6,
   "attachments" : [
      {
         "level" : 1,
         "path" : "/EP/20001004/B1/000000/70/00/00/00360001.tif",
         "filename" : "00360001.tif",
         "media" : "image/tiff",
         "pkey" : "EP-0700000-B1-20001004",
         "size" : 22886
      },
      /* further attachment array members */
   ],
}

Response XML

<?xml version="1.0"?>
<response method="attachment/list" status="success" time="0.652126">
  <attachments>
    <attachment pkey="EP-0700000-B1-20001004"
                size="22886"
                media="image/tiff"
                path="/EP/20001004/B1/000000/70/00/00/00360001.tif"
                filename="00360001.tif" />
    <!-- further attachment elements -->
  </attachments>
</response>

Multiple UCIDs

wget -O- \
--header 'x-user:x' \
--header 'x-password:y' \
'https://cdws21.ificlaims.com/attachment/list?ucid=EP-0700000-A2,EP-0700000-B1&multi=1'

Response JSON

{
   "ucid_count" : 2,
   "status" : "success",
   "time" : "0.152457",
   "attachments" : [
      {
         "EP-0700000-A2" : {
            "count" : 7,
            "attachments" : [
               {
                  "level" : 1,
                  "path" : "/EP/19960306/A2/000000/70/00/00/EP0700000A219960306.pdf",
                  "filename" : "EP0700000A219960306.pdf",
                  "pkey" : "EP-0700000-A2-19960306",
                  "media" : "application/pdf",
                  "size" : 710278
               },
               ; etc ...
            ]
         }
      },
      {
         "EP-0700000-B1" : {
            "count" : 6,
            "attachments" : [
               {
                  "level" : 1,
                  "path" : "/EP/20001004/B1/000000/70/00/00/00360001.tif",
                  "filename" : "00360001.tif",
                  "media" : "image/tiff",
                  "pkey" : "EP-0700000-B1-20001004",
                  "size" : 22886
               },
               ; etc ...
            ]
         }
      }
   ],
}

Response XML

<?xml version="1.0"?>
<response method="attachment/list" time="0.081054" status="success">
  <attachment-listing ucid-count="1">
    <attachments ucid="EP-0700000-A2" count="7">
      <attachment filename="EP0700000A219960306.pdf" media="application/pdf" path="/EP/19960306/A2/000000/70/00/00/EP0700000A219960306.pdf" pkey="EP-0700000-A2-19960306" size="710278"/>
      <attachment filename="imgaf001.tif" media="image/tiff" path="/EP/19960306/A2/000000/70/00/00/imgaf001.tif" pkey="EP-0700000-A2-19960306" size="7365"/>
      <attachment filename="imgf0001.tif" media="image/tiff" path="/EP/19960306/A2/000000/70/00/00/imgf0001.tif" pkey="EP-0700000-A2-19960306" size="22135"/>
      <attachment filename="imgf0002.tif" media="image/tiff" path="/EP/19960306/A2/000000/70/00/00/imgf0002.tif" pkey="EP-0700000-A2-19960306" size="21904"/>
      <attachment filename="imgf0003.tif" media="image/tiff" path="/EP/19960306/A2/000000/70/00/00/imgf0003.tif" pkey="EP-0700000-A2-19960306" size="11082"/>
      <attachment filename="imgf0004.tif" media="image/tiff" path="/EP/19960306/A2/000000/70/00/00/imgf0004.tif" pkey="EP-0700000-A2-19960306" size="22929"/>
      <attachment filename="imgf0005.tif" media="image/tiff" path="/EP/19960306/A2/000000/70/00/00/imgf0005.tif" pkey="EP-0700000-A2-19960306" size="12493"/>
    </attachments>
  </attachment-listing>
</response>

In the event that the ucid has no attachments, the HTTP response code 204 No Content will be returned if the @multi attribute is not specified. Otherwise, an empty JSON attachment list with count : 0 will be returned. The returned JSON is an array containing anonymous structures. The keys to the anonymous structure, i.e., media, path, and size, correspond identically with that of the XML response. Please see below for details. The attribute @count is the total number of attachments residing in the data store for the corresponding ucid. If @count > 0, a list of attachment elements follows. The attributes are described below.

Key	Description

Key

Description

@media

Internet media type, i.e., text/xml and image/tiff. There are other types of attachments, e.g., ChemDraw, Chemical Expression, and Mathmatica but there are currently no standard internet media types and hence, this attribute will be populated with non-standard media types. The following attachments, corresponding file name extension, and internet media types are available.

File	Extension	@media
Sequence Listings	APP	application/app
ChemDraw	CDX	application/chemdraw
Graphics Interchange Format	GIF	image/gif
Initialization Files	INI	application/ini
JPEG	JPG	image/jpeg
Chemical Expression	MOL	application/chemexpres
Mathmatica	NB	application/mathmatica
Portable Document Format	PDF	application/pdf
Portable Network Graphics	PNG	image/png
PostScript	POS	application/postscript
Sequence Files	SEQ	application/seq
ST.33 Files	ST33	image/st33
Tagged Image Format	TIF(F)	image/tiff
Text Files	TXT	text/plain
Extensible Markup Language	XML	text/xml
ZIP Files	ZIP	application/zip

@path

The relative path by which the attachment can be retrieved in a subsequent call using /attachment/fetch

@size

Size, in bytes, of attachment

@filename

Name of file as stored in the attachments server

@level

Integer representation of the subscription level to which the attachment is available

1=Basic
2=Premium
3=Premium+

/attachment/fetch

Fetch an attachment associated with a ucid.

Paths may change at any time. To get the most current @path parameter, you must use attachment/list.

Method	GET

Method	GET
Path	`/attachment/fetch`
Parameters		Values	Description
	@path	String: e.g., /EP/19960306/A2/000000/70/00/00/imgaf001.tif	The path of the attachment to fetch as returned in the response to `/attachment/list`
	@scale	Boolean 1\|0	Enable image scaling.
	@scale.x	Integer (pixels)	(v3.5) Scale x to given pixels.
	@scale.y	Integer (pixels)	(v3.5) Scale y to given pixels.
	@scale.factor	Float, e.g., scale=.50 half size	(v3.5) Scale the image by a factor. This is a float value.
	@scale.type	String: min\|max	(v3.5) If both .x and .y are given, the one resulting in a larger image is used ('max'), unless you set the type parameter to 'min'.
	@scale.qtype	String: preview\|mixing\|normal	(v3.5) Type of scaling in order of speed and inverse quality, preview being fastest with least quality, normal being slowest with the best quality.
	@scale.thumbnail	Boolean: 1\|0	(v3.5) Setting this parameter creates a pre-configured thumbnail with defaults of .x=80, .y=80, and qtype=preview.
	@convert	Boolean 1\|0	(v3.5) Enable image conversion.
	@convert.to	String: tiff\|jpeg\|png	(v3.5) Convert image to given format.

Request

wget -O- \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/attachment/fetch?path=12345678/EP/19960306/A2/000000/70/00/00/imgaf001.tif'

Response

The request Accept header is irrelevant with regard to response format. In the event of a system failure involving attachment availability between calls to /attachment/list and /attachment/fetch, the HTTP response code 404 Not Found will be returned. If this rare situation arises, it is advised to call list to retrieve valid @path attributes.

Request (with scaling and conversion)

wget -O- \
--header 'x-user:x' \
--header 'x-password:y' \
'https://cdws21.ificlaims.com/attachment/fetch?path=12345678/EP/19960306/A2/000000/70/00/00/imgaf001.tif&scale=1&scale.factor=.75&convert=1&convert.to=jpeg'

/attachment/fetchall

Fetch all attachments corresponding to a particular ucid in a compressed zip package.

Method	GET

Method	GET
Path	`/attachment/fetchall`
Parameters		Values	Description
	@ucid	String: e.g., EP-0700000-B1	Document identifier
	@exclude	String: e.g., pdf,mol,cdx	(v3.8.6) Comma-separated list of file extensions to exclude from package. The following extensions can be excluded: app cdx gif ini jpg mol nb pdf png pos seq st33 tif tiff txt xml zip

Request

wget -O- \ 
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/attachment/fetchall?ucid=EP-0700000-B1'>> ./EP-0700000-B1.zip

Response

The request Accept header is irrelevant with regard to response format. In the event of a system failure involving attachment availability between calls to /attachment/list and /attachment/fetchall, the HTTP response code 404 Not Found will be returned. If this rare situation arises, it is advised to call list to retrieve valid @path attributes or be certain the ucid has attachments. Content-Type returned is application/zip.

/attachment/pdf

Fetch the PDF, if available, for a particular ucid.

Method	GET

Method	GET
Path	`/attachment/pdf`
Parameters		Values	Description
Parameters	@ucid	String: e.g., EP-0700000-B1	Document identifier

Request

wget -O- \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/attachment/pdf?ucid=US-20160000001-A1'

Response

If the request is successful, an HTTP response code of 200 along with data of type application/pdf will be returned. If no PDF file is available for the requested ucid, the HTTP response code 204 No Content will be returned.

/attachment/abimage

Fetch the front page drawing or figure, if available, for a particular ucid. If there is no front page image, the first referenced image is retrieved.

Method	GET

Method	GET
Path	`/attachment/abimage`
Parameters		Values	Description
	@ucid	String: e.g., US-20160000001-A1	Document identifier
	@scale	Boolean 1\|0	Enable image scaling.
	@scale.x	Integer (pixels)	(v3.8.6) Scale x to given pixels.
	@scale.y	Integer (pixels)	(v3.8.6) Scale y to given pixels.
	@scale.factor	Float, e.g., scale=.50 half size	(v3.8.6) Scale the image by a factor. This is a float value.
	@scale.type	String: min\|max	(v3.8.6) If both .x and .y are given, the one resulting in a larger image is used ('max'), unless you set the type parameter to 'min'.
	@scale.qtype	String: preview\|mixing\|normal	(v3.8.6) Type of scaling in order of speed and inverse quality, preview being fastest with least quality, normal being slowest with the best quality.
	@scale.thumbnail	Boolean: 1\|0	(v3.8.6) Setting this parameter creates a pre-configured thumbnail with defaults of .x=80, .y=80, and qtype=preview.
	@convert	Boolean 1\|0	(v3.8.6) Enable image conversion.
	@convert.to	String: tiff\|jpeg\|png	(v3.8.6) Convert image to given format.

Request

wget -O- \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/attachment/abimage?ucid=US-20160000001-A1'

Response

An Accept header during the request is allowed but not required. If the request is successful, an HTTP response code of 200 along with the abstract or first image will be returned. If no specific image type was requested via the Accept header, the returned data will be in the original format which will be listed in the Content-Type response header. If no images are available for the requested ucid, the HTTP response code 204 No Content will be returned.