Reserve an attachment upload

curl --request POST \
  --url https://{your-subdomain}.neetodesk.com/api/external/v2/attachment_uploads \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "filename": "report.pdf",
  "byte_size": 20481,
  "checksum": "Y2hlY2tzdW1leGFtcGxl",
  "content_type": "application/pdf"
}
'

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filename: 'report.pdf',
    byte_size: 20481,
    checksum: 'Y2hlY2tzdW1leGFtcGxl',
    content_type: 'application/pdf'
  })
};

fetch('https://{your-subdomain}.neetodesk.com/api/external/v2/attachment_uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{your-subdomain}.neetodesk.com/api/external/v2/attachment_uploads"

payload = {
    "filename": "report.pdf",
    "byte_size": 20481,
    "checksum": "Y2hlY2tzdW1leGFtcGxl",
    "content_type": "application/pdf"
}
headers = {
    "X-Api-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6IjEyMyJ9fQ==",
  "upload_url": "https://neeto-desk.s3.amazonaws.com/3ieihu6erxcialumauhj1pqs07hr?X-Amz-Signature=...",
  "upload_headers": {
    "Content-Type": "application/pdf",
    "Content-MD5": "Y2hlY2tzdW1leGFtcGxl"
  },
  "filename": "report.pdf",
  "content_type": "application/pdf",
  "byte_size": 20481,
  "checksum": "Y2hlY2tzdW1leGFtcGxl"
}

Attachments

Reserve an attachment upload

Reserves storage for a file and returns where to send its bytes, for callers that would rather not route the file through this API. Use Upload attachment instead to send the file in one request.

Three steps:

POST the file’s filename, byte_size and checksum here. The response carries a signed_id, an upload_url and the upload_headers the next step must send.
PUT the file’s bytes to upload_url, carrying every header in upload_headers unchanged. The bytes go straight to storage and never pass through this API.
Pass the signed_id in attachments on Create ticket or Create comment.

checksum is the base64-encoded MD5 digest of the file, which is the form Content-MD5 takes - not the hex digest. Generate it with openssl dgst -md5 -binary report.pdf | base64. The storage service verifies it, so a wrong digest fails at step 2.

A reservation holds no file until step 2 completes. Attaching a signed_id whose bytes never arrived is rejected rather than left as a broken attachment, and a reservation that is never used is cleaned up automatically.

POST

attachment_uploads

Reserve an attachment upload

curl --request POST \
  --url https://{your-subdomain}.neetodesk.com/api/external/v2/attachment_uploads \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "filename": "report.pdf",
  "byte_size": 20481,
  "checksum": "Y2hlY2tzdW1leGFtcGxl",
  "content_type": "application/pdf"
}
'

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filename: 'report.pdf',
    byte_size: 20481,
    checksum: 'Y2hlY2tzdW1leGFtcGxl',
    content_type: 'application/pdf'
  })
};

fetch('https://{your-subdomain}.neetodesk.com/api/external/v2/attachment_uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{your-subdomain}.neetodesk.com/api/external/v2/attachment_uploads"

payload = {
    "filename": "report.pdf",
    "byte_size": 20481,
    "checksum": "Y2hlY2tzdW1leGFtcGxl",
    "content_type": "application/pdf"
}
headers = {
    "X-Api-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6IjEyMyJ9fQ==",
  "upload_url": "https://neeto-desk.s3.amazonaws.com/3ieihu6erxcialumauhj1pqs07hr?X-Amz-Signature=...",
  "upload_headers": {
    "Content-Type": "application/pdf",
    "Content-MD5": "Y2hlY2tzdW1leGFtcGxl"
  },
  "filename": "report.pdf",
  "content_type": "application/pdf",
  "byte_size": 20481,
  "checksum": "Y2hlY2tzdW1leGFtcGxl"
}

Replace {your-subdomain} with your workspace’s subdomain.
Learn how to find your subdomain in Workspace subdomain.

Sending the file

The response tells you where to send the bytes. Send them with a PUT, carrying every header from upload_headers unchanged.

FILE=$HOME/Downloads/report.pdf

# 1. Reserve the upload. `wc -c` pads its output on BSD and macOS, so trim it.
curl -X POST "https://<subdomain>.neetodesk.com/api/external/v2/attachment_uploads" \
  -H "X-Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d "{
        \"filename\": \"$(basename "$FILE")\",
        \"byte_size\": $(wc -c < "$FILE" | tr -d ' '),
        \"checksum\": \"$(openssl dgst -md5 -binary "$FILE" | base64)\",
        \"content_type\": \"application/pdf\"
      }"

# 2. Send the bytes to the upload_url from the response. Pass each header from
#    upload_headers exactly as the response gave it, values included.
curl -X PUT "<upload_url>" \
  -H "Content-Type: <upload_headers.Content-Type>" \
  -H "Content-MD5: <upload_headers.Content-MD5>" \
  --data-binary "@$FILE"

# 3. Attach it.
curl -X POST "https://<subdomain>.neetodesk.com/api/external/v2/tickets" \
  -H "X-Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "customer@example.com",
        "subject": "Printer is jammed",
        "description": "Report attached.",
        "attachments": ["<signed_id>"]
      }'

checksum is the base64-encoded MD5 digest, not the hex digest. The storage service verifies it, so a hex digest fails at step 2 rather than at step 1.

Send the headers from upload_headers rather than composing your own. Their values are covered by the upload signature, so an altered or missing one is refused. Which headers appear depends on how the workspace stores files, so read them from the response rather than hardcoding the set above.

Headers

X-Api-Key

string

default:your-api-key

required

Use the X-Api-Key header to provide your workspace API key. Refer to Authentication for more information.

Body

application/json

filename

string

required

Name the file should carry in the workspace.

Example:

"report.pdf"

byte_size

integer

required

Size of the file in bytes.

Example:

20481

checksum

string

required

Base64-encoded MD5 digest of the file, which is the form Content-MD5 takes. Not the hex digest. Generate it with openssl dgst -md5 -binary report.pdf | base64.

Example:

"Y2hlY2tzdW1leGFtcGxl"

content_type

string

Media type of the file. Inferred from the filename when omitted.

Example:

"application/pdf"

Response

Created - Upload reserved successfully

signed_id

string

Pass this to attachments on ticket or comment create once the file's bytes have been sent to upload_url. It is only accepted in the workspace that reserved it, and attaching it before the bytes arrive is rejected.

Example:

"eyJfcmFpbHMiOnsiZGF0YSI6IjEyMyJ9fQ=="

upload_url

string

Send the file's bytes here with an HTTP PUT. The URL is short-lived.

Example:

"https://neeto-desk.s3.amazonaws.com/3ieihu6erxcialumauhj1pqs07hr?X-Amz-Signature=..."

upload_headers

object

Headers the PUT must carry, exactly as given. Send them unchanged - the signature covers them, so an altered or missing header is refused by the storage service.

Hide child attributes

upload_headers.{key}

string

Example:

{
  "Content-Type": "application/pdf",
  "Content-MD5": "Y2hlY2tzdW1leGFtcGxl"
}

filename

string

Example:

"report.pdf"

content_type

string

Example:

"application/pdf"

byte_size

integer

Example:

20481

checksum

string

Example:

"Y2hlY2tzdW1leGFtcGxl"

Getting started

Tickets

Comments

Attachments

Customers

Ticket fields

Forms

Reports

Team members

API v1 (deprecated)

Reserve an attachment upload

Sending the file

Headers

Body

Response

​Sending the file

Headers

Body

Response

Sending the file