1 of 100

REST API

Introduction

The Marketplace Platform REST API lets you interact with the platform programmatically. Our API is organized around REST, has predictable resource-oriented URLs, uses JSON-encoded representations, and uses standard HTTP response codes, authentication, and verbs. Use our API to create apps, automate tasks, or build integrations with the platform.

Beginners Guide

What is a REST API?

An API (Application Programming Interface) is a set of rules that allows programs to talk to each other and share data and functions in a standard format over the Internet.

REST (Representational State Transfer) is a way to design APIs for distributed systems. When people mention a "REST API", they mean an API that uses the HTTP protocol.

These URLs point to different resources, which can be data like JSON, web pages, audio files, or images. You can perform actions on these resources using HTTP methods like GET, POST, PUT, and DELETE:

GET = Retrieve data
POST = Create new data
PUT = Update existing data
DELETE = Remove data

For example, the Marketplace Platform offers several REST APIs for tasks like managing orders and viewing users and accounts. Each API in our platform works similarly, whether you access it directly over HTTP or through helper libraries in various programming languages.

Authentication

The Marketplace Platform uses API tokens to authenticate requests. You can view and manage your API keys in the user interface of your account settings. Include your API token in the "Authorization" HTTP header with the "Bearer" prefix for authentication.

For example, the following request could be used to retrieve a list of Buyers:

GET https://api.platform.softwareone.com/public/v1/accounts/buyers
Authorization: Bearer {TOKEN_VALUE}

Your API keys have permissions assigned to them, so keep them secure. Do not share your secret API keys in public areas like GitHub or client-side code.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Content Type

The Marketplace Platform API expects the content type of API requests to be "application/json" in most cases (except for cases where "multipart/form-data" is used to send attachments)

GET https://api.platform.softwareone.com/public/v1/accounts/buyers
Authorization: Bearer {TOKEN_VALUE}
Content-Type: application/json

To communicate successfully with the Marketplace Platform APIs, ensure your API requests are formatted using the "application/json" content type. Using the wrong content type may result in unexpected behavior or errors.

API Endpoint

The base endpoint for the Marketplace Platform API is:

https://api.platform.softwareone.com/public

All API requests start from that base URL. For example, if you have an endpoint like:

/v1/accounts/buyers

The fully qualified URL that you need to use is:

https://api.platform.softwareone.com/public/v1/accounts/buyers

Use this base endpoint with specific API paths to correctly access the resources and services provided by the Marketplace Platform.

Resource Query Language

The Resource Query Language (or RQL) is used for querying and manipulating resources in the Marketplace Platform's APIs. With RQL, you can filter, sort, paginate, and project data. It is simple to use but flexible enough to handle complex scenarios.

For example, to display all users with the first name "Buzz", your GET request would look like this:

GET /v1/accounts/users?firstName=Buzz

See Resource Query Language for more details.

Errors Handling

Our platform reports errors using HTTP status codes in a standard format, ensuring consistency and clarity. For more details, please see Errors Handling.

Explore the APIs

Resource Query Language

Resource Query Language (RQL) is a query language used by the Marketplace Platform in its REST API.

Introduction

The Resource Query Language (or RQL) is used for querying and manipulating resources in the Marketplace Platform's . With RQL, you can filter, sort, paginate, and project data. It is simple to use but flexible enough to handle complex scenarios.

Using RQL

RQL consists of a set of operators that can be classified into three main categories:

Comparison Operators: These perform comparisons like equals, greater than, etc.
Logical Operators: These combine multiple conditions.
Algorithmic Operators: These handle functionalities like sorting and pagination.

Operators are formatted as operator(arg1,arg2,...). Complex expressions can be created by nesting these operators.

Practical Examples

Suppose you want to list all users with a specific domain. Implementing filtering is essential, and this is where RQL comes in.

Basic Filtering

To display all users with the first name "Buzz", your GET request would look like this:

GET /v1/accounts/users?firstName=Buzz

the same expression can be written as:

GET /v1/accounts/users?eq(firstName,Buzz)

Sorting

To sort users based on their first name, your GET request would look like this:

GET /v1/accounts/users?order=firstName

To sort in the opposite direction, the '-' operator can be used:

GET /v1/accounts/users?order=-firstName

Pagination

To paginate your results with a limit of 10 users and to retrieve the third page (offset 20):

GET /v1/accounts/users?limit=10&offset=20

The first parameter limit=10 expresses the number of users to return
Second parameter offset=20 offsets the starting position in the result set. The first 20 users will be skipped.

Projection

To request specific fields, such as forstName, lastName, and email to be included, the select=+ operator can be used:

GET /v1/accounts/users?select=+firstName,+lastName,+email

To request certain fields to be excluded, the select=- operator can be used:

GET /v1/accounts/users?select=-firstName,-lastName,-email

Search

To search for all users with the firstName starting from 'Bu', the following query can be used:

GET /v1/accounts/users?ilike(firstName,Bu*)

the operator ilike performs a case-insensitive search.

Combining Operators

Logical operators can be used to combine multiple operators. For example, to filter users with first name "Buzz" and last name "Astral":

GET /v1/accounts/users?and(eq(firstName,Buzz),eq(lastName,Astral))

In simple cases, a combined expression can also be written in the following form:

GET /v1/accounts/users?firstName=Buzz&lastName=Astral

Operators

Advanced use cases

Special Characters in Values

