openapi: 3.2.0 info: contact: email: hello@arta.io name: Arta url: https://manual.arta.io/ description: The Arta Public API provides quote generation, transport booking, and tracking capabilities. Additionally the API enables Arta partner organizations to configure email and webhook notifications for their accounts. termsOfService: https://www.arta.io/legal/terms title: Arta Public Shipment Exceptions API version: '2021-01-01' servers: - url: https://api.arta.io variables: {} security: [] tags: - name: shipment_exceptions paths: /shipment_exceptions: get: callbacks: {} deprecated: false description: Retrieve a paginated collection of Shipment Exceptions belonging to your Organization operationId: shipmentExceptions/list parameters: - description: Authorize your API calls with an Arta API token example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y in: header name: Authorization required: true schema: type: string x-struct: null x-validate: null - description: Page number of the results to fetch. in: query name: page schema: default: 1 type: integer x-struct: null x-validate: null - description: Results per page (max 50) in: query name: page_size schema: default: 20 type: integer x-struct: null x-validate: null - description: An optional sort order for the returned collection. in: query name: sort required: false schema: enum: - created_at_asc - created_at_desc - updated_at_asc - updated_at_desc type: string x-struct: null x-validate: null responses: '200': content: application/json: schema: properties: items: items: $ref: '#/components/schemas/ShipmentException' type: array x-struct: null x-validate: null metadata: properties: page: example: 1 format: int64 readOnly: true type: integer x-struct: null x-validate: null page_size: example: 20 format: int64 readOnly: true type: integer x-struct: null x-validate: null total_count: example: 1 format: int64 readOnly: true type: integer x-struct: null x-validate: null type: object x-struct: null x-validate: null type: object x-struct: null x-validate: null description: A paginated collection of Shipment Exceptions headers: content-type: example: application/json schema: type: string x-struct: null x-validate: null style: simple x-arta-request-id: description: A unique identifier for the Arta API call example: FkBjuxbwLLTx4RoAARkx schema: type: string x-struct: null x-validate: null style: simple summary: List Shipment Exceptions tags: - shipment_exceptions post: callbacks: {} deprecated: false description: 'Create a Shipment Exception for a Shipment * Clients can create shipment exceptions of a single type currently:`requested_hold_to_collect` * A shipment must have a `pending` or `confirmed` status to create a `requested_hold_to_collect` shipment exception. * `hold_until` date cannot be greater than 30 days from the associated shipment''s `created_at` timestamp.' operationId: shipmentExceptions/create parameters: - description: Authorize your API calls with an Arta API token example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y in: header name: Authorization required: true schema: type: string x-struct: null x-validate: null requestBody: content: application/json: schema: $ref: '#/components/schemas/ShipmentExceptionCreate' required: false responses: '201': content: application/json: schema: $ref: '#/components/schemas/ShipmentException' description: Successful response headers: content-type: example: application/json schema: type: string x-struct: null x-validate: null style: simple x-arta-request-id: description: A unique identifier for the Arta API call example: FkBjuxbwLLTx4RoAARkx schema: type: string x-struct: null x-validate: null style: simple summary: Create Shipment Exception tags: - shipment_exceptions /shipment_exceptions/{shipment_exception_id}: get: callbacks: {} deprecated: false description: Retrieve an existing Shipment Exception operationId: shipmentExceptions/get parameters: - description: Authorize your API calls with an Arta API token example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y in: header name: Authorization required: true schema: type: string x-struct: null x-validate: null - description: shipment_exception_id parameter in: path name: shipment_exception_id required: true schema: type: string x-struct: null x-validate: null responses: '200': content: application/json: schema: $ref: '#/components/schemas/ShipmentException' description: Successful Shipment Exception response headers: content-type: example: application/json schema: type: string x-struct: null x-validate: null style: simple x-arta-request-id: description: A unique identifier for the Arta API call example: FkBjuxbwLLTx4RoAARkx schema: type: string x-struct: null x-validate: null style: simple '404': content: application/json: schema: properties: errors: properties: detail: example: string type: string x-struct: null x-validate: null type: object x-struct: null x-validate: null title: NotFound type: object x-struct: null x-validate: null description: Not Found headers: content-type: example: application/json schema: type: string x-struct: null x-validate: null style: simple x-arta-request-id: description: A unique identifier for the Arta API call example: FkBjuxbwLLTx4RoAARkx schema: type: string x-struct: null x-validate: null style: simple summary: Get a Shipment Exception tags: - shipment_exceptions patch: callbacks: {} deprecated: false description: Update an existing Shipment Exception operationId: shipmentExceptions/update parameters: - description: Authorize your API calls with an Arta API token example: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y in: header name: Authorization required: true schema: type: string x-struct: null x-validate: null - description: shipment_exception_id parameter in: path name: shipment_exception_id required: true schema: type: string x-struct: null x-validate: null requestBody: content: application/json: schema: $ref: '#/components/schemas/ShipmentExceptionUpdate' required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/ShipmentException' description: Successful Shipment Exception response headers: content-type: example: application/json schema: type: string x-struct: null x-validate: null style: simple x-arta-request-id: description: A unique identifier for the Arta API call example: FkBjuxbwLLTx4RoAARkx schema: type: string x-struct: null x-validate: null style: simple '404': content: application/json: schema: properties: errors: properties: detail: example: string type: string x-struct: null x-validate: null type: object x-struct: null x-validate: null title: NotFound type: object x-struct: null x-validate: null description: Not Found headers: content-type: example: application/json schema: type: string x-struct: null x-validate: null style: simple x-arta-request-id: description: A unique identifier for the Arta API call example: FkBjuxbwLLTx4RoAARkx schema: type: string x-struct: null x-validate: null style: simple summary: Update a Shipment Exception tags: - shipment_exceptions components: schemas: ShipmentExceptionUpdate: example: shipment_exception: hold_until: '2023-08-15' status: resolved properties: shipment_exception: properties: hold_until: description: Optionally provide a date to hold collection for the shipment. Values should be in the `YYYY-MM-DD` format. Hold until dates must be fewer than 30 days from the shipment's `created_at` datetime. type: string x-struct: null x-validate: null status: description: The current status for this exception example: resolved type: string x-struct: null x-validate: null type: object x-struct: null x-validate: null required: - shipment_exception title: ShipmentExceptionUpdate type: object x-struct: Elixir.DocsWeb.Schemas.RequestBody.ShipmentExceptionUpdate x-validate: null ShipmentExceptionCreate: example: shipment_exception: hold_until: '2023-08-15' shipment_id: 5baff45a-281d-416e-9310-a4a7c637952e type: requested_hold_to_collect properties: shipment_exception: properties: hold_until: description: Optionally provide a date to hold collection for the shipment. Values should be in the `YYYY-MM-DD` format. Hold until dates must be fewer than 30 days from the shipment's `created_at` datetime. type: string x-struct: null x-validate: null shipment_id: description: The ID for the shipment associated to the shipment exception type: string x-struct: null x-validate: null type: description: The type ID for this resource. Options are defined in the Shipment Exception Types metadata endpoint. Currently, the only accepted type for client-created shipment exceptions is `requested_hold_to_collect`. enum: - requested_hold_to_collect example: requested_hold_to_collect type: string x-struct: null x-validate: null required: - type - shipment_id type: object x-struct: null x-validate: null required: - shipment_exception title: ShipmentExceptionCreate type: object x-struct: Elixir.DocsWeb.Schemas.RequestBody.ShipmentExceptionCreate x-validate: null ShipmentException: example: created_at: '2023-05-26T19:33:19.693833' exception_type_label: null hold_until: null id: d686ad3b-33fd-454c-a7aa-94b1ecbc539f package_id: 4366794 resolution: null shipment_id: a5cbb58c-43ab-4658-9999-98a33b0070d5 source: api status: new type: held_at_customs updated_at: '2023-05-26T19:33:19.693833' properties: created_at: description: A NaiveDatetime-formatted timestamp describing when the exception was created with microsecond precision example: '2024-08-13T22:44:39.593704' format: date-time type: string x-struct: null x-validate: null exception_type_label: description: An additional label providing context about the exception type (optional) nullable: true type: string x-struct: null x-validate: null hold_until: description: The date the shipment will be held until nullable: true type: string x-struct: null x-validate: null id: description: The id of the exception in UUID format format: uuid type: string x-struct: null x-validate: null package_id: description: The package associated with this exception (optional) example: '12345' format: int64 nullable: true type: integer x-struct: null x-validate: null resolution: description: A brief description of the method by which this exception was resolved example: Balance Cleared nullable: true type: string x-struct: null x-validate: null shipment_id: description: The id of the shipment associated with this exception format: uuid type: string x-struct: null x-validate: null source: description: The source of the exception example: arta_team type: string x-struct: null x-validate: null status: description: The current status for this exception enum: - new - in_progress - resolved example: resolved type: string x-struct: null x-validate: null type: description: The type of exception example: prepayment_required type: string x-struct: null x-validate: null updated_at: description: A NaiveDatetime-formatted timestamp describing when the exception was last updated with microsecond precision example: '2024-08-13T22:44:39.593704' format: date-time type: string x-struct: null x-validate: null title: ShipmentException type: object x-struct: Elixir.DocsWeb.Schemas.Response.ShipmentException x-validate: null x-topics: - content: 'The Arta API accepts server-to-server communications authenticated by API keys. Your API keys are self-managed and unique to your organization. Using your API key to authenticate an API call is straightforward. Simply include your API Key token in the Authorization header of every call made to the system. This is the only place that it is accepted.' example: "```shell\n\n$ curl \\ \n\n -X GET https://api.arta.io/shipments \\ \n\n -H \"Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y\"" title: Authentication - content: "Arta imposes rate limits on API requests to maintain system stability and ensure fair usage. If you exceed these limits, the API will return a `429 Too Many Requests` error. Below are the rate limits for both Live and Test modes.\n\n**Live Mode:**\n\n*\tConcurrent requests: 15 API calls at the same time (any type)\n* Instant quote requests: 20 calls per minute\n* Overall requests: 1000 API calls per minute (any type)\n\n**Test Mode:**\n\n* Concurrent requests: 10 API calls at the same time (any type)\n* Instant quote requests: 10 calls per minute\n* Overall requests: 500 API calls per minute (any type)\n\nWhen a rate limit is exceeded, we recommend implementing retry logic with exponential backoff to handle 429 errors effectively." title: Rate Limits - content: 'The Arta API supports flexible search functionality across multiple resources, including Shipments, Requests, Hosted Sessions, Tags, and others. Using the search query parameter, you can construct structured queries to filter results based on specific criteria. Key features of the search functionality include: * Support for negation, wildcards, numeric filters, and date comparisons. * Each search query consists of one or more clauses, where each clause contains a `field`, an operator, and a `value`. * Clauses operating on the same field are combined using OR logic, while clauses across different fields are combined using AND logic. * Use quotation marks to keep multi-word search terms together. This allows for powerful and precise filtering to retrieve the exact data you need from the API. **Syntax and operators** The following table lists the operators and syntax that you can use to construct a search query clause. | Operator | Usage | Description | Examples | |------------|--------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------| | `:` | `field:value` | Exact match operator (case insensitive) | `status:pending` returns records where the status is `pending` | | `*` | `value*` | Use an asterisk (wildcard operator) at the end of a term to match fields that start with the fragment | `art*` returns records that match "arta" and "artist" but not "smart" | | `*` | `*value` | Use an asterisk at the start of a term to match fields that end with the fragment | `*art` returns "smart" but not "martian" | | `-` | `-field:value` | Returns records that don’t match the clause | `-status:pending` returns records that do not have a status of pending | | `>, <, =` | `field:value`, `field:>=value`, `field:<=value` | Greater than/less than operators | `created-at:<=2021-01-01` returns records from the beginning of time through January 1, 2021 | | `..` | `field:value1..value2` | Filters for values within a given range where the first number is the lowest value and the second is the highest | `created-at:2021-05-01..2021-05-15` returns records where the `created_at` field is between May 1, 2021 and May 15, 2021 | **Hosted Session search fields** | Field | Type | |------------|--------------| | `created-at` | date | | `destination-address-line-1` | string | | `destination-city` | string | | `destination-contacts-emails` | string | | `destination-contacts-names` | string | | `destination-contacts-phone-numbers` | string | | `destination-country` | string | | `destination-postal-code` | string | | `destination-region` | string | | `insurance` | string | | `internal-reference` | string | | `object-creators` | string | | `object-descriptions` | string | | `object-internal-references` | string | | `object-public-references` | string | | `object-titles` | string | | `origin-address-line-1` | string | | `origin-city` | string | | `origin-contacts-emails` | string | | `origin-contacts-names` | string | | `origin-contacts-phone-numbers` | string | | `origin-country` | string | | `origin-postal-code` | string | | `origin-region` | string | | `public-reference` | string | | `quote-type` | string | | `shipping-notes` | string | | `shortcode` | string | | `status` | string | | `type` | string | | `tags` | string | **Request search fields** | Field | Type | |------------|--------------| | `bookable` | string | | `created-at` | date | | `destination-address-line-1` | string | | `destination-city` | string | | `destination-contacts-emails` | string | | `destination-contacts-names` | string | | `destination-contacts-phone-numbers` | string | | `destination-country` | string | | `destination-postal-code` | string | | `destination-region` | string | | `hosted-session` | string | | `internal-reference` | string | | `object-creators` | string | | `object-descriptions` | string | | `object-internal-references` | string | | `object-public-references` | string | | `object-titles` | string | | `origin-address-line-1` | string | | `origin-city` | string | | `origin-contacts-emails` | string | | `origin-contacts-names` | string | | `origin-contacts-phone-numbers` | string | | `origin-country` | string | | `origin-postal-code` | string | | `origin-region` | string | | `public-reference` | string | | `quote-type` | string | | `shipping-notes` | string | | `shortcode` | string | | `status` | string | | `tags` | string | **Shipment search fields** | Field | Type | |------------|--------------| | `created-at` | date | | `destination-address-line-1` | string | | `destination-city` | string | | `destination-contacts-emails` | string | | `destination-contacts-names` | string | | `destination-contacts-phone-numbers` | string | | `destination-country` | string | | `destination-postal-code` | string | | `destination-region` | string | | `eei-form-status` | string | | `hosted-session` | string | | `internal-reference` | string | | `object-creators` | string | | `object-descriptions` | string | | `object-internal-references` | string | | `object-public-references` | string | | `object-titles` | string | | `origin-address-line-1` | string | | `origin-city` | string | | `origin-contacts-emails` | string | | `origin-contacts-names` | string | | `origin-contacts-phone-numbers` | string | | `origin-country` | string | | `origin-postal-code` | string | | `origin-region` | string | | `public-reference` | string | | `quote-type` | string | | `request-shortcode` | string | | `shipping-notes` | string | | `shortcode` | string | | `status` | string | | `tags` | string | | `total` | numeric | | `total-currency` | string | | `tracking-numbers` | string | **Tag search fields** | Field | Type | |------------|--------------| | `color` | string | | `description` | string | | `is_active` | string | | `name` | string | ' title: Search