Skip to main content

Working with Public API Tokens

This document provides technical specifications and operational guidance concerning the utilisation of the Vertice Public API.

The Public API acts as a proxy, interfacing with Vertice's internal APIs. The architecture guarantees that only officially supported functionalities are accessible externally, preserving system stability and ensuring backward compatibility.

The Public API is the only officially supported interface for external system integrations. Direct interaction with internal APIs, such as through the exploitation of browser-derived authentication tokens, remains explicitly unsupported and will fail without prior notification.

Supported Use Cases

  1. Initiation of New Requests: Initiates specified procurement processes through API calls.

    • SaaS - Contract Renewal: urn:verticeone:vertice:{{account_id}}:services:service/saas/renewal/generic/v4

    • SaaS - New Purchase: urn:verticeone:vertice:{{account_id}}:services:service/saas/purchase/v4

      • Endpoint: POST /accounts/{accountId}/procurement/requests

Initiation of new requests using this endpoint is now deprecated and should not be used. Replace any uses with Invoke API trigger calls

  1. Retrieval of Request Status: Enables querying for the status of a previously created request.

    • Endpoint: GET /accounts/{accountId}/procurement/requests/{requestId}

  2. List active vendors: Enables to obtain list of active vendors.

    1. Endpoint: GET /accounts/{accountId}/vendors

  3. Bulk create Vendors: Allows to create vendors in bulk.

    • Endpoint: POST /accounts/{accountId}/vendors

  4. Get Vendor details: Allows to retrieve the details of a specific vendor.

    1. Endpoint: GET /accounts/{accountId}/vendors/{vendorUrn}

  5. Update existing Vendor: Allows to update details of a specific vendor.

    1. Endpoint: PATCH /accounts/{accountId}/vendors/{vendorUrn}

  6. Update existing Vendors in bulk: Allows to update multiple vendors at the same time

    1. Endpoint: PATCH /accounts/{accountId}/vendors

  7. Invoke API trigger: Invokes an API trigger configured in the Workflow Configuration

    1. Endpoint: POST /accounts/{accountId}/workflows/trigger/{triggerUrn}/invoke

Prerequisites

To use the Vertice Public API, the following features must be activated in the customer account:

Requests

  • Intelligent Workflows (INTELLIGENT_WORKFLOWS)

  • Vertice API (VERTICE_API)

Vendors

  • Vertice API (VERTICE_API)

  • Vendor Directory (VENDOR_DIRECTORY)

Configuration

  1. Open Vertice, and click on the Integrations section.

  2. Open the API Access tab.

  3. Scroll down to configured tokens

Authentication

The API authentication is a token-based mechanism, specifically employing Bearer tokens.

Generating Tokens

  1. From the Vertice API subsection under Connectors, click the “Add Token” button.

  2. Assign a token name.

  3. Specify the operational scopes associated with the token. These scopes define the actions that can be executed by the token. Note that the current available scopes are statically defined.

  4. Important: The generated token must be copied and stored in a secure repository immediately – it will not be accessible after this.

Using Tokens

Add the token into the Authorization header field of all API requests:

curl -X POST \ https://api.vertice.one/accounts/{accountId}/procurement/requests \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "serviceRef": "...", "input": { ... } }'

Token Management

  • Expiration: Authentication tokens are valid for one year from the date of issue.

  • Revocation: Tokens can be revoked through the Vertice platform at any time. To deactivate a token, select the revocation control on the tile. Once invalidated, tokens cannot be used.

  • Regeneration/Renewal: For security reasons, existing tokens cannot be regenerated or renewed. Should a token approach its expiration date or its integrity be compromised, the token must be revoked, and a new token subsequently generated.

  • Token Visibility: Currently valid tokens are displayed by default. The display can be adjusted to include expired or revoked tokens as needed.

  • Sorting: The list of tokens is sortable based on multiple criteria, such as creation date and assigned name.

Starting a request

Since deprecation of the create request endpoint, this is the new default way any requests should be started

  1. Go to workflows configuration

  2. Click +

  3. Select Create new trigger

  4. In Type choose API trigger

  5. Configure name, schema and other fields

  6. Click create

  7. Integrate any desired workflow to this trigger

  8. Invoke the trigger using the invoke-trigger endpoint, if everything is set up correctly, the request on the integrated workflow should successfully be started

API trigger Schema

The data structure, or schema, required for invoing an API triggger is dependent upon the specific trigger that you need to invoke.

Finding the Schema

In the Vertice Workflow configuration open Triggers > API and click the desired trigger. Click on the trigger in the canvas and on the right side in the trigger properties panel, you can see and edit the defined schema.