To pass special characters (e.g., &^$?) or whitespaces as values to RQL operators, enclose them in either double quotes (") or single quotes (') as shown in the following example:

GET /v1/accounts/users?firstName="Buzz !!!"

If you need to include a quotation mark within the value, you can do so by enclosing it with a different type of quotation mark, as shown in the following example:

GET /v1/accounts/users?firstName="Buzz with the ' Quote"

Allowing you to pass these special symbols as values.

The Asterisk Character and the ilike operator

The asterisk (*) character has a special meaning in the ilike operator, matching zero or more characters in its place from the parameter value. For example, the "*dog" pattern will match strings like "big dog" and "dog," but it will not match "big dog!" because of the exclamation mark.

If you need to use the asterisk (*) character itself in the pattern, you can escape it as '*', as shown in the following example:

GET /v1/accounts/users?ilike(firstName,"The\**")

The ilike operator in this case will be searching for the literal value “The*” at the beginning of the firstName property.

Errors Handling

General Information on Handling REST API Errors in the Marketplace Platform

All errors reported by the REST API have an HTTP status code and follow the standard format. When an error occurs, the response body usually contains a JSON object with the following fields:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "traceId": "00-9e02a91b64ac56904703a3a69ea9101d-56be90a29d0b0b25-00",
  "errors": {
    "mistake": [
      "Unknown expression group."
    ]
  }
}

type: [string] A URI reference that identifies the error type, providing a consistent way to categorize errors across different API implementations.
title: [string] A human-readable title or summary of the error.
status: [number] The HTTP status code associated with the error.
detail: (Optional) [string] A detailed human-readable description of the error, providing additional information to help clients understand the issue.
instance: (Optional) [string] A URI reference that identifies the specific occurrence of the error, useful for debugging or tracing purposes.
traceId: (Optional) [string] A unique identifier to trace requests in logs.
errors: (Optional) [key-value] A collection of errors detected by validation logic.

Common Errors

Some of the common errors are listed in the table below.

HTTP status

Description

401 Unauthorized

This means the request lacks valid authentication credentials for the target resource. Check if the Authorization header is present and contains the valid token value.

403 Forbidden

The server understands the request but refuses to authorize it.

404 Not Found

The requested resource could not be found on the server.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource.

415 Unsupported Media Type

The server refuses the request because the payload format is not supported.

500 Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request.

501 Not Implemented

The server does not support the functionality required to fulfill the request.

504 Gateway Timeout

The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server.

Accounts API

Account

Account Object

The account object represents an individual account on the Marketplace platform. This object contains the following properties:

Field

Type

Description

Example

{
  "id": "ACC-1671-0642",
  "href": "/accounts/accounts/ACC-1671-0642",
  "type": "Client",
  "status": "Enabled",
  "name": "You Are a Test Account",
  "description": "This is a test account.",
  "externalId": "WW-1001111",
  "serviceLevel": "Express",
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "postCode": "12345",
    "city": "Cityville",
    "state": "S",
    "country": "ST"
  },
  "logo": null,
  "technicalSupportEmail": "user@example.com",
  "website": "https://example.com"  
}

{
  "id": "ACC-1671-0642",
  "href": "/accounts/accounts/ACC-1671-0642",
  "type": "Client",
  "status": "Enabled",
  "name": "You Are a Test Account",
  "description": "This is a test account.",
  "externalId": "WW-1001111",
  "serviceLevel": "Express",
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "postCode": "12345",
    "city": "Cityville",
    "state": "S",
    "country": "ST"
  },
  "logo": null,
  "technicalSupportEmail": "user@example.com",
  "website": "https://example.com",
  "groups": [
		{
			"id": "UGR-9354-3382",
			"href": "/user-groups/UGR-9354-3382",
			"name": "Administrators",
			"description": "Manages administrative tasks and resources within an organization.",
			"logo": null,
			"isDefault": true
		}
  ],
  {
    "created": { "at": "2023-12-14T17:28:57.667Z", "by": { "id": "USR-1234-1234", "name": "John Smith" } },
    "updated": { "at": "2023-12-14T17:28:57.667Z", "by": { "id": "USR-1234-1234", "name": "John Smith" } },
    "disabled": { "at": "2023-12-14T17:28:57.667Z", "by": { "id": "USR-1234-1234", "name": "John Smith" } },
    "enabled": { "at": "2023-12-14T17:28:57.667Z", "by": { "id": "USR-1234-1234", "name": "John Smith" } },
    "activated": { "at": "2023-12-14T17:28:57.667Z", "by": { "id": "USR-1234-1234", "name": "John Smith" } }
  }
}

List Accounts

Create Account

Create a new Client or Vendor Account object.

Enable Account

Enable the previously disabled Account object.

When enabled, the account status will change to Active if the account has ExternalId assigned or Enabled otherwise.

Disable Account

Disable the Account object. Disabling prevents users from signing in

Activate Account

Activate the previously enabled Account object.

Get Account

Get a single Account object by ID.

Update Account

Update the Account object.

Validate Account

Validate the Account object.

Get List of External Buyers

Gets a list of external Buyer objects that can be added to Account

Get Account Icon

Buyer

Buyer Object

The buyer object represents an individual buyer in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary buyer identifier.

Example: "BUY-1234-1234"

href

string

Relative reference to object on API.

Example: "/v1/accounts/buyers/BUY-1234-1234"

status

string

Status: Enabled, Active, Disabled, Deleted

name

string

Buyer's name.

Example: "Stark Industries"

icon

string

Relative path to buyer’s logo.

Example: "/static/accounts/BUY-1234-1234/logo.png"

externalIds

BuyerExternalIdsObject

External identifier.

Example:

{
 "erpCompanyContact": "WW-CON-123456",
 "erpCustomer": "WW-SCU-123456"
}

address

object

Address of the buyer.

Example:

{
  "addressLine1": "123 Main Street",
  "addressLine2": "Apt 4B",
  "postCode": "12345",
  "city": "Cityville",
  "state": "S",
  "country": "ST"
}

taxId

string

