Attachment API

The Attachment API allows 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.

The following video provides more information on the Attachment API:

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

This method deletes the attachment with a specific sys_id value.

URL format

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

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

Supported request parameters

Table 1. Parameters
Parameter Description
sys_id The sys_id value of the attachment to delete.

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.

Table 2. Request headers
Header Description
None
Table 3. Response headers
Header Description
None

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 response codes .

Table 4. Status codes
Status code Description
204 Indicates the request ran successfully.

Sample cURL request

curl "https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5" \
--request DELETE \
--header "Accept:application/json" \
--user 'admin':'admin'
""

Sample Python request

#Need to install requests package for python
#easy_install requests
import requests

# Set the request parameters
url = 'https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5'

# Eg. User name="admin", Password="admin" for this code sample.
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Content-Type":"application/xml","Accept":"application/xml"}

# Do the HTTP request
response = requests.delete(url, auth=(user, pwd), headers=headers  )

# Check for HTTP codes other than 200
if response.status_code != 200: 
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Decode the JSON response into a dictionary and use the data
data = response.json()
print(data)
None

Attachment API - GET /now/attachment

This method gets the metadata for multiple attachments.

URL format

Versioned URL: api/now/v1/attachment

Default URL: api/now/attachment

Supported request parameters

Table 5. Parameters
Parameter Description
sysparm_query An encoded query. Queries for the Attachment API are relative to the Attachments [sys_attachment] table.

For example: (sysparm_query=file_name=attachment.doc)

The encoded query provides support for order by. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query. For example, sysparm_query=ORDERBYfile_name^ORDERBYDESCtable_Name orders the results in ascending order by name first, and then in descending order by table name.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: This property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.
sysparm_limit Limit to be applied on pagination. The default is 10000.

Unusually large sysparm_limit values can impact system performance.

sysparm_offset A number of records to exclude from the query. Use this parameter when you need to get more records than specified in sysparm_limit. For example, if sysparm_limit is set to 500, but there are additional records you want to query, you can specify a sysparm_offset value of 500 to get the second set of records.

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.

Table 6. Request headers
Header Description
Table 7. Response headers
Header Description
Content-Type The content type of the response. For metadata requests, this is the content type of the metadata, not the content type of the attachment files.
Link Links to download the attachments.

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 response codes .

Table 8. Status codes
Status code Description
200 Indicates the query ran successfully.

Sample cURL request

curl "https://instance.service-now.com/api/now/attachment?sysparm_limit=1" \
--request GET \
--header "Accept:application/json" \
--user 'admin':'admin'
{
  "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"
    }
  ]
}

Sample Python request

#Need to install requests package for python
#easy_install requests
import requests

# Set the request parameters
url = 'https://instance.service-now.com/api/now/attachment?sysparm_limit=1'

# Eg. User name="admin", Password="admin" for this code sample.
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Content-Type":"application/xml","Accept":"application/xml"}

# Do the HTTP request
response = requests.get(url, auth=(user, pwd), headers=headers  )

# Check for HTTP codes other than 200
if response.status_code != 200: 
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Decode the JSON response into a dictionary and use the data
data = response.json()
print(data)
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <result>
      <table_sys_id>5054b6f8c0a800060056addcf551ecf8</table_sys_id>
      <size_bytes>462</size_bytes>
      <download_link>https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file</download_link>
      <sys_updated_on>2009-05-21 04:12:21</sys_updated_on>
      <sys_id>615ea769c0a80166001cf5f2367302f5</sys_id>
      <image_height />
      <sys_created_on>2009-05-21 04:12:21</sys_created_on>
      <file_name>blocks.swf</file_name>
      <sys_created_by>glide.maint</sys_created_by>
      <compressed>true</compressed>
      <average_image_color />
      <sys_updated_by>glide.maint</sys_updated_by>
      <sys_tags />
      <image_width />
      <table_name>content_block_programmatic</table_name>
      <sys_mod_count>0</sys_mod_count>
      <content_type>application/x-shockwave-flash</content_type>
      <size_compressed>485</size_compressed>
   </result>
</response>

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

This method gets the metadata for the attachment file with a specific sys_id value.

URL format

Versioned URL: api/now/v1/attachment/<attachment record sys_id>

Default URL: api/now/attachment/<attachment record sys_id>

Supported request parameters

Table 9. Parameters
Parameter Description
sys_id The sys_id of the attachment record you want to get metadata for.

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.

Table 10. Request headers
Header Description
None
Table 11. Response headers
Header Description
Content-Type The content type of the response. For metadata requests, this is the content type of the metadata, not the content type of the attachment files.

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 response codes .

