The Contact object represents a contact who receives the notifications. Contact can be linked to a user in the platform. Each contact can manage its notification preferences at the category level.
This object contains the following attributes:
id
string, core
(Read-only) A primary identifier for the contact.
href
string, core
(Read-only) A relative reference to the object.
name
string, core
The display name of the contact.
email
string, core
The email address of the contact.
user
object, core
(Read-only) Indicates if the email belongs to a registered on the platform.
Example:
optOuts
object
Represents the object, containing the list of notification categories the contact has chosen to opt out of. By default, a contact is opted into all published categories.
Example:
status
enum
Indicates the status. Allowed values are active
or blocked.
audit
object
(Read-only) Represents the object.
{
"id": "CTT-1234-9876-1234",
"href": "/v1/notifications/contacts/CTT-1234-9876-1234",
"name": "Will Smith",
"email": "will.smith@softwareone.com",
"user": {
"id": "USR-3773-5838",
"href": "/accounts/users/USR-1234-9876",
"name": "Will Smith",
"email": "will.smith@softwareone.com"
},
"optOuts": [
{
"id": "NTC-1234-9876",
"href": "/notifications/categories/NTC-1234-9876",
"name": "Orders",
"shortDescription": "Orders"
}
],
"status": "Active",
"audit": {
"created": {
"at": "2023-12-14T17:28:57Z",
"by": {
"id": "UR-1234-1234-1234",
"name": "John Smith",
"icon": "/static/users/UR-1234-1234-1234.icon.svg"
},
"of": {
"id": "ACC-1234-1234",
"href": "/accounts/accounts/ACC-1234-1234",
"name": "Microsoft",
"icon": "/static/ACC-1234-1234/account.png"
}
}
}
}{
"id": "USR-3773-5838",
"href": "/accounts/users/USR-1234-9876",
"name": "Will Smith",
"email": "will.smith@softwareone.com"
}[
{
"id": "NTC-1234-9876",
"href": "/notifications/categories/NTC-1234-9876",
"name": "Orders",
"shortDescription": "Orders"
}
]The following diagram shows the state (status) transition process of a contact on the platform.
New
This is the initial status for a new contact.
Active
A contact in this state can receive emails from the platform, depending on their preferences.
Blocked
A contact in this state will not receive the email, but the platform will generate a message.
Deleted
Deleted contacts cannot be used for notifications.
Supports RQL filtering, sorting, and pagination via query string parameters.
OK
Gets or sets the description of the category.
Gets or sets the timestamp of when this category was last used to send a notification.
Bad Request
GET /public/v1/notifications/contacts HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
{
"$meta": {
"pagination": {
"offset": 1,
"limit": 1,
"total": 1
},
"omitted": [
"text"
]
},
"data": [
{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"activated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"blocked": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"deleted": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"revision": 1,
"name": "text",
"blockedReason": "text",
"email": "text",
"status": "text",
"identity": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1
},
"directories": [
{
"id": "text",
"revision": 1
}
],
"chat": true,
"optOuts": [
{
"id": "text",
"name": "text",
"revision": 1,
"description": "text",
"lastUsed": "2026-01-01T00:00:00.000Z"
}
],
"user": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"invitationAcceptedAt": "2026-01-01T00:00:00.000Z"
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1,
"email": "text",
"status": "text",
"phone": {
"prefix": "text",
"number": "text"
},
"firstName": "text",
"lastName": "text",
"lastLoginAt": "2026-01-01T00:00:00.000Z",
"settings": {
"cultureCode": "text",
"dateFormat": "text",
"languageCode": "text",
"numberFormat": {
"decimalSeparator": "text",
"groupSeparator": "text"
},
"timeFormat": "text",
"timeZone": "text",
"optOuts": {
"objectTypes": [
"text"
]
}
},
"accounts": [
{
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
],
"currentAccount": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
}
}
]
}Creates a new contact with the provided email address. Contacts can then be subscribed to categories.
Created
Represents a notification contact who can receive email notifications.
Gets or sets the description of the category.
Gets or sets the timestamp of when this category was last used to send a notification.
Bad Request
POST /public/v1/notifications/contacts HTTP/1.1
Host: api.platform.softwareone.com
Content-Type: application/json
Accept: */*
Content-Length: 98
{
"email": "text",
"optOuts": [
{
"id": "text"
}
],
"name": "text",
"directories": [
{
"id": "text"
}
],
"chat": true
}{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"activated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"blocked": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"deleted": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"revision": 1,
"name": "text",
"blockedReason": "text",
"email": "text",
"status": "text",
"identity": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1
},
"directories": [
{
"id": "text",
"revision": 1
}
],
"chat": true,
"optOuts": [
{
"id": "text",
"name": "text",
"revision": 1,
"description": "text",
"lastUsed": "2026-01-01T00:00:00.000Z"
}
],
"user": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"invitationAcceptedAt": "2026-01-01T00:00:00.000Z"
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1,
"email": "text",
"status": "text",
"phone": {
"prefix": "text",
"number": "text"
},
"firstName": "text",
"lastName": "text",
"lastLoginAt": "2026-01-01T00:00:00.000Z",
"settings": {
"cultureCode": "text",
"dateFormat": "text",
"languageCode": "text",
"numberFormat": {
"decimalSeparator": "text",
"groupSeparator": "text"
},
"timeFormat": "text",
"timeZone": "text",
"optOuts": {
"objectTypes": [
"text"
]
}
},
"accounts": [
{
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
],
"currentAccount": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
}
}Blocks the contact, preventing them from receiving any notifications until unblocked.
The Contact ID.
OK
Represents a notification contact who can receive email notifications.
Gets or sets the description of the category.
Gets or sets the timestamp of when this category was last used to send a notification.
Bad Request
POST /public/v1/notifications/contacts/{id}/block HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"activated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"blocked": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"deleted": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"revision": 1,
"name": "text",
"blockedReason": "text",
"email": "text",
"status": "text",
"identity": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1
},
"directories": [
{
"id": "text",
"revision": 1
}
],
"chat": true,
"optOuts": [
{
"id": "text",
"name": "text",
"revision": 1,
"description": "text",
"lastUsed": "2026-01-01T00:00:00.000Z"
}
],
"user": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"invitationAcceptedAt": "2026-01-01T00:00:00.000Z"
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1,
"email": "text",
"status": "text",
"phone": {
"prefix": "text",
"number": "text"
},
"firstName": "text",
"lastName": "text",
"lastLoginAt": "2026-01-01T00:00:00.000Z",
"settings": {
"cultureCode": "text",
"dateFormat": "text",
"languageCode": "text",
"numberFormat": {
"decimalSeparator": "text",
"groupSeparator": "text"
},
"timeFormat": "text",
"timeZone": "text",
"optOuts": {
"objectTypes": [
"text"
]
}
},
"accounts": [
{
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
],
"currentAccount": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
}
}Returns the resource with the specified ID. Use the select query parameter to specify which fields to include.
The resource ID.
Optional RQL select statement to filter fields.
OK
Represents a notification contact who can receive email notifications.
Gets or sets the description of the category.
Gets or sets the timestamp of when this category was last used to send a notification.
Bad Request
Not Found
GET /public/v1/notifications/contacts/{id} HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"activated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"blocked": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"deleted": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"revision": 1,
"name": "text",
"blockedReason": "text",
"email": "text",
"status": "text",
"identity": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1
},
"directories": [
{
"id": "text",
"revision": 1
}
],
"chat": true,
"optOuts": [
{
"id": "text",
"name": "text",
"revision": 1,
"description": "text",
"lastUsed": "2026-01-01T00:00:00.000Z"
}
],
"user": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"invitationAcceptedAt": "2026-01-01T00:00:00.000Z"
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1,
"email": "text",
"status": "text",
"phone": {
"prefix": "text",
"number": "text"
},
"firstName": "text",
"lastName": "text",
"lastLoginAt": "2026-01-01T00:00:00.000Z",
"settings": {
"cultureCode": "text",
"dateFormat": "text",
"languageCode": "text",
"numberFormat": {
"decimalSeparator": "text",
"groupSeparator": "text"
},
"timeFormat": "text",
"timeZone": "text",
"optOuts": {
"objectTypes": [
"text"
]
}
},
"accounts": [
{
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
],
"currentAccount": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
}
}Unblocks the contact, allowing them to receive notifications again.
The Contact ID.
OK
Represents a notification contact who can receive email notifications.
Gets or sets the description of the category.
Gets or sets the timestamp of when this category was last used to send a notification.
Bad Request
POST /public/v1/notifications/contacts/{id}/unblock HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"activated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"blocked": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"deleted": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"revision": 1,
"name": "text",
"blockedReason": "text",
"email": "text",
"status": "text",
"identity": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1
},
"directories": [
{
"id": "text",
"revision": 1
}
],
"chat": true,
"optOuts": [
{
"id": "text",
"name": "text",
"revision": 1,
"description": "text",
"lastUsed": "2026-01-01T00:00:00.000Z"
}
],
"user": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"invitationAcceptedAt": "2026-01-01T00:00:00.000Z"
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1,
"email": "text",
"status": "text",
"phone": {
"prefix": "text",
"number": "text"
},
"firstName": "text",
"lastName": "text",
"lastLoginAt": "2026-01-01T00:00:00.000Z",
"settings": {
"cultureCode": "text",
"dateFormat": "text",
"languageCode": "text",
"numberFormat": {
"decimalSeparator": "text",
"groupSeparator": "text"
},
"timeFormat": "text",
"timeZone": "text",
"optOuts": {
"objectTypes": [
"text"
]
}
},
"accounts": [
{
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
],
"currentAccount": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
}
}Permanently removes the contact and all associated subscriptions. This operation cannot be undone.
The Contact ID.
No Content
No content
Bad Request
Not Found
DELETE /public/v1/notifications/contacts/{id} HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
No content
Updates contact properties. Only provided fields will be modified.
The Contact ID.
OK
Represents a notification contact who can receive email notifications.
Gets or sets the description of the category.
Gets or sets the timestamp of when this category was last used to send a notification.
Bad Request
PUT /public/v1/notifications/contacts/{id} HTTP/1.1
Host: api.platform.softwareone.com
Content-Type: application/json
Accept: */*
Content-Length: 98
{
"email": "text",
"optOuts": [
{
"id": "text"
}
],
"name": "text",
"directories": [
{
"id": "text"
}
],
"chat": true
}{
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"activated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"blocked": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"deleted": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"revision": 1,
"name": "text",
"blockedReason": "text",
"email": "text",
"status": "text",
"identity": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
}
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1
},
"directories": [
{
"id": "text",
"revision": 1
}
],
"chat": true,
"optOuts": [
{
"id": "text",
"name": "text",
"revision": 1,
"description": "text",
"lastUsed": "2026-01-01T00:00:00.000Z"
}
],
"user": {
"id": "text",
"audit": {
"created": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"updated": {
"at": "2026-01-01T00:00:00.000Z",
"by": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1
}
},
"invitationAcceptedAt": "2026-01-01T00:00:00.000Z"
},
"$meta": {
"omitted": [
"text"
]
},
"name": "text",
"icon": "text",
"revision": 1,
"email": "text",
"status": "text",
"phone": {
"prefix": "text",
"number": "text"
},
"firstName": "text",
"lastName": "text",
"lastLoginAt": "2026-01-01T00:00:00.000Z",
"settings": {
"cultureCode": "text",
"dateFormat": "text",
"languageCode": "text",
"numberFormat": {
"decimalSeparator": "text",
"groupSeparator": "text"
},
"timeFormat": "text",
"timeZone": "text",
"optOuts": {
"objectTypes": [
"text"
]
}
},
"accounts": [
{
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
],
"currentAccount": {
"id": "text",
"name": "text",
"icon": "text",
"revision": 1,
"type": "Client",
"status": "Active"
}
}
}