Buyer's tax ID.

Example: "12-34567890"

account

Buyer’s account object.

sellers

contact

object

Contact person details.

Example:

{
	"name": "Will Smith",
	"firstName": "Will",
	"lastName": "Smith",
	"email": "will.smith@adastraflex.com",
	"phone": null,
	"user": {
		"id": "USR-0000-0001",
		"href": "/users/USR-0000-0001",
		"icon": null,
		"name": "Will Smith"
	}
}

audit

object

Possible audit events: Created, Updated, Disabled, Enabled, Activated.

Example:

{
  "created": { "at": "...", "by": { } },
  "updated": { "at": "...", "by": { } },
  "disabled": { "at": "...", "by": { } },
  "enabled": { "at": "...", "by": { } },
  "activated": { "at": "...", "by": { } },
  "deleted": { "at": "...", "by": { } }
}

Example

{
	"id": "BUY-3911-2313",
	"href": "/accounts/buyers/BUY-3911-2313",
	"contact": {
		"name": "Will Smith",
		"firstName": "Will",
		"lastName": "Smith",
		"email": "will.smith@adastraflex.com",
		"phone": null
	},
	"externalIds": {
		"erpCompanyContact": "WW-CON-123456",
		"erpCustomer": "WW-SCU-123456"
    },
	"status": "Active",
	"icon": null,
	"address": {
		"addressLine1": "PO Box 31",
		"addressLine2": "Victory Road",
		"postCode": "DE24 8BJ",
		"city": "Derby",
		"state": "Derbs",
		"country": "UK"
	},
	"taxId": "VAT1",
	"name": "Stark Industries"
}

{
	"id": "BUY-3911-2313",
	"href": "/accounts/buyers/BUY-3911-2313",
	"contact": {
		"name": "Will Smith",
		"firstName": "Will",
		"lastName": "Smith",
		"email": "will.smith@adastraflex.com",
		"phone": null,
		"user": {
			"id": "USR-0000-0001",
			"href": "/users/USR-0000-0001",
			"icon": null,
			"invited": "2024-02-03T11:34:15.381Z",
			"joined": "2024-02-04T12:34:15.381Z",
			"lastLogin": "2024-02-05T13:34:15.381Z",
			"name": "Will Smith"
		}
	},
    "externalIds": {
		"erpCompanyContact": "WW-CON-123456",
		"erpCustomer": "WW-SCU-123456"
    },
	"status": "Active",
	"icon": null,
	"address": {
		"addressLine1": "PO Box 31",
		"addressLine2": "Victory Road",
		"postCode": "DE24 8BJ",
		"city": "Derby",
		"state": "Derbs",
		"country": "UK"
	},
	"taxId": "VAT1",
	"account": {
		"id": "ACC-5563-4382",
		"href": "/accounts/accounts/ACC-5563-4382",
		"type": "Client",
		"status": "Active",
		"icon": null,
		"name": "AdAstraflexx"
	},
	"name": "Stark Industries",
	"sellers": [
		{
			"id": "SEL-1299-2079",
			"href": "/accounts/sellers/SEL-1299-2079",
			"externalId": "SWO_CH",
			"name": "SoftwareOne AG"
		}
	],
	"audit": {
		"created": {
			"at": "2023-12-14T13:44:20.896Z",
			"by": {
				"id": "USR-0000-0001",
				"href": "/users/USR-0000-0001",
				"icon": null,
				"invited": "2024-02-03T11:34:15.383Z",
				"joined": "2024-02-04T12:34:15.383Z",
				"lastLogin": null,
				"name": "Will Smith"
			}
		},
		"updated": {
			"at": "2024-01-06T19:04:16.692Z",
			"by": {
				"id": "USR-0000-0001",
				"href": "/users/USR-0000-0001",
				"icon": null,
				"invited": "2024-02-03T11:34:15.383Z",
				"joined": "2024-02-04T12:34:15.383Z",
				"lastLogin": null,
				"name": "Will Smith"
			}
		}
	}
}

List Buyers

Get the Buyers collection.

Create Buyer

Create a new Buyer object for the client account.

Enable Buyer

Enable a previously disabled Buyer object.

When enabled, the buyer status will change to Active if the buyer has ExternalId assigned or Enabled otherwise.

Disable Buyer

Disable the Buyer object. Disabled buyers cannot be used in transactions.

Get Buyer

Get a single Buyer object by ID.

Update Buyer

Update the Buyer object. You can only update the logo and contact fields only.

Delete Buyer

Delete the Buyer object.

Validate Buyer

Validate a Buyer object.

Seller

Seller Object

The seller object represents a seller in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary seller identifier.

Example: "SEL-1234-1234"

href

string

Relative reference to object on API.

Example: "/v1/accounts/sellers/SEL-1234-1234"

status

string

Status: Active , Disabled, Offline , Deleted

name

string

Seller's name.

Example: "SoftwareOne USA"

icon

string

Relative path to seller’s logo.

Example: "/static/accounts/SEL-1234-1234/logo.png"

externalId

string

External identifier.

Example: "WW-CON-123456"

address

object

Address of the seller.

Example:

{
  "addressLine1": "123 Main Street",
  "addressLine2": "Apt 4B",
  "postCode": "12345",
  "city": "Cityville",
  "state": "S",
  "country": "ST"
}

currency

string

buyers

audit

object

Possible audit events: Created, Updated, Activated, Disabled, Deactivated, or Deleted

Example:

{
  "created": { "at": "...", "by": { } },
  "updated": { "at": "...", "by": { } },
  "activated": { "at": "...", "by": { } },
  "disabled": { "at": "...", "by": { } },
  "deactivated": { "at": "...", "by": { } },
  "deleted": { "at": "...", "by": { } }
}

