Skip to main content

Create and manage tasks

Tasks record work to be completed, who is responsible and when it is due. An integration can create a task for a residential deal or contact group, read it by ID, and update its attributes and progress.

Access and identifiers​

OperationScope example
Read a taskapi.tasks.read
Create a taskapi.tasks.create
Update a taskapi.tasks.update

Broader applicable scopes also work. Send a bearer token, a permitted adviser contact ID in UserId, and Accept: application/vnd.api+json on task requests. Writes also need Content-Type: application/vnd.api+json. Task reads require valid adviser context as well as access to the task.

An assignee ID comes from the advisers resource, for example data[].id from search advisers. It is an adviser family ID, distinct from the adviser contact ID sent in UserId. A task also has its own ID; neither a deal ID nor a contact-group ID can replace it. The assignee and linked records must be accessible to your application.

Create a residential-deal task​

Replace the example IDs with an accessible assignee and residential deal. Supply a due date with an explicit time-zone offset when the task needs one.

POST {API_BASE_URL}/jsonapi/tasks
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
"data": {
"type": "tasks",
"attributes": {
"title": "Follow up on outstanding application details",
"detail": "Confirm the documents needed for the application.",
"progress": "NotStarted",
"priority": "Normal",
"dueDate": "2026-11-02T09:00:00+10:00"
},
"relationships": {
"assignee": { "data": { "type": "advisers", "id": "3001" } },
"residentialDeal": { "data": { "type": "deals", "id": "5001" } }
}
}
}

A successful POST returns 201 Created. Save the returned data.id for later reads and updates. The assignee is required.

Create a contact-group task​

Use the same POST endpoint and headers with this body. The contactGroups relationship is an array of contact-group identifiers, rather than individual contact IDs. A task with one contact-group link and no deal links can later be promoted to a deal task.

{
"data": {
"type": "tasks",
"attributes": {
"title": "Arrange a follow-up with the contact group",
"detail": "Confirm the preferred appointment time.",
"progress": "NotStarted",
"priority": "Normal",
"dueDate": "2026-11-03T09:00:00+10:00"
},
"relationships": {
"assignee": { "data": { "type": "advisers", "id": "3001" } },
"contactGroups": {
"data": [{ "type": "contact-groups", "id": "4001" }]
}
}
}
}

Read a task and select fields​

Retrieve a saved task by its own ID. To request only its title, progress and due date:

GET {API_BASE_URL}/jsonapi/tasks/7001?fields[tasks]=title,progress,dueDate
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json

Omit fields[tasks] to read all available task fields. Add relationship names to the fieldset when you need their identifiers. Sparse fieldsets can also shape POST and PATCH responses; they do not choose which attributes are written.

Use the task's returned relationship identifiers to retrieve other resources, or follow a supported related-resource endpoint. For example, read a task's residential deal returns related resource data, while read its residential-deal linkage returns the identifier. Seeing a task does not grant access to every linked record.

The examples here fetch related details separately; they do not rely on include to populate a task response. For asset or commercial finance, use the linked ID with the corresponding asset finance or commercial finance member endpoint to retrieve the full public summary.

Update attributes and progress​

PATCH uses type: "tasks" and an ID matching the URL. Send only the fields to change; omitted attributes retain their values.

PATCH {API_BASE_URL}/jsonapi/tasks/7001
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
"data": {
"type": "tasks",
"id": "7001",
"attributes": {
"title": "Confirm the remaining application documents",
"detail": "Client has supplied the first set of documents.",
"progress": "InProgress"
}
}
}

For a progress-only update, send only progress inside attributes using the same envelope and headers.

FieldSupported values or constraint
progressNotStarted, InProgress, OnHold, Completed, NotRequired
priorityNormal, Medium, High, Critical
titleRequired on creation; non-empty and at most 500 characters when supplied
detailPlain text or safe HTML, up to 10 KiB of UTF-8 text
dueDateDate and time with an explicit offset; send null to clear it

These updates work for both residential-deal and contact-group tasks. A successful PATCH may return 200 OK with a resource or 204 No Content. Read the task again when you need to confirm the saved values; this requires read scope as well as update scope.

Promote a contact task to a deal task​

A task can move from a contact group to a residential deal when it has exactly one existing contact-group link and no existing deal links. Supply one new deal relationship through the main PATCH endpoint:

PATCH {API_BASE_URL}/jsonapi/tasks/7002
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
"data": {
"type": "tasks",
"id": "7002",
"relationships": {
"residentialDeal": { "data": { "type": "deals", "id": "5002" } }
}
}
}

Omit contactGroups from this request. The supported transition removes the contact-group link and adds the deal link. Read the result to confirm relationships.residentialDeal.data.id and an empty relationships.contactGroups.data array.

This is a one-time transition, not a general way to reassign tasks between deals or replace their links. Other link-change combinations can leave the existing links unchanged, so check persisted state rather than treating a successful HTTP response as proof that a relationship changed.

Supported operations​

The API exposes task creation, reads by ID, updates and supported relationship reads. It does not expose collection searches (GET /jsonapi/tasks), task deletion or relationship-only POST/PATCH/DELETE operations. Submit supported relationship changes through PATCH /jsonapi/tasks/{id}.

For runnable examples and the order in which samples share saved IDs, see the C# task samples.