Last updated Jul 16, 2025

Work item

The Work item object type represents a work item object. atlassian:work-item should be used to ingest work item-specific fields.

Payload structure

1
2
  objects {}
  ├─ schemaVersion (string) [Required]
  ├─ id (string) [Required]
  ├─ updateSequenceNumber (long) [Required]
  ├─ displayName (string) [Required]
  ├─ description (string) [Optional]
  ├─ url (string) [Required]
  ├─ createdAt (Instant (ISO8601 / RFC3339)) [Required]
  └─ createdBy [] [Optional]
      ├─ accountId (string)
      └─ ari (string)
  └─ lastUpdatedAt (Instant (ISO8601 / RFC3339)) [Required]
  └─ lastUpdatedBy [] [Required]
      ├─accountId (string)
      └─ ari
  └─ permissions 
      └─ accessControls
         └─ principals
            └─type
  └─ associations [] [Optional]
      ├─ associationType (string)
      └─ values []
      
  atlassian:work-item
  ├─ dueDate (string) [Optional]
  ├─ assignee [] [Optional]
      ├─ accountId (string) [Optional]
      ├─ email (string) [Optional]
      ├─ externalId (string) [Optional]
      ├─ ari (string) [Optional]
      ├─ name (string) [Optional]
      ├─ userName (string) [Optional]
      ├─ avatar (string) [Optional]
      └─ url (string) [Optional]
  ├─ workItemProject (WorkItemProject) [Optional]
      ├─ id (string) [Required]
      ├─ name (string) [Required]
  ├─ collaborators (List<UserReference>) [Optional]
      ├─ accountId (string) [Optional]
      ├─ email (string) [Optional]
      ├─ externalId (string) [Optional]
      ├─ ari (string) [Optional]
      ├─ name (string) [Optional]
      ├─ userName (string) [Optional]
      ├─ avatar (string) [Optional]
      └─ url (string) [Optional]
  ├─ exceedsMaxCollaborators (boolean) [Optional]
  ├─ status (string) [Optional]
  ├─ subtype (string) [Optional]
  ├─ attachments (List<Attachment>) [Optional]
      ├─ url (string) [Required]
      ├─ thumbnailUrl (string) [Optional]
      ├─ title (string) [Required]
      ├─ mimeType (string) [Optional]
      └─ byteSize (integer) [Optional]
  └─ team (string) [Optional]

Common properties

Property	Type	Required	Description
`schemaVersion`	`string`	Yes	The schema version of the object.
`id`	`string`	Yes	The ID of the object in the source system.
`updateSequenceNumber`	`long`	Yes	A sequence number to compare when writing to the database. Objects are written following a last write wins strategy, therefore an object with a greater `UpdateSequenceNumber` is considered a more recently updated object.
`displayName`	`string`	Yes	The display name of the object.
`description`	`string`	No	The description of the object.
`url`	`string`	Yes	The URL from the provider which the object is accessible from.
`createdAt`	`string`	Yes	The date the object was created. Format: Instant (ISO8601 / RFC3339)
`createdBy`	`user`	No	The user that created the object. See User to learn more.
`lastUpdatedAt`	`string`	Yes	The date the object was last updated. Format: Instant (ISO8601 / RFC3339)
`lastUpdatedBy`	`user`	No	The user that last updated the object. See User to learn more.
`owners`	`list<User>`	No	List of users that own the object.
`thumbnail`	`thumbnail`	No	The thumbnail of the object. See Thumbnail to learn more.
`parentKey`	`entityKey`	No	The ID of the parent object. If null, it is a standalone object. See Entity key to learn more.
`containerKey`	`entityKey`	No	The container identifier that this object belongs to. See Entity key to learn more.
`permissions`	`list<Permissions>`	Yes	The permissions configuration of the object. See Permissions to learn more.
`associations`	`association`	No	List of objects associated with the object. Generally used to link an external object to a Atlassian object. See Association to learn more.

Work item properties

