TomTom LogoDocs
Products
Resources
Pricing
Sign in
Map Feedback API
Documentation
API Explorer

Initiate attachment upload

Request access
Service version: 1.0.0Last edit: 2026.09.23NEW

Important note
This API is not available as part of our free evaluation or Pay As You Grow (PAYG) offering. Click the Request Access button above to contact our Sales team.

Purpose

This call is used to start adding a file to a feedback. It reserves a place for the file and returns a temporary link that you upload the file to. It is the first of the three calls described in Attachments.

The file itself is not sent with this call.

How to request data

HTTP method: POST

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for these values. The generic URL format is as follows.

URL request format

post
URL request format
https://{baseURL}/maps/orbis/feedback/{feedbackId}/attachments?key={API-key}&apiVersion={version}

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • The order of request parameters is not important.

Parameter

Required

Type

Description

feedbackId

Yes

string

The ID of the feedback the file belongs to. Part of the URL.

filename

Yes

string

The name of the file, as it should be shown later. A maximum of 255 characters.

contentType

Yes

string

The type of the file. One of image/png, image/jpeg, image/gif, image/webp, application/pdf, text/plain.

sizeBytes

Yes

integer

The size of the file in bytes. Must be greater than 0 and no larger than 10,485,760 (10 MiB).

Example request

{
 "filename": "missing-road-sign.png",
 "contentType": "image/png",
 "sizeBytes": 20480
}

Response data

The uploadUrl points at TomTom’s file storage on *.blob.core.windows.net and already carries a temporary access token, so send it exactly as you received it. It is valid for 15 minutes, until the moment given in expiresAt. Upload the file to it with an HTTP PUT request, then confirm the upload with Complete attachment upload. If the link expires before you upload, simply make this call again to get a new one.

Response codes

HTTP Code

Message

Description

Sample response

201

Created

Upload started successfully

{
  "attachmentId": "6b48dd3c-6d0c-4b0a-9a6e-1f1c0e2a51f4",
  "uploadUrl": "https://{storageHost}/attachments/{blobId}?{sasToken}",
  "expiresAt": "2026-09-23T10:22:41.114166"
}

400

Bad Request

Invalid request parameters, for example a file type that is not allowed or a file that is too large

{
  "errorText": "Validation failed",
  "detailedError": {
    "code": "BAD_REQUEST",
    "message": "sizeBytes: must be less than or equal to 10485760"
  },
  "httpStatusCode": 400
}

403

Forbidden

Access denied

{
  "detailedError": {
    "code": "Forbidden",
    "message": "You are not allowed to access this endpoint"
  }
}

404

Not Found

Feedback not found

{
  "errorText": "Feedback with feedback id=7049aa04-91bd-4ad3-8085-bd8bec318905 not found",
  "detailedError": {
    "code": "NOT_FOUND",
    "message": "Feedback with feedback id=7049aa04-91bd-4ad3-8085-bd8bec318905 not found"
  },
  "httpStatusCode": 404
}

409

Conflict

The feedback already has the maximum of 100 attachments

{
  "errorText": "Issue 7049aa04-91bd-4ad3-8085-bd8bec318905 already has 100 attachments (max 100)",
  "detailedError": {
    "code": "CONFLICT",
    "message": "Issue 7049aa04-91bd-4ad3-8085-bd8bec318905 already has 100 attachments (max 100)"
  },
  "httpStatusCode": 409
}

500

Internal Server Error

Internal server error

{
  "errorText": "An unexpected error has occurred. Please try again later.",
  "detailedError": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error has occurred. Please try again later."
  },
  "httpStatusCode": 500
}