Example

{
	"id": "SEL-7295-4834",
	"href": "/accounts/sellers/SEL-7295-4834",
	"externalId": "SWO_CH",
	"status": "Active",
	"icon": null,
	"currency": "USD",
	"address": {
		"addressLine1": "Some street",
		"addressLine2": null,
		"postCode": "P0S C0D3",
		"city": "Some city",
		"state": "SS",
		"country": "CH"
	},
	"name": "SoftwareOne AG"
}

{
	"id": "SEL-7295-4834",
	"href": "/accounts/sellers/SEL-7295-4834",
	"externalId": "SWO_CH",
	"status": "Active",
	"icon": null,
	"currency": "USD",
	"address": {
		"addressLine1": "Some street",
		"addressLine2": null,
		"postCode": "P0S C0D3",
		"city": "Some city",
		"state": "SS",
		"country": "CH"
	},
	"name": "SoftwareOne AG",
	"buyers": [
		{
			"id": "BUY-2321-7707",
			"href": "/accounts/buyers/BUY-2321-7707",
			"name": "My first buyer"
		}
	],
	"audit": {
		"created": {
			"at": "2023-12-14T14:19:13.410Z",
			"by": {
				"id": "USR-0000-0001",
				"href": "/users/USR-0000-0001",
				"icon": null,
				"invited": "2024-02-03T11:59:55.933Z",
				"joined": "2024-02-04T12:59:55.933Z",
				"lastLogin": null,
				"name": "Will Smith"
			}
		},
		"updated": {
			"at": "2024-01-24T09:33:09.073Z",
			"by": {
				"id": "USR-0000-0001",
				"href": "/users/USR-0000-0001",
				"icon": null,
				"invited": "2024-02-03T11:59:55.933Z",
				"joined": "2024-02-04T12:59:55.933Z",
				"lastLogin": "2024-02-05T13:59:55.933Z",
				"name": "Will Smith"
			}
		}
	}
}

List Sellers

Get the Sellers collection.

Get Seller

Get a single Seller object by ID.

Create Seller

Create a new Seller object.

Update Seller

Update the seller object, except the seller status. Use the disable, activate, deactivate, and delete endpoints to manage the status.

Activate Seller

Activate a previously deactivated or disabled seller.

When activated, the status changes from Offline or Disabled to Active.

Deactivate Seller

Deactivate a seller.

When a seller is deactivated, the status changes from Active to Offline.

Disable Seller

Disable or deactivate the seller object.

When disabled, the status changes from Active to Disabled. Disabled sellers cannot be used in transactions.

Delete Seller

Delete the seller object. When deleted, the status changes from Active to Deleted.

Licensee

Licensee Object

The licensee object represents a licensee in the Marketplace platform. This object contains the following properties:

Field

Type

Description

Example

{
	"id": "LCE-8893-6916-0000",
	"href": "/accounts/licensees/LCE-8893-6916-0000",
	"contact": null,
	"name": "Stark Industries",
	"externalId": null,
	"status": "Active",
	"address": null,
	"useBuyerAddress": false,
	"icon": null,
	"description": null
}

{
	"id": "LCE-8893-6916-0000",
	"href": "/accounts/licensees/LCE-8893-6916-0000",
	"contact": null,
	"name": "Stark Industries",
	"externalId": null,
	"status": "Active",
	"address": null,
	"useBuyerAddress": false,
	"icon": null,
	"description": null,
	"account": {
		"id": "ACC-5563-4382",
		"href": "/accounts/accounts/ACC-5563-4382",
		"type": "Client",
		"status": "Active",
		"icon": null,
		"name": "AdAstraflexx"
	},
	"buyer": {
		"id": "BUY-8928-0965",
		"href": "/accounts/buyers/BUY-8928-0965",
		"name": "Stark Industries"
	},
	"seller": {
		"id": "SEL-4717-3953",
		"href": "/accounts/sellers/SEL-4717-3953",
		"externalId": "SWO_CA",
		"name": "SoftwareOne Canada, Inc."
	}
}

List Licensees

List Licensee items in the Licensees collection.

Get Licensee

Get a single licensee object by ID.

Create Licensee

Create a new licensee object.

Update Licensee

Update the licensee object.

You can update the licensee Seller Object, except the status (which is managed through the disable, enable, deleteendpoints) buyers id and sellers id.

Delete Licensee

Delete the licensee object.

Enable Licensee

Enable the previously disabled licensee object.

Disable Licensee

Disable the licensee object.

Module

Module Object

The module object represents a module in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary module identifier.

Example: "MOD-1234"

name

string

Name of the module.

Example: "Invoices"

description

string

Description of the module.

Example: "Invoices module"

accountTypes

string

Defines presence of module for each account type.

Example: ["vendor", "client", "operations"]

isEnabledByDefault

boolean

Defines whether the module is enabled by default.

Example: "true"

isConfigurable

boolean

Defines whether module’s access can be changed.

Example: "true"

Example

{
  "id": "MOD-1234",
  "name": "Invoices",
  "description": "Invoices module",
  "accountTypes": ["vendor", "client", "operations"],
  "isEnabledByDefault": true,
  "isConfigurable": false
}

List Modules

Get a list of modules in the platform.

Users

User Object

The user object represents an individual user in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary user identifier.

Example: "USR-1671-0642"

href

string

Relative reference to object on API (always /v1/accounts/users/{id}).

Example: "/v1/accounts/users/USR-1671-0642"

email

string

Email address of the user.

Example: "will.smith@softwareone.com"

status

string

Status of the user.

enum values

New

Invited

Invitation

Expired

Active

Blocked

Disabled

Deleted

A user can have the Invited or InvitationExpired status only if they haven't joined the account.

