Prewave Suppliers - Connection Contacts API
🆕 NEW - Supplier connection contact management endpoints. Available from February 2026.
OpenAPI Specification
openapi: 3.0.1
info:
title: Public Prewave Actions Suppliers - Connection Contacts API
description: 'Documentation of the Public Prewave API.
## What''s New
### Q1 2026 — Supplier Management, User Management, Actions and Feed
This quarter introduces major v2 upgrades, expanded administrative capabilities, and the new Actions API.
- **Core Releases:** Deployed Supplier Management API v2 and Feed API v2, alongside the all-new Actions API.
- **Enhanced Functionality:** Added robust identifier management, granular user and role configuration, and endpoints for managing supplier connection contacts.
- ⚠️ **Required Migration:** Legacy v1 endpoints for Suppliers and Sites Upsert have been deprecated. Developers must migrate existing integrations to v2 by **May 31, 2027** (original deadline was December 31, 2026).
📖 **[Read the Q1 2026 changelog](https://docs.prewave.com/en/articles/699847-q1-2026-public-api-updates)**
### Q2 2026 — Supplier Screening and External Scores
We have expanded our v2 documentation to include comprehensive integration guidance for supplier screening and validation workflows and identifier-based external score ingestion.
- **New Capabilities:** Added support for optional post-onboarding screening and validation during the create event.
- **External Scores:** Batch POST for multiple supplier sites, per-site history GET, and event-type discovery GET (`/public/v1/scores/externals` and `/public/v1/scores/externals/event-types`). Documented in OpenAPI when enabled for your organization.
- **Developer Resources:** Published new integration examples and detailed identifier validation rules to streamline your implementation process.
📖 **[Read the Q2 2026 changelog](https://docs.prewave.com/en/articles/699849-q2-2026-public-api-updates)**
### Q3 2026 — Scores Webhooks
To support event-driven architectures and eliminate the need for continuous API polling, we are introducing webhooks for score state changes later this year.
- **Event-Driven Architecture:** Register webhook URLs to receive real-time HTTP payloads whenever a supplier''s score updates, so you can drive immediate mitigation responses without polling the API.
- **Availability:** Comprehensive OpenAPI specifications and payload schemas will be published closer to the release date.
- **Note:** Schemas and behaviors are subject to refinement prior to general availability.
Documentation updates will be provided prior to release.
### Q4 2026 — Feed V2
We are enhancing Feed API v2 with additional capabilities on top of the existing `GET /public/v2/feed` contract (see Q1 changelog and OpenAPI for the current Feed v2 integration).
- **Availability:** Details will be announced before release.
- **Note:** Schemas and behaviors are subject to refinement prior to the official release.
Documentation updates will be provided prior to release.
---
## Authentication
Prewave’s public api uses *API tokens* to authenticate against our RESTful service. We’ll provide you an *API-token* that each
endpoint needs present as a http header.
To pass the token in a request, simply add it as a header-parameter with
* key = X-Auth-Token
* value = api-token
See an example in curl below where the api-token would be 12345678-90ab-cdef-1234-567890abcdef
```
curl --request GET \
--url https://REPLACE_WITH_SERVER/public/v1/target/prewave/3975230/alerts \
--header ''X-Auth-Token: 12345678-90ab-cdef-1234-567890abcdef''
```
---
## Manage API Tokens
Before you can obtain your API token, you''ll need the credentials for your API user. These credentials will be
sent to you as part of the company-onboarding. If you haven''t got your credentials yet, please reach out to
your sales-contact at Prewave or contact us via info@prewave.ai
To generate an API Token, navigate to https://www.prewave.com/management/api and log in with the
credentials of your API user. Then click at the button "Create New" and use your new api-token authentication as a header parameter.
You can create multiple API tokens and also remove existing API tokens on https://www.prewave.com/management/api.
API tokens do not expire, therefore you have to maintain the list of API tokens you are using manually.
---
## Default Rate Limits
We have two types of default rate limits. For increased access, please contact customer success.
| Type | Requests per 10 seconds | Requests per Minute |
|-----------------------------------|-------------------------|---------------------|
| GET requests | 100 | 500 |
| POST, PUT, PATCH, DELETE requests | 20 | 100 |
'
version: '1.0'
servers:
- url: https://api.prewave.com
description: Production Environment
security:
- Token authentication: []
tags:
- name: Suppliers - Connection Contacts
description: 🆕 NEW - Supplier connection contact management endpoints. Available from February 2026.
paths:
/public/v2/suppliers/connection-contacts:
get:
tags:
- Suppliers - Connection Contacts
summary: Find supplier connection contacts by identifier
description: "\n### Overview\nRetrieve all connection contacts for a supplier identified by any of its identifiers (supplierId, customerId, ownId, or prewaveId).\n\nConnection contacts are contact persons associated with suppliers that can be used for communication and relationship management. This endpoint returns contacts that are accessible to your organization.\n\n### Search Behavior\n- Provide at least one identifier parameter.\n- The identifiers must resolve to **exactly one** supplier.\n- If multiple suppliers are found, a `400 Bad Request` is returned.\n\n### Related Operations\n- **Create Contact**: [POST /public/v2/suppliers/connection-contacts](#operations-Suppliers_-_Connection_Contacts-createConnectionContactByIdentifier)\n- **Delete Contact**: [DELETE /public/v2/suppliers/connection-contacts/{contactId}](#operations-Suppliers_-_Connection_Contacts-deleteConnectionContact)\n- **Find Suppliers**: [GET /public/v2/suppliers/sites/find-by-identifier](#operations-Suppliers_-_Sites-findSuppliers)\n\n### Required Permission\n`access_public_suppliers` and `access_public_conn_contacts`\n "
operationId: findConnectionContactsByIdentifier
parameters:
- name: supplierId
in: query
description: Supplier ID to search for. Can be combined with customerId, ownId, and/or prewaveId.
required: false
schema:
type: string
example: SAP-12345
- name: customerId
in: query
description: Customer ID to search for. Can be combined with supplierId, ownId, and/or prewaveId.
required: false
schema:
type: string
example: CRM-67890
- name: ownId
in: query
description: Own site ID to search for. Can be combined with supplierId, customerId, and/or prewaveId.
required: false
schema:
type: string
example: OWN-SITE-01
- name: prewaveId
in: query
description: Prewave ID to search for. Can be combined with supplierId, customerId, and/or ownId.
required: false
schema:
type: integer
format: int32
example: 12345
- name: source
in: query
description: Optional source system to filter by. If not provided, matches IDs with any source or without a source. Applies to all provided ID parameters.
required: false
schema:
type: string
example: SAP
responses:
'200':
description: Successfully retrieved connection contacts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PublicSupplierConnectionContact'
examples:
Contacts List:
summary: Sample response with connection contacts
description: Contacts List
value: '[{"id":42,"email":"contact@supplier.com"},{"id":43,"email":"support@supplier.com"}]'
'400':
description: 400 Bad Request - Invalid request or multiple suppliers found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Multiple suppliers found:
summary: Search criteria matches multiple suppliers
description: Multiple suppliers found
value: '{"code":"invalid_request","message":"Multiple suppliers found matching the provided identifiers. Found 2 suppliers with prewaveTargetIds: 102006215, 102006216. Please provide more specific identifiers.","solution":"Provide more specific identifiers or use the source parameter."}'
'404':
description: 404 Not Found - Supplier not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Supplier not found:
summary: No supplier matches the identifiers
description: Supplier not found
value: '{"code":"resource_not_found","message":"No supplier found matching the provided identifiers","solution":"Verify the identifiers and ensure the supplier exists in your organization"}'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 100,\n \"requestCount\": 100,\n \"limits\": [\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 500,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
post:
tags:
- Suppliers - Connection Contacts
summary: Create connection contact for a supplier by identifier
description: "\n### Overview\nCreate a new connection contact for a supplier identified by any of its identifiers (supplierId, customerId, ownId, or prewaveId).\n\nThis endpoint allows you to add contact persons to suppliers for relationship management. If your organization is not yet connected to the identified target, it will be automatically connected as a supplier.\n\n### Auto-Connection Logic\n- If the identified target is not yet connected to your organization, an edge of type 'Supplier' will be created automatically.\n- This requires the additional internal permission `access_public_mng_customer_conn`.\n\n### Related Operations\n- **List Contacts**: [GET /public/v2/suppliers/connection-contacts](#operations-Suppliers_-_Connection_Contacts-findConnectionContactsByIdentifier)\n- **Delete Contact**: [DELETE /public/v2/suppliers/connection-contacts/{contactId}](#operations-Suppliers_-_Connection_Contacts-deleteConnectionContact)\n\n### Required Permission\n`access_public_suppliers` and `access_public_mng_conn_contacts`\n "
operationId: createConnectionContactByIdentifier
parameters:
- name: supplierId
in: query
description: Supplier ID to search for. Can be combined with customerId, ownId, and/or prewaveId.
required: false
schema:
type: string
example: SAP-12345
- name: customerId
in: query
description: Customer ID to search for. Can be combined with supplierId, ownId, and/or prewaveId.
required: false
schema:
type: string
example: CRM-67890
- name: ownId
in: query
description: Own site ID to search for. Can be combined with supplierId, customerId, and/or prewaveId.
required: false
schema:
type: string
example: OWN-SITE-01
- name: prewaveId
in: query
description: Prewave ID to search for. Can be combined with supplierId, customerId, and/or ownId.
required: false
schema:
type: integer
format: int32
example: 12345
- name: source
in: query
description: Optional source system to filter by. If not provided, matches IDs with any source or without a source. Applies to all provided ID parameters.
required: false
schema:
type: string
example: SAP
requestBody:
description: Connection contact payload
content:
application/json:
schema:
$ref: '#/components/schemas/PublicConnectionContactPayload'
examples:
Create Contact:
summary: Example payload to create a connection contact
description: Create Contact
value: '{"email":"new.contact@supplier.com"}'
required: true
responses:
'201':
description: Connection contact created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PublicSupplierConnectionContact'
examples:
Contact Created:
summary: Sample response for successful contact creation
description: Contact Created
value: '{"id":44,"email":"new.contact@supplier.com"}'
'400':
description: 400 Bad Request - Invalid request, multiple suppliers found, or target not connectable.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Not Connectable:
summary: Target is not connectable
description: Not Connectable
value: '{"code":"invalid_request","message":"Supplier is not connectable","solution":"Ensure the target type supports connections."}'
'404':
description: 404 Not Found - Supplier not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Supplier not found:
description: Supplier not found
value: '{"code":"resource_not_found","message":"No supplier found matching the provided identifiers","solution":"Verify the identifiers and ensure the supplier exists in your organization"}'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 20,\n \"requestCount\": 20,\n \"limits\": [\n {\n \"requestLimit\": 20,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
/public/v2/suppliers/connection-contacts/{contactId}:
get:
tags:
- Suppliers - Connection Contacts
summary: Get a connection contact
description: "\n### Overview\nRetrieve a connection contact by its unique Prewave identifier.\n\n### Identification\nThe `{contactId}` is a unique numerical identifier of the connection contact.\n\n### Getting contactId\n- From the list of contacts returned by `GET /public/v2/suppliers/connection-contacts`.\n- From the response body or `Location` header when creating a contact via `POST /public/v2/suppliers/connection-contacts`.\n\n### Required Permission\n`access_public_suppliers` and `access_public_conn_contacts`\n "
operationId: getConnectionContact
parameters:
- name: contactId
in: path
description: Unique identifier of the connection contact. You can obtain this ID from the list endpoint (GET) or from the creation response (POST).
required: true
schema:
type: integer
format: int32
example: 42
responses:
'200':
description: Successfully retrieved connection contact
content:
application/json:
schema:
$ref: '#/components/schemas/PublicSupplierConnectionContact'
examples:
Single Contact:
summary: Sample response for a single contact
description: Single Contact
value: '{"id":42,"email":"contact@supplier.com"}'
'404':
description: 404 Not Found - Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Contact Not Found:
summary: The specified contact ID does not exist
description: Contact Not Found
value: '{"code":"resource_not_found","message":"Connection contact with ID 999 not found","solution":"Verify the contact ID."}'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 100,\n \"requestCount\": 100,\n \"limits\": [\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 500,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
delete:
tags:
- Suppliers - Connection Contacts
summary: Delete a connection contact
description: "\n### Overview\nDelete a connection contact by its unique Prewave identifier.\n\n### Identification\nThe `{contactId}` is a unique numerical identifier of the connection contact.\n\n### Getting contactId\n- From the list of contacts returned by `GET /public/v2/suppliers/connection-contacts`.\n- From the response body or `Location` header when creating a contact via `POST /public/v2/suppliers/connection-contacts`.\n\n### Required Permission\n`access_public_suppliers` and `access_public_mng_conn_contacts`\n "
operationId: deleteConnectionContact
parameters:
- name: contactId
in: path
description: Unique identifier of the connection contact. You can obtain this ID from the list endpoint (GET) or from the creation response (POST).
required: true
schema:
type: integer
format: int32
example: 42
responses:
'204':
description: Connection contact deleted successfully
'404':
description: 404 Not Found - Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Contact Not Found:
summary: The specified contact ID does not exist
description: Contact Not Found
value: '{"code":"resource_not_found","message":"Connection contact with ID 999 not found","solution":"Verify the contact ID."}'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 20,\n \"requestCount\": 20,\n \"limits\": [\n {\n \"requestLimit\": 20,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
components:
schemas:
AccessDeniedErrorDTO:
required:
- code
- loggedIn
- message
type: object
properties:
loggedIn:
type: boolean
example: null
permission:
type: string
nullable: true
example: null
code:
type: string
description: Error code
example: null
message:
type: string
description: Error message
example: null
solution:
type: string
description: Possible solution to the error
nullable: true
example: null
example: null
ErrorDTO:
required:
- code
- message
type: object
properties:
code:
type: string
description: Error code
example: null
message:
type: string
description: Error message
example: null
solution:
type: string
description: Possible solution to the error
nullable: true
example: null
description: Error response
example: null
PublicSupplierConnectionContact:
required:
- id
type: object
properties:
id:
type: integer
description: Unique identifier of the connection contact.
format: int32
example: 42
email:
type: string
description: Email address of the connection contact. May be null if not provided.
format: email
nullable: true
example: contact@example.com
description: Public representation of a supplier's connection contact. Contains the unique contact ID and the contact's email address.
example: null
ApiRateLimitTimeRequestLimit:
type: object
properties:
requestLimit:
type: integer
description: Maximum number of requests allowed in this time window
format: int32
example: 100
timeInSeconds:
type: integer
description: Time window duration in seconds
format: int32
example: 10
description: Rate limit configuration for a specific time window
example: null
ApiRateLimitResponse:
type: object
properties:
error:
type: string
description: Error type identifier
example: RateLimitExceeded
message:
type: string
description: Human-readable error message explaining the rate limit violation
example: API rate limit exceeded. Please reduce your request rate.
requestLimit:
type: integer
description: Maximum number of requests allowed in the current time window
format: int32
example: 100
requestCount:
type: integer
description: Number of requests made in the current time window
format: int32
example: 101
limits:
type: array
description: All rate limits that apply to this endpoint, showing different time windows
items:
$ref: '#/components/schemas/ApiRateLimitTimeRequestLimit'
example: null
currentTime:
type: string
description: Current server time in ISO 8601 format
format: date-time
example: '2026-01-19T10:30:00'
nextResetAt:
type: string
description: Time when the rate limit will reset in ISO 8601 format
format: date-time
example: '2026-01-19T10:30:10'
description: Response returned when API rate limit is exceeded (HTTP 429)
example: null
PublicConnectionContactPayload:
required:
- em
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prewave/refs/heads/main/openapi/prewave-suppliers-connection-contacts-api-openapi.yml