# [EXPERIMENTAL] Upsert External Deployment

Create or update an external Deployment. A unique ID (id) is required to identify the Deployment. 
Calling this endpoint with an existing id will update the Deployment.

External Deployments represent work assignments that are managed outside of the Resource Management system.

We don't allow overlap between Deployments for the same Employee or Transport Resource.

Endpoint: PUT /deployment/{id}
Version: 1.27.2
Security: clientCredentials

## Path parameters:

  - `id` (string, required)
    Unique identifier for this external Deployment. Should only contain characters which do not need URL encoding.

## Header parameters:

  - `Prefer` (array)
    The RFC7240 Prefer header indicates that a particular server behavior
is preferred by the client but is not required for successful completion
of the request (see RFC 7240).

The following behavior (see _Examples_) is supported by this API:
* return= is used to suggest the server to
  return using 204 without resource (minimal) or using 200 or 201 with
  resource (representation) in the response body on success.

## Request fields (application/json):

  - `employee` (string, required)
    The business ID of the employee for this deployment.
    Example: "employee-42"

  - `transport_resources` (array, required)
    The business IDs of the transport resources for this deployment.
    Example: ["truck-1","trailer-2"]

  - `start` (object, required)

  - `start.at` (string, required)
    When the deployment starts.
    Example: "2021-01-01T08:00:00Z"

  - `start.location` (object, required)
    Location for the deployment. For external deployments, either address or home_base must be provided, but not both.

  - `start.location.home_base` (object)
    The business_id of a known HomeBase in the system for this deployment location.

  - `start.location.home_base.business_id` (string, required)
    The unique identifier of a HomeBase.
    Example: "depot-1"

  - `start.location.address` (object)
    Address for this deployment location.

  - `start.location.address.name` (string, required)
    A name by which to identify this location. If used as a start_location, this is used for matching colocated entities.
    Example: "Conundra"

  - `start.location.address.address_line` (string)
    The address line of this location's address. Can contain street, house number, bus and more.
    Example: "Voordries 41b"

  - `start.location.address.city` (string)
    The name of the locality of this location.

Required when no geo_point is provided.
    Example: "Oosterzele"

  - `start.location.address.zip_code` (string)
    The ZIP code of the locality of this location.

Required when no geo_point is provided.
    Example: "9860"

  - `start.location.address.country_code` (string)
    The ISO3166-1 alpha-2 two letter country code for this location.

Required when no geo_point is provided.

  - `start.location.address.geo_point` (object)

  - `start.location.address.geo_point.latitude` (number, required)
    Example: 50.9514048

  - `start.location.address.geo_point.longitude` (number, required)
    Example: 3.8067878

  - `end` (object, required)

  - `end.at` (string, required)
    When the deployment ends.
    Example: "2021-01-01T17:00:00Z"

  - `total_break_time` (string, required)
    Total break time during the deployment, formatted as ISO-8601 duration.
    Example: "PT1H"

## Response 201 fields (application/json):

  - `id` (string)
    The unique deployment ID.
    Example: "deployment-123"

  - `resource_combination_id` (string)
    The ID of the associated resource combination, if any.
    Example: "rc-456"

  - `availability_id` (string)
    The ID of the associated availability, if any.
    Example: "avail-789"

  - `employee_id` (string)
    The ID of the employee assigned to this deployment.
    Example: "employee-42"

  - `transport_resource_ids` (array)
    The IDs of the transport resources assigned to this deployment.
    Example: ["truck-1","trailer-2"]

  - `start` (object)

  - `start.at` (string, required)
    When the deployment starts.
    Example: "2021-01-01T08:00:00Z"

  - `start.location` (object, required)
    Location for the deployment. For external deployments, either address or home_base must be provided, but not both.

  - `start.location.home_base` (object)
    The business_id of a known HomeBase in the system for this deployment location.

  - `start.location.home_base.business_id` (string, required)
    The unique identifier of a HomeBase.
    Example: "depot-1"

  - `start.location.address` (object)
    Address for this deployment location.

  - `start.location.address.name` (string, required)
    A name by which to identify this location. If used as a start_location, this is used for matching colocated entities.
    Example: "Conundra"

  - `start.location.address.address_line` (string)
    The address line of this location's address. Can contain street, house number, bus and more.
    Example: "Voordries 41b"

  - `start.location.address.city` (string)
    The name of the locality of this location.

Required when no geo_point is provided.
    Example: "Oosterzele"

  - `start.location.address.zip_code` (string)
    The ZIP code of the locality of this location.

Required when no geo_point is provided.
    Example: "9860"

  - `start.location.address.country_code` (string)
    The ISO3166-1 alpha-2 two letter country code for this location.

Required when no geo_point is provided.

  - `start.location.address.geo_point` (object)

  - `start.location.address.geo_point.latitude` (number, required)
    Example: 50.9514048

  - `start.location.address.geo_point.longitude` (number, required)
    Example: 3.8067878

  - `start.location.address.geo_point.resolved` (object)
    Indicates whether the address is resolved.

  - `start.location.address.geo_point.resolved.geocoded` (boolean)
    Example: true

  - `start.location.address.geo_point.resolved.address` (string)
    Example: "Voordries 31 bus B, 9860 Oosterzele"

  - `start.location.address.geo_point.resolved.precision` (integer)
    Example: 9

  - `end` (object)

  - `end.at` (string, required)
    When the deployment ends.
    Example: "2021-01-01T17:00:00Z"

  - `total_break_time` (string)
    Total break time during the deployment, formatted as ISO-8601 duration.
    Example: "PT1H"

  - `planning_id` (string)
    The ID of the planning that created this deployment, if any.
    Example: "planning-123"

## Response 400 fields (application/problem+json):

  - `title` (string)
    A short, summary of the problem.
    Example: "Validation exception"

  - `detail` (string)
    A detailed explanation specific to this problem.
    Example: "The field contains invalid business formatting."

  - `violations` (array)

  - `violations.field` (string)
    Example: "path.to.field"

  - `violations.message` (string)
    Example: "Field is required"

## Response 404 fields (application/problem+json):

  - `title` (string)
    A short, summary of the problem.
    Example: "Validation exception"

  - `detail` (string)
    A detailed explanation specific to this problem.
    Example: "The field contains invalid business formatting."


## Response 204 fields

## Response 401 fields