name

string

User's name.

Example: "Will Smith"

firstName

string

First name of the user.

Example: "Will"

lastName

string

Last name of the user.

Example: "Smith"

phone

object

User's country code and phone number.

Example:

{ 
  "prefix": "+34",
  "number": "660707172"
}

SSO

bool

Flag if a user logs using SSO.

Example: "true"

acceptedTerms

bool

Flag if user has accepted terms and conditions.

Example: "true"

accounts

List of accounts that user is added to, not returned on users account sub-collection.

Example:

[
  {
    "id": "ACC-1671-0642",
    "name": "You Are a Test Account"
  }
]

groups

Groups that the user belongs to.

Example:

[
  {
    "id": "UGR-5116-6265",
    "name": "Administrators"
  },
  {
    "id": "UGR-5116-6565",
    "name": "Fulfillment Managers"
  }
]

settings

invitation

object

Added only in context of account (on account sub-collection), and only in case of user being invited.

Example:

{
  "code": "910B14E6CB2343A09CB32F24BBC4BEF1",
  "status": "Invited"
}

invitation.code

string

Invitation code sent to user to invite them to the platform.

Example: "910B14E6CB2343A09CB32F24BBC4BEF1"

invitation.status

string

Invitation status for the user in account.

Example: "Invited"

audit

object

Meaning of audit events: On GLobal User

created - when user was created (once in lifecycle).
updated - when user parameters changed last time.
login - when user last time logged in.
blocked - when user was blocked last time.

On account subcollection, in additional to above:

invited - when user was invited into account (dropped on join).
joined - when user was accepted invitation to account.
access - when user last time switched to the account context.

Example:

{
    "created": { ... },
    "updated": { ... },
    "joined": { ... },
    "login": { ... },
    "access": { ... }
}

Example

{
  "id": "USR-6375-2499",
  "href": "/v1/accounts/users/USR-6375-2499",
  "email": "test12.test@SWO1.com",
  "name": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "status": "Invited",
  "phone": { 
      "prefix": "+34",
      "number": "660707172"
  },
  "accounts": [
		{
			"id": "ACC-1671-0642",
			"href": "/accounts/ACC-1671-0642",
			"icon": null,
			"name": "You Are a Test Account"
		}
  ],
  "group": [
      {
        "id": "UGR-5116-6265",
        "name": "Administrators"
      },
      {
        "id": "UGR-5116-6565",
        "name": "Fulfillment Managers"
      }
  ],
  "invitation": {
    "code": "910B14E6CB2343A09CB32F24BBC4BEF1",
    "status": "Invited"
  }
}

List Users

Get a list of all platform users.

Get User

Get a single user by ID.

Set User Password

Set passwords for non-SSO users during onboarding.

Update User

Update a user.

Unblock User

Unblock a previously blocked user.

Block User

Block a user.

User Groups

Group Object

The group object represents a user group in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary group identifier.

Example: "UGR-1234-1234"

href

string

Relative reference to object on API.

Example: "/v1/accounts/groups/UGR-1234-1234"

icon

string

Relative path to token’s logo.

Example: "/static/accounts/UGR-1234-1234/logo.png"

name

string

Group name.

Example: "Stark Industries"

description

string

Group description.

Example: "Stark's marketing group"

modules

List of modules available for the group.

Example: "Invoices"

default

bool

Indicated if the user group is set as default in the account. There is only one default user-group per account.

Example: "true"

stats

stats

Statistics of the group. A

group can be deleted only if the UsersCount is 0.

Example:

{
  "users": 123
}

Example

{
	"id": "UGR-5116-6265",
	"href": "/user-groups/UGR-5116-6265",
	"name": "Test-1",
	"description": "Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.",
	"modules": [
		{
			"id": "MOD-1756-1452",
			"name": "Access management"
		},
		{
			"id": "MOD-9042-8216",
			"name": "Account management"
		}
	],
	"icon": "https://picsum.photos/210/201",
	"default": true,
	"stats": {
		"users": 123
	}
}

List User Groups

Get the user groups collection.

Get User Group

Get a single user group by ID.

Create User Group

Create a user group for the client account.

Update User Group

Update a user group.

Delete User Group

Delete a user group.

Account User

Account User Object

The user object represents an individual user in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary account user identifier.

Example: "AUSR-5709-0422-8243"

href

string

Relative reference to object on API (always /v1/accounts/account-users/{id}).

Example: "/v1/accounts/account-users/AUSR-5709-0422-8243"

user

account

{
  "id": "ACC-1671-0642",
  "href": "/accounts/ACC-1671-0642",
  "icon": null,
  "name": "You Are a Test Account"
}

invitation

Invitation.Status

Invitation information: Invited, Active, InvitationExpired

Example:

{
  "url": "https://client.softwareone.com/accept-invite?code=invitationCode",
  "status": "Invited"
}

groups

List of user groups.

Example:

[
  {
    "id": "UGR-8447-7590",
    "href": "/user-groups/UGR-8447-7590",
    "name": "test2",
    "description": "test2",
    "logo": "",
    "isDefault": false
  }
]

Example

{
    "$meta": {
        "pagination": {
            "offset": 0,
            "limit": 10,
            "total": 1
        },
        "omitted": [
            "audit"
        ]
    },
    "data": [
        {
            "id": "AUSR-4134-7183-7330",
            "href": "/account-users/AUSR-4134-7183-7330",
            "user": {
                "id": "USR-6375-2499",
                "href": "/users/USR-6375-2499",
                "email": "test12.test@SWO1.com",
                "firstName": "test",
                "lastName": "test"
            },
            "groups": [
                {
                    "id": "UGR-8447-7590",
                    "href": "/user-groups/UGR-8447-7590",
                    "name": "test2",
                    "description": "test2",
                    "logo": "",
                    "isDefault": false
                }
            ],
            "account": {
                "id": "ACC-1671-0642",
                "href": "/accounts/ACC-1671-0642",
                "icon": null,
                "name": "You Are a Test Account"
            },
            "invitation": {
                "code": "TEST",
                "status": "Invited"
            }
        }
    ]
}