Property	Type	Required	Description
`dueDate`	`string`	No	The due date for the work item. Format: Instant (ISO8601 / RFC3339)
`assignee`	`UserReference`	No	The person assigned to work on this item.
`workItemProject`	`WorkItemProject`	No	The project associated with this work item.
`workItemProject.id`	`string`	Yes	The unique identifier of the project.
`workItemProject.name`	`string`	Yes	The name of the project.
`collaborators`	`List<UserReference>`	No	List of collaborators working on this item.
`collaborators.accountId`	`string`	No	The account ID of the collaborator.
`collaborators.email`	`string`	No	The email address of the collaborator.
`collaborators.externalId`	`string`	No	The external ID of the collaborator.
`collaborators.ari`	`string`	No	The Atlassian Resource Identifier (ARI) of the collaborator.
`collaborators.name`	`string`	No	The name of the collaborator.
`collaborators.userName`	`string`	No	The username of the collaborator.
`collaborators.avatar`	`string`	No	The avatar URL of the collaborator.
`collaborators.url`	`string`	No	The URL of the collaborator.
`exceedsMaxCollaborators`	`boolean`	No	Whether the number of collaborators exceeds the maximum limit.
`status`	`string`	No	The current status of the work item.
`subtype`	`string`	No	The subtype of the work item. Allowed values: `task` `default_task` `work_item` `epic` `bug` `story` `milestone` `section` `approval` `problem` `question` `incident` `issue` `other`
`attachments`	`List<Attachment>`	No	List of attachments for the work item.
`attachments.url`	`string`	Yes	The URL to access the attached file.
`attachments.thumbnailUrl`	`string`	No	The URL for the thumbnail of the attachment.
`attachments.title`	`string`	Yes	The title or name of the attachment.
`attachments.mimeType`	`string`	No	The MIME type of the attachment.
`attachments.byteSize`	`integer`	No	The size of the attachment in bytes.
`team`	`string`	No	The team associated with the work item.

Example payload

1
2
{
  "objects" : [ {
    "id" : "work-item-1",
    "updateSequenceNumber" : 1,
    "description" : "Fix login issue",
    "url" : "https://work-item.example.com/item/1",
    "displayName" : "Work Item Name",
    "createdAt" : "2024-04-16T09:31:32+00:00",
    "createdBy" : {
      "email" : "e-mail@user1.com",
      "externalId" : "external-id-1",
      "name" : "John Smith",
      "avatar" : "https://work-item.example.com/avatar/31"
    },
    "lastUpdatedAt" : "2024-04-16T09:31:32+00:00",
    "lastUpdatedBy" : {
      "email" : "e-mail@user1.com",
      "externalId" : "external-id-1",
      "name" : "John Smith",
      "avatar" : "https://work-item.example.com/avatar/31"
    },
    "permissions" : [ {
      "action" : "read",
      "accessControls" : [ {
        "principals" : [ {
          "type" : "EVERYONE"
        } ]
      } ]
    } ],
    "containerKey" : {
      "type" : "atlassian:space",
      "value" : {
        "entityId" : "CFG3W7TKJ"
      }
    },
    "atlassian:work-item" : {
      "dueDate" : "2024-05-01T12:00:00+00:00",
      "assignee" : {
        "email" : "e-mail@user1.com",
        "externalId" : "external-id-1",
        "name" : "John Smith",
        "avatar" : "https://work-item.example.com/avatar/31"
      },
      "project" : {
        "id" : "project-1",
        "name" : "Project A"
      },
      "collaborators" : [ {
        "email" : "e-mail@user1.com",
        "externalId" : "external-id-1",
        "name" : "John Smith",
        "avatar" : "https://work-item.example.com/avatar/31"
      } ],
      "exceedsMaxCollaborators" : false,
      "status" : "In Progress",
      "subtype" : "work_item",
      "attachments" : [ {
        "url" : "https://example.com/files/attachment1.png",
        "mimeType" : "image/png",
        "byteSize" : 204800
      } ],
      "team" : "Engineering Team"
    }
  } ],
  "operationType" : "NORMAL"
}