# Create or replace a twin.

Endpoint: PUT /twins
Version: v3
Security: oauth2

## Request fields (application/json):

  - `id` (string, required)
    The unique Id of the digital twin.
    Example: "TW-DD-II-L01"

  - `modelId` (string, required)
    Digital Twin Model Identifier.
    Example: "dtmi:com:willowinc:Level;1"

  - `lastUpdateTime` (string,null)
    Timestamp when the twin was last updated in ISO 8601 format.
    Example: "2024-08-30T03:49:30.4062816+00:00"

  - `contents` (object)
    This field will contain properties and components as defined in the contents section of the DTDL definition of the twin.
    Example: {"levelNumber":0,"mappedIds":[{"exactType":"ExternalIdentity","scope":"CONNECTOR","scopeId":"CONxxxxxxxxxxx","value":"TW-CC-II-L01"},{"exactType":"FloorLevelIdentity","scope":"BUILDING","scopeId":"BLDGxxxxxxxxxxxxxxx","value":"0"},{"exactType":"ExternalIdentity","scope":"ORG","scopeId":"ORG2xxxxxxxxxxx","value":"urn:willowinc:twin:id:TW-DD-II-L01"}],"name":"Floor_1","uniqueID":"a360cf30-c112-40a1-b4b4-f65da82fa9e8","externalID":"FLRPXxxxxxxxxxxxxxxxx","code":"L01","siteID":"104bd33c-a697-4027-b6a6-677e30a53d09","alternateClassification":{"brickSchema":{"version":"1.3","code":"dtmi:org:brickschema:schema:Brick:Floor;1"}},"externalIds":{"mappingKey":"msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"},"area":{"$metadata":{"$lastUpdateTime":"2024-08-30T03:49:30.4062816Z"}}}

## Response 200 fields (application/json):

  - `id` (string, required)
    The unique Id of the digital twin.
    Example: "TW-DD-II-L01"

  - `modelId` (string, required)
    Digital Twin Model Identifier.
    Example: "dtmi:com:willowinc:Level;1"

  - `lastUpdateTime` (string,null)
    Timestamp when the twin was last updated in ISO 8601 format.
    Example: "2024-08-30T03:49:30.4062816+00:00"

  - `contents` (object)
    This field will contain properties and components as defined in the contents section of the DTDL definition of the twin.
    Example: {"levelNumber":0,"mappedIds":[{"exactType":"ExternalIdentity","scope":"CONNECTOR","scopeId":"CONxxxxxxxxxxx","value":"TW-CC-II-L01"},{"exactType":"FloorLevelIdentity","scope":"BUILDING","scopeId":"BLDGxxxxxxxxxxxxxxx","value":"0"},{"exactType":"ExternalIdentity","scope":"ORG","scopeId":"ORG2xxxxxxxxxxx","value":"urn:willowinc:twin:id:TW-DD-II-L01"}],"name":"Floor_1","uniqueID":"a360cf30-c112-40a1-b4b4-f65da82fa9e8","externalID":"FLRPXxxxxxxxxxxxxxxxx","code":"L01","siteID":"104bd33c-a697-4027-b6a6-677e30a53d09","alternateClassification":{"brickSchema":{"version":"1.3","code":"dtmi:org:brickschema:schema:Brick:Floor;1"}},"externalIds":{"mappingKey":"msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"},"area":{"$metadata":{"$lastUpdateTime":"2024-08-30T03:49:30.4062816Z"}}}

## Response 400 fields (application/json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)