List Account Users

Get all users assigned to an account.

Get Account User

Get a single account user by ID.

Create Account User

Invite a user to the account.

Assign User to a Group

Assign an account user to a specific group.

Update User to Group Assignment

Remove User

Removes a user from a specific group.

Accept User Invitation

Accepts user invitation to the account.

Resend User Invitation

Resend an invitation to the user.

Send New Invitation

Send new invitation when invite expires.

Delete Account User

Deletes a user from the account. The user remains active in the other accounts.

API Tokens

Token Object

The token object represents an authentication token user in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary API token identifier.

Example: "TKN-1671-0642"

href

string

Relative reference to object on API.

Example: "/v1/accounts/accounts/ACC-1671-0642/tokens/TKN-4134-7330"

name

string

Name of the token.

Example: "Robot"

description

string

Token description.

Example: "Test token"

status

string

Status of the token: Active, Disabled, Deleted

modules

At least one modules validation when creating API Token.

account

Account under which the token has been defined.

Example:

{
  "id": "ACC-123-123",
  "name": "Microsoft"
}

token

string

Authentication code.

Example

{
    "id": "TKN-4134-7330",
    "href": "/v1/accounts/accounts/ACC-1671-0642/tokens/TKN-4134-7330",
    "name": "Name",
    "description": "Description",
    "icon": "",
    "status": "Active",
    "modules": [
        {
            "id": "MOD-1756-1452"
        },
        {
            "id": "MOD-9042-8216"
        }
    ],
    "token": "CODE"
}

Create Token

Create a new token object for the specific account.

List Tokens

Get the API tokens collection.

Get Token

Get a single API token by ID.

Update Token

Update the specified token object.

Delete Token

Delete an existing token object.

Enable Token

Enable the specified token object.

Disable Token

Disable the specified token object.

Commerce API

Agreements Attachments

Users

User Object

The user object represents an individual user in the Marketplace platform. This object contains the following properties:

Field

Type

Description

id

string

Primary user identifier.

Example: "USR-1671-0642"

href

string

Relative reference to object on API (always /v1/accounts/users/{id}).

Example: "/v1/accounts/users/USR-1671-0642"

email

string

Email address of the user.

Example: "will.smith@softwareone.com"

status

string

Status of the user.

enum values

New

Invited

Invitation

Expired

Active

Blocked

Disabled

Deleted

A user can have the Invited or InvitationExpired status only if they haven't joined the account.

name

string

User's name.

Example: "Will Smith"

firstName

string

First name of the user.

Example: "Will"

lastName

string

Last name of the user.

Example: "Smith"

phone

object

User's country code and phone number.

Example:

{ 
  "prefix": "+34",
  "number": "660707172"
}

SSO

bool

Flag if a user logs using SSO.

Example: "true"

acceptedTerms

bool

Flag if user has accepted terms and conditions.

Example: "true"

accounts

List of accounts that user is added to, not returned on users account sub-collection.

Example:

[
  {
    "id": "ACC-1671-0642",
    "name": "You Are a Test Account"
  }
]

groups

Groups that the user belongs to.

Example:

[
  {
    "id": "UGR-5116-6265",
    "name": "Administrators"
  },
  {
    "id": "UGR-5116-6565",
    "name": "Fulfillment Managers"
  }
]

settings

invitation

object

Added only in context of account (on account sub-collection), and only in case of user being invited.

Example:

{
  "code": "910B14E6CB2343A09CB32F24BBC4BEF1",
  "status": "Invited"
}

invitation.code

string

Invitation code sent to user to invite them to the platform.

Example: "910B14E6CB2343A09CB32F24BBC4BEF1"

invitation.status

string

Invitation status for the user in account.

Example: "Invited"

audit

object

Meaning of audit events: On GLobal User

created - when user was created (once in lifecycle).
updated - when user parameters changed last time.
login - when user last time logged in.
blocked - when user was blocked last time.

On account subcollection, in additional to above:

invited - when user was invited into account (dropped on join).
joined - when user was accepted invitation to account.
access - when user last time switched to the account context.

Example:

{
    "created": { ... },
    "updated": { ... },
    "joined": { ... },
    "login": { ... },
    "access": { ... }
}

Example

{
  "id": "USR-6375-2499",
  "href": "/v1/accounts/users/USR-6375-2499",
  "email": "test12.test@SWO1.com",
  "name": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "status": "Invited",
  "phone": { 
      "prefix": "+34",
      "number": "660707172"
  },
  "accounts": [
		{
			"id": "ACC-1671-0642",
			"href": "/accounts/ACC-1671-0642",
			"icon": null,
			"name": "You Are a Test Account"
		}
  ],
  "group": [
      {
        "id": "UGR-5116-6265",
        "name": "Administrators"
      },
      {
        "id": "UGR-5116-6565",
        "name": "Fulfillment Managers"
      }
  ],
  "invitation": {
    "code": "910B14E6CB2343A09CB32F24BBC4BEF1",
    "status": "Invited"
  }
}

Agreements

Agreements Object

The agreement represents an instance of a relationship between Seller, Buyer, and Licensee. It may refer to one-time purchases or/and set of subscriptions.

Field

Type

Description

id

string

Primary account identifier.

Example: "AGR-2119-4550-8674"

href

string

Relative reference to object on API (always /commerce/agreements/{id}).