Understanding the Schema

The schema serves as a formal specification for constructing the input object contained within the JSON payload submitted to the POST /accounts/{accountId}/workflows/trigger/{triggerUrn}/invoke endpoint. This specifies all necessary input parameters for the specific trigger designated by the triggerUrn identifier.

Invoking a trigger

  1. Look up the appropriate api endpoint in the trigger properties panel in workflow configuration page.

  2. Construct the JSON payload, including the input object, ensuring strict conformance of the input object to the specifications of the retrieved schema.

  3. Incorporate the API authentication token within the Authorization: Bearer <YOUR_API_TOKEN> header field.

  4. Specify the Content-Type: application/json header.

Example Payload

Presented below is an illustrative JSON payload for invoking an API trigger.

{ "input": { "data": 123 } }

Examples

  • Remember to substitute the placeholder values (like {accountId}, {requestId}, {your_jwt_token}, {vendorUrn}, and the example request body) with actual valid data when making the calls.

  • You can easily test Public API endpoints by importing OpenAPI (vertice-api.yaml ) specification to Postman.

1. Get Procurement Request Status

This endpoint allows users to retrieve the current status of a specific service request.

  • Endpoint: GET /accounts/{accountId}/procurement/requests/{requestId}

  • Description: Retrieves the status of a specific service request.

  • Curl Example:

curl -X GET 'https://api.vertice.one/public/accounts/{accountId}/procurement/requests/{requestId}' \ -H 'Authorization: Bearer {your_jwt_token}'

Example response:

{   "status": "PENDING" }

Notes:

  • Replace {accountId} with the actual Account ID.

  • Replace {requestId} with the actual Request ID.

  • Replace {your_jwt_token} with your valid JWT Bearer token for the Authorization header.

  • Status is one of PENDING, ACTIVE, COMPLETED, CANCELLED, TERMINATED, FAILED

2. Bulk create Vendors

This endpoint allows users to create a new vendors. Vendors are processed one by one. Response contains list of accepted and rejected vendors.

  • Endpoint: POST /accounts/{accountId}/vendors

  • Description: Allows to create vendors in bulk.

  • Curl Example:

    curl -X POST 'https://api.vertice.one/public/accounts/{accountId}/vendors' \ -H 'Authorization: Bearer {your_jwt_token}' \ -H 'Content-Type: application/json' \ -d '{   "vendors": [     {       "name": "My Vendor 1",       "category": "Vendor Category",       "description": "Vendor Description",       "websiteUrl": "https://vendorwebsite.com",       "globalVendorUrn": "urn:verticeone:vertice::vendor:vendor/xxx",       "primaryContact": {         "name": "Foo",         "surname": "Bar",         "email": "[email protected]",         "phone": "1234567890"       },       "addresses": [         {           "street1": "123 Main St",           "street2": "Apt 1",           "city": "New York",           "state": "NY",           "postalCode": "10001",           "countrySubdivision": "US-NY",           "country": "US",           "type": "BILLING"          },         {           "street1": "742 Evergreen Terrace",           "city": "Springfield",           "state": "IL",           "postalCode": "62704",           "countrySubdivision": "US-IL",           "country": "US",           "type": "SHIPPING"         }       ],       "taxNumber": "CZ123456",       "taxNumberType": "SSN",       "additionalFields": {         "employees": 120       },       "customData": {         "internalReference": {           "value": "abc123"         }       }     },     {       "name": "My Vendor 2",       "category": "Vendor Category",       "description": "Vendor Description",       "websiteUrl": "https://vendorwebsite.com",       "globalVendorUrn": "urn:verticeone:vertice::vendor:vendor/xxx"     }   ] }

Example response

{     "acceptedVendors": [         {             "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/2688f4c4-0ffa-499f-a90e-0073eac4de0b",             "name": "My Vendor 2"         }     ],     "errorVendors": [         {             "name": "My Vendor 1",             "errorCode": 409,             "errorMessage": "Vendor already exists"         }     ] }

Notes:

  • Replace {accountId} with the actual Account ID.

  • Replace {your_jwt_token} with your valid JWT Bearer token for the Authorization header.

  • The JSON data (-d) should contain the the list of vendors to create. The name of the vendor is required, other parameters are optional. You are allowed to create 1 to 1000 vendors in single request.

  • The response status code comes back as 207. The response object contains list of successfully created vendors (acceptedVendors) and list of rejected vendors (errorVendors).

  • A single batch can contain a maximum of 100 entries.

3. Get Vendor details

