Attachment API

The Attachment API provides endpoints that allow you to upload and query file attachments.

You can upload or retrieve a single file with each request.

The Attachment API respects any system limitations on uploaded files, such as maximum file size and allowed attachment types. You can control these settings using the properties com.glide.attachment.max_size, 1024MB by default, and glide.attachment.extensions.

Note: The Attachment API accepts all Content-Type values (*/*). Specify the file content type when uploading an attachment. The content type is stored with file metadata allowing other tools to correctly identify and parse the file.

The following video provides more information on the Attachment API:

Attachment API role requirements

To create attachments, the user record used to authenticate the HTTP request with ServiceNow must have any roles required to create Attachment [sys_attachment] records. It must also have any roles required to read and write records on the target table, such as the itil role to add attachments to incident records.

By default there is no single role allowing a user to add attachments. You can create a role to explicitly allow adding attachments, then assign this role to the user account being used to make the request.

Parent Topic:REST API reference

Attachment - DELETE /now/attachment/{sys_id}

Deletes a specified attachment.

URL format

Versioned URL: /api/now/v1/attachment/{sys_id}

Default URL: /api/now/attachment/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

cURL request

curl "https://instance.servicenow.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5" \
--request DELETE \
--user 'username':'password'

""

Attachment - DELETE /now/attachment/{sys_id}/attributes

Deletes all attributes for an attachment.

Attributes are deleted from the Attachment Attributes [sys_attachment_attribute] table.

URL format

Versioned URL: /api/now/{api_version}/attachment/{sys_id}/attributes

Default URL: /api/now/attachment/{sys_id}/attributes

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

cURL request

This example deletes all attributes from an attachment.

curl "https://instance.service-now.com/api/now/attachment/a3af695b0a0006871b657c200acf62e0/attributes" \
--request DELETE \
--user 'username':'password'

Response body.

""

Attachment - DELETE /now/attachment/{sys_id}/attributes/{attribute_key}

Deletes a specified attribute from an attachment.

Attributes are deleted from the Attachment Attributes [sys_attachment_attribute] table.

URL format

Versioned URL: /api/now/{api_version}/attachment/{sys_id}/attributes/{attribute_key}

Default URL: /api/now/attachment/{sys_id}/attributes/{attribute_key}

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

cURL request

This example deletes a specified attribute from an attachment.

curl "https://instance.service-now.com/api/now/attachment/a3af695b0a0006871b657c200acf62e0/attributes/example_key" \
--request DELETE \
--user 'username':'password'

Response body.

""

Attachment - GET /now/attachment

Returns the metadata for multiple attachments.

URL format

Versioned URL: api/now/v1/attachment

Default URL: api/now/attachment

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

cURL request

curl "https://instance.servicenow.com/api/now/attachment?sysparm_limit=1" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": [
    {
      "table_sys_id": "5054b6f8c0a800060056addcf551ecf8",
      "size_bytes": "462",
      "download_link": "https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file",
      "sys_updated_on": "2009-05-21 04:12:21",
      "sys_id": "615ea769c0a80166001cf5f2367302f5",
      "image_height": "",
      "sys_created_on": "2009-05-21 04:12:21",
      "file_name": "blocks.swf",
      "sys_created_by": "glide.maint",
      "compressed": "true",
      "average_image_color": "",
      "sys_updated_by": "glide.maint",
      "sys_tags": "",
      "table_name": "content_block_programmatic",
      "image_width": "",
      "sys_mod_count": "0",
      "content_type": "application/x-shockwave-flash",
      "size_compressed": "485"
    }
  ]
}

Attachment - GET /now/attachment/{sys_id}

Returns the metadata for the attachment file with a specific sys_id value.

URL format

Versioned URL: /api/now/v1/attachment/{sys_id}

Default URL: /api/now/attachment/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

cURL request

curl "https://instance.servicenow.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "table_sys_id": "5054b6f8c0a800060056addcf551ecf8",
    "size_bytes": "462",
    "download_link": "https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file",
    "sys_updated_on": "2009-05-21 04:12:21",
    "sys_id": "615ea769c0a80166001cf5f2367302f5",
    "image_height": "",
    "sys_created_on": "2009-05-21 04:12:21",
    "file_name": "blocks.swf",
    "sys_created_by": "glide.maint",
    "compressed": "true",
    "average_image_color": "",
    "sys_updated_by": "glide.maint",
    "sys_tags": "",
    "table_name": "content_block_programmatic",
    "image_width": "",
    "sys_mod_count": "0",
    "content_type": "application/x-shockwave-flash",
    "size_compressed": "485"
  }
}

Attachment - GET /now/attachment/{sys_id}/attributes

Retrieves all attributes for an attachment.

Attributes are retrieved from the Attachment Attributes [sys_attachment_attribute] table.

URL format

Versioned URL: /api/now/{api_version}/attachment/{sys_id}/attributes

Default URL: /api/now/attachment/{sys_id}/attributes

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"result": [
  {
    "key": "example_key",
    "value": "example_value"
  }
]

cURL request

This example retrieves all attributes for the specified attachment.

curl "https://instance.service-now.com/api/now/attachment/a3af695b0a0006871b657c200acf62e0/attributes" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Response body.

{
  "result": [
    {
      "key": "example_key",
      "value": "example_value"
    },
    {
      "key": "another_key",
      "value": "another_value"
    }
  ]
}

Attachment - GET /now/attachment/{sys_id}/attributes/{attribute_key}

Retrieves a specified attribute from an attachment.

Attributes are retrieved from the Attachment Attributes [sys_attachment_attribute] table.

URL format

Versioned URL: /api/now/{api_version}/attachment/{sys_id}/attributes/{attribute_key}

Default URL: /api/now/attachment/{sys_id}/attributes/{attribute_key}

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"result": { 
   "key": "String",  
   "value": "String"
}

cURL request

This example retrieves a specified attribute from an attachment.

curl "https://instance.service-now.com/api/now/attachment/a3af695b0a0006871b657c200acf62e0/attributes/example_key" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Response body.

{
  "result": {
    "key": "example_key",
    "value": "example_value"
  }
}

Attachment - GET /now/attachment/{sys_id}/file

Returns the binary file attachment with a specific sys_id value.

URL format

Versioned URL: /api/now/v1/attachment/{sys_id}/file

Default URL: /api/now/attachment/{sys_id}/file

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

cURL request

curl "https://instance.servicenow.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file" \
--request GET \
--header "Accept:*/*" \
--user "username":"password"

Binary response not shown.

Attachment - PATCH /now/attachment/{sys_id}

Renames an attachment.

URL format

Versioned URL: /api/now/{api_version}/attachment/{sys_id}

Default URL: /api/now/attachment/{sys_id}

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"error": {   
   "detail": "String",
   "message": "String"
}

cURL request

This example renames an attachment.

curl "https://instance.service-now.com/api/now/attachment/a3af695b0a0006871b657c200acf62e0" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"file_name\": \"new_attachment_name\"        
}" \
--user 'username':'password'

