--- title: "Create Upload URLs" url: "https://stage-api-docs.centraldispatch.com/apis/stage-dispatch-document-api-1-0-0/versions/37a28be1-2b73-47a5-9171-d6fcf5977ad4/operations/postUploadUrls" --- > Full API specification: https://stage-api-docs.centraldispatch.com/apis/stage-dispatch-document-api-1-0-0/versions/37a28be1-2b73-47a5-9171-d6fcf5977ad4.md # Create Upload URLs `POST` `/dispatch-documents/upload-urls` Operation ID: `postUploadUrls` Get a temporary URL (or URLs) to upload a document. #### 📝 Important Notes - The URL is temporary and will expire after a short period. - Use the URL with a standard HTTP PUT request to upload the document. - Requires either dispatchId or listingId, both must not be provided in the same request. #### Example using the returned URL ```bash curl {uploadUrl} --upload-file {filename} ``` ## Header parameters - `Content-Type` (string, required) - The major version of the API to make a request against. This is a custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to `application/vnd.coxauto.v1+json`. ## Request body (required) Content types: `application/json` ## Responses - `200` - OK. Successful request. - `400` - Bad Request. Check the request payload. **Scenarios:** - Invalid `dispatchId` format. - Invalid request body structure. - Validation error. - `401` - Unauthorized. Authentication failed or missing. - `403` - Forbidden. The attempted action is not permitted. - `404` - Not Found. **Scenarios:** - `dispatchId` not found. - `422` - Unprocessable Entity. Errors found in the request. **Scenarios:** - Both `dispatchId` and `listingId` provided (mutually exclusive). - Neither `dispatchId` nor `listingId` provided (at least one required). - `fileName`not supplied. - `documents` array not supplied. - `429` - Too Many Requests. Rate limit exceeded. - `500` - Error. - `503` - Service Unavailable. Temporary service interruption. ## OpenAPI definition ````yaml openapi: 3.0.1 info: title: Dispatch Document API version: 1.0.0 servers: - url: https://document-api.centraldispatch.com description: Production server paths: /dispatch-documents/upload-urls: post: tags: - Dispatch Document summary: Create Upload URLs description: >- Get a temporary URL (or URLs) to upload a document. #### 📝 Important Notes - The URL is temporary and will expire after a short period. - Use the URL with a standard HTTP PUT request to upload the document. - Requires either dispatchId or listingId, both must not be provided in the same request. #### Example using the returned URL ```bash curl {uploadUrl} --upload-file {filename} ``` operationId: postUploadUrls parameters: - name: Content-Type in: header description: The major version of the API to make a request against. This is a custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to `application/vnd.coxauto.v1+json`. required: true schema: type: string example: application/vnd.coxauto.v1+json requestBody: description: "`CreateUploadUrlsRequest`" content: application/json: schema: $ref: "#/components/schemas/CreateUploadUrlsRequest" examples: sample single: value: dispatchId: d159acc0-e89b-12d3-a456-426614174000 listingId: "42220470" documents: - displayName: Example document parentId: dad00000-e89b-12d3-a456-426614174000 fileName: example.txt sample multiple: value: dispatchId: d159acc0-e89b-12d3-a456-426614174000 documents: - fileName: Document.pdf - displayName: Example document parentId: dad00000-e89b-12d3-a456-426614174000 fileName: example.txt required: true responses: "200": description: OK. Successful request. headers: X-CoxAuto-Media-Type: description: Contains the major version and format information. schema: type: string example: coxauto.v1; format=json content: application/json: schema: $ref: "#/components/schemas/UploadUrlCollection" "400": description: |- Bad Request. Check the request payload. **Scenarios:** - Invalid `dispatchId` format. - Invalid request body structure. - Validation error. content: application/json: schema: $ref: "#/components/schemas/Errors" "401": description: Unauthorized. Authentication failed or missing. "403": description: Forbidden. The attempted action is not permitted. "404": description: |- Not Found. **Scenarios:** - `dispatchId` not found. content: application/json: schema: $ref: "#/components/schemas/EmptyResponse" "422": description: >- Unprocessable Entity. Errors found in the request. **Scenarios:** - Both `dispatchId` and `listingId` provided (mutually exclusive). - Neither `dispatchId` nor `listingId` provided (at least one required). - `fileName`not supplied. - `documents` array not supplied. content: application/json: schema: $ref: "#/components/schemas/Errors" "429": description: Too Many Requests. Rate limit exceeded. "500": description: Error. content: application/json: schema: $ref: "#/components/schemas/Errors" "503": description: Service Unavailable. Temporary service interruption. security: - Bearer: [] security: - Bearer: [] components: schemas: CreateUploadUrlsRequest: type: object properties: dispatchId: type: string description: The ID of the dispatch to associate the document with. Required if `listingId` is null. Not allowed if `listingId` is provided. format: uuid nullable: true example: d159acc0-e89b-12d3-a456-426614174000 listingId: type: string description: The ID of the listing to associate the document with. Required if `dispatchId` is null. Not allowed if `disptachId` is provided. nullable: true example: "42220470" documents: type: array items: $ref: "#/components/schemas/UploadUrlRequest" description: Details of the documents to be uploaded. description: Details of the request body to retrieve presigned URLs for document upload. UploadUrlCollection: type: object properties: documents: type: array items: $ref: "#/components/schemas/UploadUrlsResponse" description: A collection of presigned URLs. description: Details of the upload URL response. Errors: type: object properties: errors: type: array items: $ref: "#/components/schemas/Error" description: A collection of errors. nullable: true description: An error occurred, and the request could not be completed. EmptyResponse: type: object description: No response. UploadUrlRequest: type: object properties: fileName: type: string description: The actual file name of the document including the file extension. example: example.txt parentId: type: string description: The parent resource of the document if not only the dispatch ID or listing ID. If the document pertains to a vehicle (bill, inspection document, etc.) it will be the vehicle ID. format: uuid nullable: true example: dad00000-e89b-12d3-a456-426614174000 displayName: type: string description: The display name of the document. If not provided, `fileName` will be used. nullable: true example: Example document description: Details of the upload URL request. UploadUrlsResponse: type: object properties: fileName: type: string description: The actual file name of the document including the file extension. example: example.txt uploadUrl: type: string description: The fully qualified URL to which the document should be uploaded. example: https://dispatch-scan.amazonaws.com/a3aef90b-4708-44ff-8a27-5c8e2ac5d151/0079a34f-f831-4ed3-965d-2ec896d03360?X-Amz-Expires=86400&X-Amz-Security-Token=IQoJb3JpZ2luX2VjELj%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQDycNVhEDtpB1MpoRav6%2FBm8CJ5kjwWOrZrcn3TM0CZrgIhALl8E%2BIPf2L035ePqKRkGrnsne4sfPD0v9YM%2FzUiFAAzKoIECMH%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQAhoMMjc3Mjg0MTQ2OTU1IgyfSbrc16Ybau2dws4q1gMz%2BWHFdTqcha%2BRgWLuucTuDY%2FDUmaq9MW9%2BX2wg61tJG2x4GRGae%2FlGjcP65KykEpFBP2qIjHOmSYDqfBhKC0BJNiTLBTWgvtJg4%2FsAdP2rMiKF3cn%2BuWe2ZbRsGYrqecsdvgnNgqjEa7jJ4dWvl4iWDCkgWDUtZku3bPBkFxvBwb%2FMW2h87y82HWQ2LHY5jXV%2BAxG5BHumMD4tZgUpLyb12V8Dji8nug8UtasgBJMIpVcVOoJqlXRn277hBZrgsyfRu4Yywgr596LYtKMejL4etpXutrowDy9wrrzap75DuZdTBssYT2fkkcB9crKkCVk85znpb0Wc83nxZU3wIKQqKoPJO9EExBYE%2FgiCEoKcVan5P9PZUwq2HaiRvENmhLNmCBUHk6HtqtZ%2Bi%2FSii%2BCZjOfeW5VZT9kOstERlxLXpedbhdDQ5fGauAPUNrsV0PbShPW8P%2F%2F0hQocbwN5KYMCr4Tm9Ca9LKQMDk8%2FdyIo13fCyUQcbMiJ6Wr9Vaq0WiVrvFFPFYN0Iaq58xnIvfq9xNtNTRAroaqRsLkDs2XIGrPuJWihXy4EJeju6GkKUtQ4VQXdasJM9I6W457zkrNIWkmpobzeF%2FtIQBFVKDObtVGY7WIWzC82vO8BjqkAdAAENKGjkI4KdfxF7NVnBhy53raffoYPTHsbBr2h2g685PfDHzUY3Qs8gvItv521NslLcG0GplWmofphdwhZPT55Y01GiaiuwKFho1XQIIfnwkgDCZtjkPPrlyuOIdcLCqZE8IEb%2FbkeM9QoyttKzb7J%2Fi8HXFAcZDKunkbCwaTtLEmR0As9gIaYBY3Ra47IZr2d4rprhEGXPPI2jK6bdJEG1U6&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAUBD3MJ4F7BVYHI74/20250131/us-east-1/s3/aws4_request&X-Amz-Date=20250131T194251Z&X-Amz-SignedHeaders=host&X-Amz-Signature=7d5e80a5f1e25f7a31b88dabeca478faae5feb3db4d1e2433f160a9f2a408df1 expiresUtc: type: string description: The expiration date and time of the URL, in UTC/ISO 8601 format. example: 2025-11-05T20:45:37.284Z description: Details of the upload URL response. Error: type: object properties: code: type: string description: The code used for the issue. nullable: true example: resource.issue_type message: type: string description: A detailed message. nullable: true example: The issue happened because something is wrong. property: type: string description: The property to which the issue is associated. nullable: true example: person properties: type: object additionalProperties: type: string description: Additional properties related to the issue. nullable: true example: firstName: D0nn@ lastName: Sm!th description: Details of an error or issue. securitySchemes: Bearer: type: http scheme: Bearer ````