Example: "/v1/commerce/agreements/AGR-2119-4550-8674"

status

string

The key status of the object. May only be specified on creation - Draft or Provisioning, and cannot be updated with PUT.

name

string

Agreement name, will be assigned automatically on creation, as {product.name} for {licensee.name} but can be changed later.

Example: "Microsoft Office 365 NCE E1"

vendor

Example:

{
    "id": "ACC-1234-1234",
    "href": "/accounts/accounts/ACC-1234-1234",
    "name": "Microsoft",
    "icon": "/static/ACC-1234-1234/account.png"
}

client

Example:

{
    "id": "ACC-1234-4444",
    "href": "/accounts/accounts/ACC-1234-4444",
    "name": "Best LLC",
    "icon": "/static/ACC-1234-4444/account.png"
}

buyer

Example:

{
    "id": "BUY-3731-7971",
    "href": "/accounts/buyers/BUY-3731-7971",
    "name": "Adam Ruszczak",
    "icon": "/static/BUY-3731-7971/icon.png"
}

seller

Example:

{
    "id": "SEL-9121-8944",
    "href": "/accounts/sellers/SEL-9121-8944",
    "name": "Software LN",
    "icon": "/static/SEL-9121-8944/icon.png"
}

licensee

Example:

{
    "id": "LCE-9625-9634",
    "href": "/accounts/licensees/LCE-9625-9634",
    "name": "John Smith",
    "icon": "/static/LCE-9625-9634/icon.png"
}

product

Example:

{
    "id": "PRD-1111-1111-1111",
    "href": "/catalog/products/PRD-1111-1111-1111",
    "name": "Microsoft Office 365 NCE",
    "icon": "/static/PRD-1111-1111-1111/logo.png"
}

listing

Listing

Reference to the listing which allows this agreement.

Example:

{
    "id": "LST-1234-1234"
}

authorization

Authorization

Reference to the Authorization object used for the agreement.

Example:

{
    "id": "AUT-1234-4567",
    "href": "/authorization/ATH-1234-45678",
    "name": "Salesforce Enterprise License"
}

price

Price

The price for the agreement, explains the monthly and yearly prices for the whole agreement, one-time price tags are never included into it. different parts of price object visible to different actors, see Price Object.

Example:

{
  "PPxY": 150,
  "PPxM": 12.50,
  "SPxY": 165,
  "SPxM": 13.75,
  "currency": "USD"
}

template

Template

Reference to Template object.

Example:

{
    "id": "TPL-1234-4444",
    "href": "/products/product/<id>/templates/TPL-1234-4444",
    "name": "Succesful Activation"
}

error

ErrorObject

Markup text string explaining reason for provisining failure. Always set on moving status to Failed.

Example:

{
     "id": "E001234",
     "message": "Agreement provisioning failed due to unavailability of the item"
}

lines

Lines[]

List of items in Agreement.

Example:

[
  {
    "id": "ALI-1234-1234-1234-0127",
    "item": {
      "id": "ITM-1234-1234-1234-0992",
      "name": "Adobe Migration"
    },
    "quantity": 10,
    "price": {
      "PPx1": 12.50,
      "unitPP": 1.25
      "SPx1": 13.50,
      "unitSP": 1.35,
      "currency": "USD"
    },
    "order": { "id": "ORD-6869-4529-8975-9005" }
  }
]

subscriptions

Subscription[]

Example:

[
    {
      "id": "SUB-0792-5000-2253",
      "href": "/commerce/agreements/AGR-2119-4550-8674-5962/subscriptions/SUB-0792-5000-2253"
    }
]

parameters.fulfillment

OrderParameterValue []

An object that holds a concise definition of a parameter, its value, and any associated errors.

Example:

[
  {
      "id": "PRM-1234-1234-1234",
      "name": "Tennant Id",
      "externalId": "tennant_id",
      "constraints": {
          "readonly": false,
          "hidden": true,
          "required": true,
          "unique": false
      },
      "value": "69b73824-ce76-4866-ad47-b615ae9d8998",
      "error": {
          "id": "E001234",
          "message": "Incorrect parameter value"
      }
  }
]

parameters.ordering

Order Parameter Object []

An object that holds a concise definition of a parameter, its value, and any associated errors.

Example:

[
  {
      "id": "PRM-1234-1234-1234",
      "name": "Tennant Id",
      "externalId": "tennant_id",
      "constraints": {
          "readonly": false,
          "hidden": true,
          "required": true,
          "unique": false
      },
      "value": "69b73824-ce76-4866-ad47-b615ae9d8998",
      "error": {
          "id": "E001234",
          "message": "Incorrect parameter value"
      }
  }
]

audit

AuditObject

Audit object with possible entries: created, updated, activated, terminated, according to the object's lifecycle.

Possible audit events include Created, Updated, Activated, Terminated, and Failed.

Example:

{
  "created": { "at": "...", "by": { } },
  "updated": { "at": "...", "by": { } },
  "activated": { "at": "...", "by": { } },
  "terminated": { "at": "...", "by": { } }
}

externalIds

ExternalIdsObject

Set of external IDs.

Example:

{
  "client": "12345678",
  "operations":	"07bf766b-c767-4293-9ab3",
  "vendor": "ABC-2023-C07-dbeee0b302c0"
}

Example