Response body.

""

Attachment - POST /now/attachment/{sys_id}/attributes

Adds an attribute to a specified attachment.

Attributes are added in the Attachment Attributes [sys_attachment_attribute] table.

This endpoint can be used to add alt text to an attachment.

URL format

Versioned URL: /api/now/{api_version}/attachment/{sys_id}/attributes

Default URL: /api/now/attachment/{sys_id}/attributes

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"result": { 
   "key": "String",  
   "value": "String"
}

cURL request

This example adds an attribute to an attachment.

curl "https://instance.service-now.com/api/now/attachment/a3af695b0a0006871b657c200acf62e0/attributes" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"key\": \"example_key\",  
  \"value\": \"example_value\"
}" \
--user 'username':'password'

Response body.

{
  "result": {
    "key": "example_key",
    "value": "example_value"
  }
}

Attachment - POST /now/attachment/file

Uploads a specified binary file as an attachment to a specified record.

Note: The file to attach must be specified after the last parameter in the passed-in request parameter list.

URL format

Versioned URL: /api/now/v1/attachment/file

Default URL: /api/now/attachment/file

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"result": {
  "average_image_color": "String",
  "compressed": "String", 
  "content_type": "String",
  "created_by_name": "String",
  "download_link": "String",
  "file_name": "String",
  "image_height": "String",
  "image_width": "String",
  "size_bytes": "String",
  "size_compressed": "String",
  "sys_created_by": "String",
  "sys_created_on": "String",
  "sys_id": "String",
  "sys_mod_count": "String",
  "sys_tags": "String",
  "sys_updated_by": "String",
  "sys_updated_on": "String",
  "table_name": "String",
  "table_sys_id": "String",
  "updated_by_name": "String"
}

cURL request

