---
updatedAt: 2026-07-01T11:37:16.000Z
agentTools:
  projectIndex: https://developer.servicem8.com/llms.txt
---

# Create a new Attachment


			
#### OAuth Scope
This endpoint requires the following OAuth scope **manage_attachments**.

			
			
#### Record UUID
UUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.

			

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "ServiceM8 API",
    "description": "Move your app forward with the ServiceM8 API\n\n\n\n## Limits and Throttling\nTo ensure continuous quality of service, API usage can be subject to throttling. The throttle will be applied once an API consumer reaches a certain \nthreshold in terms of a maximum number of requests per minute. Most clients will never hit this threshold, but those that do, will get met by a \nHTTP 429 Too Many Requests response code. \n \nThere is a limit of 180 requests per minute, if you reach this you will receive a HTTP 429 with a text body of \"Number of allowed API requests per minute exceeded\".\nThere is a limit of 20000 requests per day, if you reach this you will receive a HTTP 429 with a text body of \"Number of allowed API requests per day exceeded\".\n\nWe encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).\n\nLimits are per Addon per account.\n\n\n## Opening Records in ServiceM8\nWhen you need to send a staff member from an external app to a ServiceM8 record in the web app, build the URL using the record UUID on the primary app domain:\n\n* Job: `https://go.servicem8.com/OpenJob/{job_uuid}`\n* Client: `https://go.servicem8.com/OpenClient/{company_uuid}`\n\nClient records are exposed by the Company endpoint in the REST API, so use the Company record `uuid` as `{company_uuid}`. These URLs are web app links, not REST API endpoints, and do not use API authentication. Users who are not signed in are redirected through login and then back to the requested record. The signed-in staff member must have access to the record and the relevant ServiceM8 menu permission.\n",
    "termsOfService": "https://www.servicem8.com/terms-of-service",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.servicem8.com/api_1.0"
    }
  ],
  "security": [
    {
      "apiKey": []
    },
    {
      "oauth2": []
    }
  ],
  "paths": {
    "/attachment.json": {
      "post": {
        "tags": [
          "Attachments"
        ],
        "operationId": "createAttachments",
        "summary": "Create a new Attachment",
        "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_attachments**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth2": [
              "manage_attachments"
            ]
          }
        ],
        "parameters": [],
        "requestBody": {
          "description": "Attachment record to create",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttachmentCreate"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "file",
                  "related_object",
                  "related_object_uuid"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file bytes to upload. The filename must include a file extension."
                  },
                  "related_object": {
                    "type": "string",
                    "description": "The type of object this attachment is related to, such as job or company."
                  },
                  "related_object_uuid": {
                    "type": "string",
                    "format": "uuid",
                    "description": "UUID of the related object."
                  },
                  "attachment_name": {
                    "type": "string",
                    "description": "Display name for the attachment. Defaults to the uploaded filename."
                  },
                  "attachment_source": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "string"
                  },
                  "lng": {
                    "type": "number",
                    "format": "double",
                    "minimum": -180,
                    "maximum": 180
                  },
                  "lat": {
                    "type": "number",
                    "format": "double",
                    "minimum": -90,
                    "maximum": 90
                  },
                  "is_favourite": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ]
                  },
                  "uuid": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional client-generated UUID for the attachment."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "headers": {
              "x-record-uuid": {
                "description": "UUID of newly created Attachment record",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "examples": {
                  "success": {
                    "value": {
                      "errorCode": 0,
                      "message": "OK"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Attachment created and file uploaded successfully",
            "headers": {
              "x-record-uuid": {
                "description": "UUID of the created attachment",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Location": {
                "description": "Relative URL of the created attachment",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Attachment"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - The request is malformed or contains invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "badRequest": {
                    "value": {
                      "errorCode": 1000,
                      "message": "An error occurred completing your request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication credentials are missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "errorCode": 401,
                      "message": "Authentication failed. Please check your API key or OAuth token."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - You don't have permission to create this resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "errorCode": 403,
                      "message": "Access forbidden. You don't have permission to access this resource."
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Uploaded file is too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported upload media type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - You have exceeded the rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                },
                "examples": {
                  "rateLimitMinute": {
                    "value": {
                      "errorCode": 429,
                      "message": "Number of allowed API requests per minute exceeded"
                    }
                  },
                  "rateLimitDay": {
                    "value": {
                      "errorCode": 429,
                      "message": "Number of allowed API requests per day exceeded"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - An unexpected error occurred on the server",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "serverError": {
                    "value": {
                      "errorCode": 500,
                      "message": "An unexpected error occurred. Please try again later."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "name": "X-Api-Key",
        "in": "header"
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.servicem8.com/oauth/authorize",
            "tokenUrl": "https://api.servicem8.com/oauth/access_token",
            "scopes": {
              "staff_locations": "Access to real-time GPS information about staff",
              "staff_activity": "Access to clock on, lunch break and clock off information about staff",
              "publish_sms": "Access to send SMS messages to customers and/or staff on your behalf. Note sending SMS messages will incur account charges.",
              "publish_email": "Access to send Email messages to customers and/or staff on your behalf",
              "vendor": "Access to basic account information",
              "vendor_logo": "Access to account logo",
              "vendor_email": "Access to account holder email address",
              "read_locations": "Read-only access to Location Endpoint",
              "manage_locations": "Full access to Location Endpoint",
              "read_staff": "Read-only access to Staff Endpoint",
              "manage_staff": "Full access to Staff Endpoint",
              "read_customers": "Read-only access to Company Endpoint",
              "manage_customers": "Full access to Company Endpoint",
              "read_customer_contacts": "Read-only access to CompanyContact Endpoint",
              "manage_customer_contacts": "Full access to CompanyContact Endpoint",
              "read_jobs": "Read-only access to Job and Badge endpoints; includes read_badges",
              "manage_jobs": "Full access to Job Endpoint",
              "create_jobs": "Ability to create jobs on behalf of account. Note creating jobs may incur account charges.",
              "read_job_contacts": "Read-only access to JobContact Endpoint",
              "manage_job_contacts": "Full access to JobContact Endpoint",
              "read_job_materials": "Read-only access to JobMaterials Endpoint",
              "manage_job_materials": "Full access to JobMaterials Endpoint",
              "read_job_categories": "Read-only access to Categories Endpoint",
              "manage_job_categories": "Full access to Categories Endpoint",
              "read_job_queues": "Read-only access to Job Queues Endpoint",
              "manage_job_queues": "Full access to Job Queues Endpoint",
              "read_tasks": "Read-only access to Tasks Endpoint",
              "manage_tasks": "Full access to Tasks Endpoint",
              "read_schedule": "Read-only access to JobActivity Endpoint",
              "manage_schedule": "Full access to JobActivity Endpoint",
              "read_inventory": "Read-only access to Materials Endpoint",
              "manage_inventory": "Full access to Materials Endpoint",
              "read_job_notes": "Read-only access to job notes",
              "publish_job_notes": "Ability to add new job notes",
              "read_job_photos": "Read-only access to job photos",
              "publish_job_photos": "Ability to add new job photos",
              "read_attachments": "Read-only access to Attachments Endpoint",
              "manage_attachments": "Full access to Attachments Endpoint",
              "read_inbox": "Read-only access to inbox messages",
              "read_messages": "Read-only access to staff messages",
              "manage_notifications": "Ability to read notifications and mark as read",
              "read_templates": "Read-only access to email, sms and document templates",
              "manage_templates": "Full-access to email, sms and document templates; includes read_templates",
              "read_badges": "Read-only access to job badges; also granted by read_jobs",
              "manage_badges": "Full-access to read/create/modify job badges; includes read_badges",
              "read_assets": "Read-only access to Assets Endpoint",
              "manage_assets": "Full access to Assets Endpoint",
              "read_knowledge_base": "Read-only access to Knowledge Base Endpoint",
              "manage_knowledge_base": "Full access to Knowledge Base Endpoint",
              "publish_diary_items": "Create immutable Add-on Job Diary items",
              "read_email": "Read job email history",
              "read_sms": "Read job SMS history",
              "create_notifications": "Create staff notifications",
              "read_service_templates": "Read access to ServiceTemplates",
              "manage_service_templates": "Full access to manage ServiceTemplates",
              "read_job_admin_activity": "Read-only access to job administration time records"
            }
          }
        }
      }
    },
    "schemas": {
      "Attachment": {
        "type": "object",
        "properties": {
          "related_object": {
            "description": "The type of object this attachment is related to (e.g., 'job', 'company', 'staff'). Must be a valid object type. Always stored in lowercase.",
            "type": "string"
          },
          "related_object_uuid": {
            "description": "UUID of the related object to which this attachment belongs. Must be a valid UUID of an existing object of the type specified in the related_object field.",
            "format": "uuid",
            "example": "123e4567-3eaf-4a91-bbce-3d4ad9cd6ed8",
            "type": "string"
          },
          "attachment_name": {
            "description": "Name of the attachment file. Used for display purposes and for naming the file when downloaded. Does not need to include file extension as this is determined by the file_type field.",
            "type": "string"
          },
          "file_type": {
            "description": "File extension including the leading dot (e.g., '.pdf', '.jpg'). Determines how the file is processed and displayed. Always stored in lowercase.",
            "type": "string"
          },
          "attachment_source": {
            "description": "Indicates the source or type of the attachment (e.g., 'INVOICE', 'QUOTE'). Used for filtering and determining how to display the attachment.",
            "type": "string"
          },
          "tags": {
            "description": "Comma-separated list of tags associated with the attachment. Used for categorization and filtering of attachments.",
            "type": "string"
          },
          "lng": {
            "description": "Longitude coordinate where the attachment was created. Used for geolocation of photos and other attachments. Decimal degrees format.",
            "type": "number",
            "format": "float"
          },
          "lat": {
            "description": "Latitude coordinate where the attachment was created. Used for geolocation of photos and other attachments. Decimal degrees format.",
            "type": "number",
            "format": "float"
          },
          "photo_width": {
            "description": "Width of the image in pixels. Only applicable for image attachments. Read-only in the API. (Read only)",
            "type": "integer"
          },
          "photo_height": {
            "description": "Height of the image in pixels. Only applicable for image attachments. Read-only in the API. (Read only)",
            "type": "integer"
          },
          "extracted_info": {
            "description": "Additional information extracted from the file, such as form responses or OCR text. Read-only in the API. (Read only)",
            "type": "string"
          },
          "is_favourite": {
            "description": "Flag indicating whether this attachment has been marked as a favorite. Used for filtering and displaying attachments. Valid values are [0,1]",
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "class_name": {
            "description": "The specific class type of the attachment. Used for specialized attachment types that extend the base dboAttachment class. Read-only in the API."
          },
          "metadata": {
            "description": "Additional structured data associated with the attachment in JSON format. The schema varies depending on attachment type and source. Used to store extended information that doesn't fit into standard fields. (Read only)",
            "type": "object",
            "additionalProperties": true
          },
          "uuid": {
            "format": "uuid",
            "description": "Unique identifier for this record",
            "example": "123e4567-7783-4d54-87c8-d34874ee627c",
            "type": "string"
          },
          "active": {
            "enum": [
              0,
              1
            ],
            "type": "integer",
            "default": 1,
            "description": "Record active/deleted flag. Valid values are [0,1]"
          },
          "edit_date": {
            "readOnly": true,
            "example": "2025-01-01 12:00:00",
            "description": "Timestamp at which record was last modified"
          },
          "created_by_staff_uuid": {
            "format": "uuid",
            "example": "123e4567-8613-4531-b0d9-30187744a228",
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          },
          "signature_data": {
            "type": "object",
            "description": "(Read only)",
            "properties": {
              "templateSupportsSignature": {
                "type": "boolean",
                "description": "True if the template from which this document was produced supports signing"
              },
              "documentSnapshotUUID": {
                "type": "string",
                "format": "uuid",
                "description": "The template mergefield snapshot which captured the unsigned document state"
              },
              "documentSnapshotExpiresUnixtime": {
                "type": "number",
                "description": "The unixtime at which the snapshot expires"
              },
              "signedDocumentAttachmentUUID": {
                "type": "string",
                "format": "uuid",
                "description": "If a signed version of this document exists, references the UUID of the attachment"
              },
              "unsignedDocumentAttachmentUUID": {
                "type": "string",
                "format": "uuid",
                "description": "References the UUID of the unsigned version of this document"
              },
              "signatureDetails": {
                "type": "object",
                "properties": {
                  "signatureText": {
                    "type": "string",
                    "description": "Text entered by the signer as the electronic representation of their signature"
                  },
                  "signatureUnixtime": {
                    "type": "number",
                    "description": "Unixtime at which the document was signed"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Optional additional data regarding the signature event"
                  }
                },
                "required": [
                  "signatureText",
                  "signatureUnixtime"
                ]
              }
            },
            "required": [
              "templateSupportsSignature"
            ]
          }
        }
      },
      "AttachmentCreate": {
        "type": "object",
        "properties": {
          "related_object": {
            "description": "The type of object this attachment is related to (e.g., 'job', 'company', 'staff'). Must be a valid object type. Always stored in lowercase.",
            "type": "string"
          },
          "related_object_uuid": {
            "description": "UUID of the related object to which this attachment belongs. Must be a valid UUID of an existing object of the type specified in the related_object field.",
            "format": "uuid",
            "example": "123e4567-3eaf-4a91-bbce-3d4ad9cd6ed8",
            "type": "string"
          },
          "attachment_name": {
            "description": "Name of the attachment file. Used for display purposes and for naming the file when downloaded. Does not need to include file extension as this is determined by the file_type field.",
            "type": "string"
          },
          "file_type": {
            "description": "File extension including the leading dot (e.g., '.pdf', '.jpg'). Determines how the file is processed and displayed. Always stored in lowercase.",
            "type": "string"
          },
          "attachment_source": {
            "description": "Indicates the source or type of the attachment (e.g., 'INVOICE', 'QUOTE'). Used for filtering and determining how to display the attachment.",
            "type": "string"
          },
          "tags": {
            "description": "Comma-separated list of tags associated with the attachment. Used for categorization and filtering of attachments.",
            "type": "string"
          },
          "lng": {
            "description": "Longitude coordinate where the attachment was created. Used for geolocation of photos and other attachments. Decimal degrees format.",
            "type": "number",
            "format": "float"
          },
          "lat": {
            "description": "Latitude coordinate where the attachment was created. Used for geolocation of photos and other attachments. Decimal degrees format.",
            "type": "number",
            "format": "float"
          },
          "photo_width": {
            "description": "Width of the image in pixels. Only applicable for image attachments. Read-only in the API."
          },
          "photo_height": {
            "description": "Height of the image in pixels. Only applicable for image attachments. Read-only in the API."
          },
          "extracted_info": {
            "description": "Additional information extracted from the file, such as form responses or OCR text. Read-only in the API."
          },
          "is_favourite": {
            "description": "Flag indicating whether this attachment has been marked as a favorite. Used for filtering and displaying attachments. Valid values are [0,1]",
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "class_name": {
            "description": "The specific class type of the attachment. Used for specialized attachment types that extend the base dboAttachment class. Read-only in the API."
          },
          "metadata": {
            "description": "Additional structured data associated with the attachment in JSON format. The schema varies depending on attachment type and source. Used to store extended information that doesn't fit into standard fields."
          },
          "uuid": {
            "format": "uuid",
            "description": "Unique identifier for this record",
            "example": "123e4567-7783-4d54-87c8-d34874ee627c",
            "type": "string"
          },
          "created_by_staff_uuid": {
            "format": "uuid",
            "example": "123e4567-8613-4531-b0d9-30187744a228",
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          }
        }
      },
      "AuthenticationError": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "number",
            "format": "int32",
            "example": 401
          },
          "message": {
            "type": "string",
            "example": "Authentication failed. Please check your API key or OAuth token."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "number",
            "format": "int32",
            "example": 1000
          },
          "message": {
            "type": "string",
            "example": "An error occurred completing your request"
          }
        }
      },
      "ForbiddenError": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "number",
            "format": "int32",
            "example": 403
          },
          "message": {
            "type": "string",
            "example": "Access forbidden. You don't have permission to access this resource."
          }
        }
      },
      "RateLimitError": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "number",
            "format": "int32",
            "example": 429
          },
          "message": {
            "type": "string",
            "example": "Number of allowed API requests per minute exceeded"
          }
        }
      },
      "Result": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "number",
            "format": "int32",
            "example": 0
          },
          "message": {
            "type": "string",
            "example": "OK"
          }
        }
      }
    }
  },
  "x-speakeasy-retries": {
    "strategy": "backoff",
    "backoff": {
      "initialInterval": 500,
      "maxInterval": 60000,
      "maxElapsedTime": 3600000,
      "exponent": 1.5
    },
    "statusCodes": [
      "5XX",
      "429"
    ],
    "retryConnectionErrors": true
  },
  "tags": [
    {
      "name": "Attachments",
      "description": "Operations related to Attachments"
    }
  ]
}
```