{
  "id": "AGR-2119-4550-8674",
  "href": "/commerce/agreements/AGR-2119-4550-8674",
  "status": "Draft",
  "name": "Microsoft Office 365 NCE E1", 
  "vendor": { "id": "ACC-1234-1234" },
  "client": { "id": "ACC-1234-4444" },
  "seller": { "id": "SEL-9121-8944" },
  "buyer": { "id": "BUY-3731-7971" },
  "licensee": { "id": "LCE-9625-9634" },
  "product": {
    "id": "PRD-1111-1111-1111",
    "href": "/catalog/products/PRD-1111-1111-1111",
    "name": "Microsoft Office 365 NCE",
    "icon": "/static/PRD-1111-1111-1111/logo.png"
  },
  "price": {
    "PPxY": 150,
    "PPxM": 12.50,
    "SPxY": 165,
    "SPxM": 13.75,
    "currency": "USD"
  },
  "startDate": "2023-12-14T17:28:57.667Z",
  "endDate": "2023-12-14T17:28:57.667Z",
  "template": {
    "id": "TPL-1234-4444",
    "href": "/products/product/<id>/templates/TPL-1234-4444",
    "name": "Succesful Activation"
  },
  "audit": {
    "created": { "at": "...", "by": { } },
    "updated": { "at": "...", "by": { } }
  },
  "lines": [
    {
      "id": "ALI-1234-1234-1234-0127",
      "item": {
        "id": "ITM-1234-1234-1234-0992",
        "name": "Adobe Migration"
      },
      "quantity": 10,
      "price": {
        "PPx1": 12.50,
        "unitPP": 1.25
        "SPx1": 13.50,
        "unitSP": 1.35,
        "currency": "USD"
      },
      "order": { "id": "ORD-6869-4529-8975-9005" }
    }
  ],
  "subscriptions": [
    { "id": "SUB-0792-5000-2253" }
  ],
  "parameters": {
    "ordering": [ ],
    "fulfillment": [ ]
  },
  "externalIDs": {
    "client": "12345678",
    "operations":	"07bf766b-c767-4293-9ab3",
    "vendor": "ABC-2023-C07-dbeee0b302c0"
  }
}

{
  "id": "AGR-2119-4550-8674",
  "href": "/commerce/agreements/AGR-2119-4550-8674",
  "status": "Draft",
  "name": "Microsoft Office 365 NCE E1", 
  "vendor": {
    "id": "ACC-1234-1234",
    "href": "/accounts/accounts/ACC-1234-1234",
    "name": "Microsoft",
    "icon": "/static/ACC-1234-1234/account.png"
  },
  "client": {
    "id": "ACC-1234-4444",
    "href": "/accounts/accounts/ACC-1234-4444",
    "name": "Best LLC",
    "icon": "/static/ACC-1234-4444/account.png"
  },
  "seller": {
    "id": "SEL-9121-8944",
    "href": "/accounts/sellers/SEL-9121-8944",
    "name": "Software LN",
    "icon": "/static/SEL-9121-8944/icon.png"
  },
  "buyer": {
    "id": "BUY-3731-7971",
    "href": "/accounts/buyers/BUY-3731-7971",
    "name": "Adam Ruszczak",
    "icon": "/static/BUY-3731-7971/icon.png"
  },
  "licensee": {
    "id": "LCE-9625-9634",
    "href": "/accounts/licensees/LCE-9625-9634",
    "name": "John Smith",
    "icon": "/static/LCE-9625-9634/icon.png"
  },
  "product": {
    "id": "PRD-1111-1111-1111",
    "href": "/catalog/products/PRD-1111-1111-1111",
    "name": "Microsoft Office 365 NCE",
    "icon": "/static/PRD-1111-1111-1111/logo.png"
  },
  "price": {
    "PPxY": 150,
    "PPxM": 12.50,
    "SPxY": 165,
    "SPxM": 13.75,
    "markup": 0.10,
    "margin": 0.11,
    "currency": "USD"
  },
  "startDate": "2023-12-14T17:28:57.667Z",
  "endDate": "2023-12-14T17:28:57.667Z",
  "template": {
    "id": "TPL-1234-4444",
    "href": "/products/product/<id>/templates/TPL-1234-4444",
    "name": "Succesful Activation"
  },
  "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"
      }
    },
    "updated": { 
      "at": "2023-12-14T17:28:57Z", 
      "by": {
        "id": "UR-1234-1234-1234",
        "name": "John Smith",
        "icon": "/static/users/UR-1234-1234-1234.icon.svg"
      }
    }
  },
  "lines": [
    {
      "id": "ALI-1234-1234-1234-0127",
      "item": {
        "id": "ITM-1234-1234-1234-0992",
        "name": "Adobe Migration"
      },
      "quantity": 10,
      "price": {
        "PPx1": 12.50,
        "unitPP": 1.25,
        "SPx1": 13.50,
        "unitSP": 1.35,
        "markup": 0.10,
        "margin": 0.11,
        "currency": "USD"
      },
      "order": { "id": "ORD-6869-4529-8975-9005" }
    }
  ],
  "subscriptions": [
    {
      "id": "SUB-0792-5000-2253",
      "href": "/commerce/agreements/AGR-2119-4550-8674-5962/subscriptions/SUB-0792-5000-2253"
    }
  ],
  "parameters": {
    "ordering": [
      {
        "id": "string",
        "name": "string",
        "value": "string",
        "hasError": true,
        "description": {
          "type": "SingleLine",
          "phase": "Configuration",
          "isRequired": true,
          "isHidden": true,
          "isReadOnly": true,
          "error": "string"
        }
      }
    ],
    "fulfillment": [
      {
        "id": "string",
        "name": "string",
        "value": "string",
        "hasError": true,
        "description": {
          "type": "SingleLine",
          "phase": "Configuration",
          "isRequired": true,
          "isHidden": true,
          "isReadOnly": true,
          "error": "string"
        }
      }
    ]
  },
  "externalIDs": {
    "client": "12345678",
    "operations":	"07bf766b-c767-4293-9ab3",
    "vendor": "ABC-2023-C07-dbeee0b302c0"
  }
}