curl "https://instance.servicenow.com/api/now/attachment/file?table_name=incident&table_sys_id=d71f7935c0a8016700802b64c67c11c6&file_name=Issue_screenshot" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type: image/jpeg" \
--user "username":"password" \
--data-binary "@ location of the file on file system"

{
  "result": {
    "table_sys_id": "d71f7935c0a8016700802b64c67c11c6",
    "size_bytes": "36597",
    "download_link": "https://instance.servicenow.com/api/now/attachment/6ea10fe64f411200adf9f8e18110c739/file",
    "sys_updated_on": "2016-01-22 15:14:07",
    "sys_id": "6ea10fe64f411200adf9f8e18110c739",
    "image_height": "",
    "sys_created_on": "2016-01-22 15:14:07",
    "file_name": "Issue_screenshot",
    "sys_created_by": "admin",
    "compressed": "true",
    "average_image_color": "",
    "sys_updated_by": "admin",
    "sys_tags": "",
    "table_name": "incident",
    "image_width": "",
    "sys_mod_count": "0",
    "content_type": "image/jpeg",
    "size_compressed": "25130"
  }
}

Attachment - POST /now/attachment/upload

Uploads a multipart file attachment.

The multipart POST method does not accept any parameters. You must specify the table name and record sys_id values within the form body. See the cURL example for a sample of a multipart/form-data request.

Important: When using multipart POST, ensure that the file content is contained in the final part of the message only. Earlier parts should contain only metadata such as table name and record sys_id.

URL format

Versioned URL: /api/now/v1/attachment/upload

Default URL: /api/now/attachment/upload

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"result": {
  "average_image_color": "String",
  "compressed": "String", 
  "content_type": "String",
  "created_by_name": "String",
  "download_link": "String",
  "file_name": "String",
  "image_height": "String",
  "image_width": "String",
  "size_bytes": "String",
  "size_compressed": "String",
  "sys_created_by": "String",
  "sys_created_on": "String",
  "sys_id": "String",
  "sys_mod_count": "String",
  "sys_tags": "String",
  "sys_updated_by": "String",
  "sys_updated_on": "String",
  "table_name": "String",
  "table_sys_id": "String",
  "updated_by_name": "String"
}

POST multipart mandatory values

When sending a multipart POST request to upload a file attachment, include attachment data in the message body, not in the URL parameters. You must specify these values in the message body:

cURL request

curl "https://instance.servicenow.com/api/now/attachment/upload" \
--request POST \
--header "Accept:application/json"\
--user "username":"password"\
--header "Content-Type:multipart/form-data"\
 -F 'table_name=incident' \
 -F 'table_sys_id=d71f7935c0a8016700802b64c67c11c6'\
 -F 'uploadFile=@ location of the file on file system'
\

{
  "result": {
    "table_sys_id": "d71f7935c0a8016700802b64c67c11c6",
    "size_bytes": "36597",
    "download_link": "https://instance.service-now.com/api/now/attachment/994adbc64f511200adf9f8e18110c796/file",
    "sys_updated_on": "2016-02-02 14:00:21",
    "sys_id": "994adbc64f511200adf9f8e18110c796",
    "image_height": "",
    "sys_created_on": "2016-02-02 14:00:21",
    "file_name": "banner-CS0001345_v1_1.jpeg",
    "sys_created_by": "admin",
    "compressed": "true",
    "average_image_color": "",
    "sys_updated_by": "admin",
    "sys_tags": "",
    "table_name": "incident",
    "image_width": "",
    "sys_mod_count": "0",
    "content_type": "image/jpeg",
    "size_compressed": "25130"
  }
}

Attachment - PUT /now/attachment/{sys_id}/attributes/{attribute_key}

Updates the value of an existing attribute for an attachment.

Attributes are updated in the Attachment Attributes [sys_attachment_attribute] table.

URL format

Versioned URL: /api/now/{api_version}/attachment/{sys_id}/attributes/{attribute_key}

Default URL: /api/now/attachment/{sys_id}/attributes/{attribute_key}

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"result": { 
   "key": "String",  
   "value": "String"
}

cURL request

This example updates the value of the example_key attribute for the specified attachment.

curl "https://instance.service-now.com/api/now/attachment/a3af695b0a0006871b657c200acf62e0/attributes/example_key" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"value\": \"new_value\"
}" \
--user 'username':'password'

Response body.

{
  "result": {
    "key": "example_key",
    "value": "new_value"
  }
}