This endpoint allows users to obtain info about specific vendor. Endpoint supports two response formats controlled by include query parameter.

  • Endpoint: GET /accounts/{accountId}/vendors/{vendorUrn}

  • Query Parameters:

    • include

      • base (default)

      • full

  • Description: Allows to retrieve the details of a specific vendor.

  • Curl Example:

    curl -X GET 'https://api.vertice.one/public/accounts/{accountId}/vendors/{vendorUrn}' \ -H 'Authorization: Bearer {your_jwt_token}'

Example response

  • Base Model

    {     "vendor": {         "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/2688f4c4-0ffa-499f-a90e-0073eac4de0b",         "id": "2688f4c4-0ffa-499f-a90e-0073eac4de0b",         "tenant": "fb1c6240-9edd-48f0-872a-0fd9a6aef48b",         "globalVendorUrn": null,         "name": "My Vendor 2",         "category": null,         "status": "ACTIVE"     } }

  • Full Model

    {     "vendor": {       "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/2688f4c4-0ffa-499f-a90e-0073eac4de0b",       "id": "2688f4c4-0ffa-499f-a90e-0073eac4de0b",       "tenant": "fb1c6240-9edd-48f0-872a-0fd9a6aef48b",       "globalVendorUrn": null,       "name": "My Vendor 2",       "status": "ACTIVE",       "createdAt": "2025-09-23T12:43:26.050804+00:00",       "updatedAt": "2025-09-23T12:43:26.050804+00:00",       "activatedAt": "2025-09-23T12:43:26.050804+00:00",       "lastModifiedBy": "Test User",       "category": null,       "description": null,       "externalId": null,       "integrationId": null,       "externalRawData": null,       "externalRecordCreatedAt": null,       "externalRecordUpdatedAt": null,       "primaryContact": null,       "addresses": [],       "taxNumber": null,       "taxNumberType": null,       "websiteUrl": null,       "additionalFields": null     },     "computedFields": {       "isMutable": true     },     "products": [       {         "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/2688f4c4-0ffa-499f-a90e-0073eac4de0b/product/2688f4c4-0ffa-499f-a90e-0073eac4de1c",         "name": "Product 1",         "category": null,         "description": "Product description"       }     ] }

Notes:

  • Replace {accountId} with the actual Account ID.

  • Replace {vendorUrn} with actual Vendor URN in encoded format.

  • Replace {your_jwt_token} with your valid JWT Bearer token for the Authorization header.

  • The response status code is 200.

  • Based on the include query parameter you can control the data format returned from the endpoint.

4. Update existing Vendor

This endpoint allows to update properties of an existing vendor.

  • Endpoint: PATCH /accounts/{accountId}/vendors/{vendorUrn}

  • Description: Update details of a specific vendor.

  • Curl Example:

curl -X PATCH 'https://api.vertice.one/public/accounts/{accountId}/vendors/{vendorUrn}' \ -H 'Authorization: Bearer {your_jwt_token}' \ -H 'Content-Type: application/json' \ -d '{   "patchData": {     "globalVendorUrn": "urn:verticeone:vertice::vendor:vendor/xxx",     "name": "Updated Vendor Name",     "category": "Updated Vendor Category",     "description": "Updated Vendor Description",     "primaryContact": null,     "addresses": [],     "taxNumber": "CZ123456",     "taxNumberType": "SSN",     "websiteUrl": "https://updatedvendorwebsite.com",     "additionalFields": {       "employeesCount": 120     },     "customData": {       "NETSUITE_CUSTOM_ID": "netsuite_external_id_123"     }   } }

Example response

{     "vendor": {       "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/2688f4c4-0ffa-499f-a90e-0073eac4de0b",       "id": "2688f4c4-0ffa-499f-a90e-0073eac4de0b",       "tenant": "fb1c6240-9edd-48f0-872a-0fd9a6aef48b",       "globalVendorUrn": "urn:verticeone:vertice::vendor:vendor/xxx",       "name": "Updated Vendor Name",       "status": "ACTIVE",       "createdAt": "2025-09-23T12:43:26.050804+00:00",       "updatedAt": "2025-09-24T14:43:26.050804+00:00",       "activatedAt": "2025-09-23T12:43:26.050804+00:00",       "lastModifiedBy": "Test User",       "category": "Updated Vendor Category",       "description": "Updated Vendor Description",       "externalId": null,       "integrationId": null,       "externalRawData": null,       "externalRecordCreatedAt": null,       "externalRecordUpdatedAt": null,       "primaryContact": null,       "addresses": [],       "taxNumber": "CZ123456",       "taxNumberType": "SSN",       "websiteUrl": "https://updatedvendorwebsite.com",       "additionalFields": {         "employeesCount": 120       }    } }