Table 12. Status codes
Status code Description
200 Indicates the query ran successfully.
404 Indicates the specified attachment does not exist, or the current user cannot access it.

Sample cURL request

curl "https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5" \
--request GET \
--header "Accept:application/json" \
--user 'admin':'admin'
{
  "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"
  }
}

Sample Python request

#Need to install requests package for python
#easy_install requests
import requests

# Set the request parameters
url = 'https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5'

# Eg. User name="admin", Password="admin" for this code sample.
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Content-Type":"application/xml","Accept":"application/xml"}

# Do the HTTP request
response = requests.get(url, auth=(user, pwd), headers=headers  )

# Check for HTTP codes other than 200
if response.status_code != 200: 
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Decode the JSON response into a dictionary and use the data
data = response.json()
print(data)
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <result>
      <table_sys_id>5054b6f8c0a800060056addcf551ecf8</table_sys_id>
      <size_bytes>462</size_bytes>
      <download_link>https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file</download_link>
      <sys_updated_on>2009-05-21 04:12:21</sys_updated_on>
      <sys_id>615ea769c0a80166001cf5f2367302f5</sys_id>
      <image_height />
      <sys_created_on>2009-05-21 04:12:21</sys_created_on>
      <file_name>blocks.swf</file_name>
      <sys_created_by>glide.maint</sys_created_by>
      <compressed>true</compressed>
      <average_image_color />
      <sys_updated_by>glide.maint</sys_updated_by>
      <sys_tags />
      <image_width />
      <table_name>content_block_programmatic</table_name>
      <sys_mod_count>0</sys_mod_count>
      <content_type>application/x-shockwave-flash</content_type>
      <size_compressed>485</size_compressed>
   </result>
</response>

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

This method gets the binary file attachment with a specific sys_id value.

URL format

Versioned URL: api/now/v1/attachment/<attachment sys_id>/file

Default URL: api/now/attachment/<attachment sys_id>/file

Supported request parameters

Table 13. Parameters
Parameter Description
sys_id The sys_id of the attachment record you want to get binary data from.

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.

Table 14. Request headers
Header Description
None
Table 15. Response headers
Header Description
X-Attachment-Metadata Metadata about the returned file, such as size, name, and file type.

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 response codes .

Table 16. Status codes
Status code Description
200 Indicates the query ran successfully.

Sample cURL request

curl "https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file" \
--request GET \
--header "Accept:*/*" \
--user 'admin':'admin'
Binary response not shown.

Sample Python request

#Need to install requests package for python
#easy_install requests
import requests

# Set the request parameters
url = 'https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file'

# Eg. User name="admin", Password="admin" for this code sample.
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Content-Type":"application/xml","Accept":"*/*"}

# Do the HTTP request
response = requests.get(url, auth=(user, pwd), headers=headers  )

# Check for HTTP codes other than 200
if response.status_code != 200: 
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Decode the JSON response into a dictionary and use the data
data = response.json()
print(data)
Binary response not shown.

Attachment API - POST /now/attachment/file

This method uploads a binary file specified in the request body as an attachment.

URL format

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

Default URL: /api/now/attachment/file

Supported request parameters

Table 17. Parameters
Parameter Description
file_name (Required) The name to give the attachment. This parameter is required to post an attachment.
table_name (Required) The name of the table you want to attach the file to. This parameter is required to post an attachment.
table_sys_id (Required) The sys_id of the record on the specified table that you want to attach the file to. This parameter is required to post an attachment.
encryption_context The sys_id of an encryption context record. Specify this parameter to allow only users with the specified encryption context to access the attachment. If you do not specify this parameter, the attached file is not encrypted with any encryption context.

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.

Table 18. Request headers
Header Description
Content-Type The content type of the file you want to attach. This header is mandatory to post file attachments.
Table 19. Response headers
Header Description
Location The URL of the new attachment.

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 response codes .

Table 20. Status codes
Status code Description
201 Indicates the query ran successfully.
400 Indicates that one or more mandatory parameters were missing from the request.
404 Indicates the record specified by the table_name and table_sys_id parameters does not exist or is not accessible by the current user.

Sample cURL request

curl "https://instance.service-now.com/api/now/attachment/file?table_name=incident&table_sys_id=d71f7935c0a8016700802b64c67c11c6&file_name=Issue_screenshot" \
--request POST \
--header "Accept:application/json" \
--user 'admin':'admin'
--header "Content-Type: image/jpeg"
-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/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"
  }
}

Sample Python request

#Need to install requests package for python
#easy_install requests
import requests

# Set the request parameters
url = 'https://instance.service-now.com/api/now/attachment/file?table_name=incident&table_sys_id=d71f7935c0a8016700802b64c67c11c6&file_name=Issue_screenshot.jpg'

# Specify the file To send. When specifying fles to send make sure you specify the path to the file, in
# this example the file was located in the same directory as the python script being executed.
data = open('Issue_screenshot.jpg', 'rb').read()

# Eg. User name="admin", Password="admin" for this code sample.
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Content-Type":"image/jpeg","Accept":"application/json"}

# Do the HTTP request
response = requests.post(url, auth=(user, pwd), headers=headers, data=data)

# Check for HTTP codes other than 201
if response.status_code != 201: 
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Decode the JSON response into a dictionary and use the data
data = response.json()
print(data)
{
  "result": {
    "table_sys_id": "d71f7935c0a8016700802b64c67c11c6",
    "size_bytes": "36597",
    "download_link": "https://instance.service-now.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.jpg",
    "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 API - POST /now/attachment/upload

This method uploads a multipart file attachment.

URL format

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

Default URL: /api/now/attachment/upload

Supported request parameters

Table 21. Parameters
Parameter Description
None The multipart POST method does not accept any parameters. The table name and record sys_id values must be specified within the message body. See the POST multipart sample for an example of a multipart message.
Important: When using multipart POST, ensure 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.

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.

Table 22. Request headers
Header Description
Content-Type The content type of the request. Set this value to multipart/form-data when using the multipart POST method.
Table 23. Response headers
Header Description
Location The URL of the new attachment.

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 response codes .

Table 24. Status codes
Status code Description
201 Indicates the query ran successfully.

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:
Table 25. Mandatory values
Value Description
table_name The name of the table you want to attach the file to.
record_sys_id The sys_id of the record on the specified table that you want to attach the file to.
Content-Type The Content-Type of the file, included in the message body for multipart uploads.
Note: The Content-Type must be defined within the file portion of the POST message, not within the form data. See the sample POST multipart message for an example of a multipart message.

Sample cURL request

curl "https://instance.service-now.com/api/now/attachment/upload" \
--request POST \
--header "Accept:application/json"
--user 'admin':'admin'"\
--header "Content-Type:multipart/form-data"
 -F 'table_name=incident' -F 'table_sys_id=d71f7935c0a8016700802b64c67c11c6' -F 'encryption_context=undefined'-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"
  }
}

Sample Python request

# This example uses the Python Requests Library and you will need to install requests package for python
# Documentation can be found at http://docs.python-requests.org/en/master/user/quickstart/
import requests
import pprint
import json

# Specify the Endpoint URL replacing instance with your ServiceNow Instance Name
url = 'https://instance.service-now.com/api/now/attachment/upload'

# Specify Parameters for File Being Uploaded, the table_name and table_sys_id should be replaced with values that make
# sense for your use case
payload = {'table_name':'incident', 'table_sys_id':'81f8915bdb6ba20028927416bf961971'}

# Specify Files To Send and Content Type. When specifying fles to send make sure you specify the path to the file, in
# this example the file was located in the same directory as the python script being executed.
# it is important to specify the correct file type
files = {'file': ('issue_screenshot.JPG', open('issue_screenshot.JPG', 'rb'), 'image/jpg', {'Expires': '0'})}

# Eg. User name="admin", Password="admin" for this code sample. This will be sent across as basic authentication
user = 'admin'
pwd = 'admin'

# Set proper headers
headers = {"Accept":"*/*"}

# Send the HTTP request
response = requests.post(url, auth=(user, pwd), headers=headers, files=files, data=payload)

# Check for HTTP codes other than 201
if response.status_code != 201:
    print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json())
    exit()

# Print Resopnse Details
print 'Response Status Code:', response.status_code

print ''
print('Reponse Payload:')
print json.dumps(response.json(), indent=4)
Response Status Code: 201

Reponse Payload:
{
    "result": {
        "sys_tags": "", 
        "sys_updated_by": "admin", 
        "content_type": "image/jpg", 
        "sys_created_by": "admin", 
        "file_name": "issue_screenshot.JPG", 
        "sys_updated_on": "2017-01-05 10:47:09", 
        "sys_created_on": "2017-01-05 10:47:09", 
        "image_width": "", 
        "image_height": "", 
        "sys_mod_count": "0", 
        "table_name": "incident", 
        "sys_id": "96679f724f84320025e874828110c7bd", 
        "download_link": "https://instance.service-now.com/api/now/attachment/96679f724f84320025e874828110c7bd/file", 
        "average_image_color": "", 
        "size_bytes": "197484", 
        "table_sys_id": "'81f8915bdb6ba20028927416bf961971'", 
        "size_compressed": "197005", 
        "compressed": "true"
    }
}