Notes:

  • Replace {accountId} with the actual Account ID.

  • Replace {vendorUrn} with actual Vendor URN in encoded format.

  • Replace {your_jwt_token} with your valid JWT Bearer token for the Authorization header.

  • The JSON data (-d) should contain the patchData object with properties to update. All allowed fields to update are listed in request body.

  • The additionalFields and customData attributes follow the RFC7396 semantics.

  • The response status code is 200.

5. Update existing vendors in bulk

This endpoint allows to update properties of multiple vendors per request. The vendors are processed one by one. The returned response only shows successful and rejected vendors, without the updated values.

  • Endpoint: PATCH /accounts/{accountId}/vendors/

  • Description: Update details of a list of vendors. Successful edits are returned in the successfulVendors list, rejected vendors are returned in errorVendors list and each contains an error code and a human readable error message.

  • Curl Example:

curl -X PATCH 'https://api.vertice.one/public/accounts/{accountId}/vendors/' \ -H 'Authorization: Bearer {your_jwt_token}' \ -H 'Content-Type: application/json' \ -d '{   "vendors": [     {       "vendorUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/2688f4c4-0ffa-499f-a90e-0073eac4de0b",       "patchData": {         "globalVendorUrn": "urn:verticeone:vertice::vendor:vendor/xxx",         "name": "Updated Vendor Name",         "category": "Updated Vendor Category",         "description": "Updated Vendor Description",         "primaryContact": null,         "addresses": [],         "taxNumber": "CZ123456",         "taxNumberType": "SSN",         "websiteUrl": "https://updatedvendorwebsite.com",         "additionalFields": {           "employeesCount": 120         },         "customData": {           "NETSUITE_CUSTOM_ID": "netsuite_external_id_123"         }       }     },     {       "vendorUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/00000000-0000-0000-0000-000000000000",       "patchData": {         "name": "Updated Missing Vendor Name",       }     }   ] }

Example response

{     "successfulVendors":     [         {             "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/2688f4c4-0ffa-499f-a90e-0073eac4de0b"         }     ],     "errorVendors":     [         {             "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/00000000-0000-0000-0000-000000000000",             "errorCode": "NOT_FOUND",             "errorMessage": "Vendor not found"         }     ] }

Notes:

  • Replace {accountId} with the actual Account ID.

  • Replace {vendorUrn} with actual Vendor URN in encoded format.

  • Replace {your_jwt_token} with your valid JWT Bearer token for the Authorization header.

  • The JSON data (-d) should contain the patchData object with properties to update. All allowed fields to update are listed in request body.

  • The additionalFields and customData attributes follow the RFC7396 semantics.

  • A single batch can contain a maximum of 100 entries.

  • The response status code is 207.

6. List active vendors

This endpoint returns list of active vendors in specific account. Pagination via query parameters limit and offset is supported.

  • Endpoint: GET /accounts/{accountId}/vendors

  • Query Parameters:

    • limit

      • min 1

      • max 1000

      • default 1000

    • offset

      • min 0

      • default 0

  • Description: Allows users to retrieve the list of vendors associated with a specific account.

  • Curl Example:

curl -X GET 'https://api.vertice.one/public/accounts/{accountId}/vendors?limit={limit}&offset={offset}' \ -H 'Authorization: Bearer {your_jwt_token}'

Example response

{     "vendors": [         {             "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/6ec48b04-f814-4003-b75e-fe2d61b34201",             "name": "My Vendor 2",             "category": "Analytics Tools",             "status": "ACTIVE",             "activatedAt": "2025-09-17T12:27:33.853635+00:00",             "description": null         },         {             "resourceUrn": "urn:verticeone:vertice:fb1c6240-9edd-48f0-872a-0fd9a6aef48b:vendor:vendor/6ec48b04-f814-4003-b75e-fe2d61b34200",             "name": "My Vendor 3",             "category": "Analytics Tools",             "status": "ACTIVE",             "activatedAt": "2025-09-17T12:27:33.853635+00:00",             "description": "Some description"         }     ],     "metadata": {         "totalCount": 150     } }

Notes:

  • Replace {accountId} with the actual Account ID.

  • Replace {vendorUrn} with actual Vendor URN.

  • Replace {limit} and {offset} with required pagination options.

  • Replace {your_jwt_token} with your valid JWT Bearer token for the Authorization header.

  • The response status code comes back as 200.

  • Based on the limit and offset query parameter you can paginate over the vendors.

Did this answer your question?