Prewave EUDR - Customers - Suppliers API

openapi: 3.2.0
info:
  title: Public Prewave EUDR - Customers - Suppliers API
  description: Documentation of the Public Prewave API.
  version: '1.0'
servers:
- url: https://api.prewave.com
  description: Production Environment
security:
- Token authentication: []
tags:
- name: EUDR - Customers - Suppliers
  description: Allows you to search for suppliers, find suppliers by IDs or references, and manage supplier connection contacts.
paths:
  /public/v2/eudr/customers/suppliers/{supplierId}/connection-contacts:
    get:
      tags:
      - EUDR - Customers - Suppliers
      summary: Find supplier connection contacts
      description: 'Retrieve connection contacts for a supplier, including contacts added by your organization and contacts added by connected customers.


        Connection contacts are contact persons associated with suppliers that can be used for communication

        and relationship management. This endpoint returns all available contacts for the specified supplier,

        regardless of which organization added them.


        **Use Cases**:

        - Retrieve contact information for supplier communication

        - View contacts added by other connected customers

        - Manage supplier relationship contacts


        **Required permissions:** `access_public_products`, `access_public_conn_contacts`, and `READ` on the target'
      operationId: findConnectionContacts
      parameters:
      - name: supplierId
        in: path
        description: Supplier target ID for which connection contacts are to be retrieved.
        required: true
        schema:
          type: integer
          format: int32
        example: 102006215
      responses:
        '200':
          description: Successfully retrieved connection contacts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicSupplierConnectionContact'
              examples:
                Connection contacts:
                  summary: Contacts available for the supplier
                  description: Connection contacts
                  value: '[{"id":42,"email":"procurement@acme.example.com"},{"id":43,"email":"sustainability@acme.example.com"},{"id":44,"email":null}]'
                No contacts:
                  summary: Supplier has no connection contacts yet
                  description: No contacts
                  value: []
        '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:
      - EUDR - Customers - Suppliers
      summary: Create connection contact for own or connected supplier
      description: 'Create a new connection contact for a supplier.


        This endpoint allows you to add contact persons to suppliers for relationship management.

        If the specified target is not currently a supplier, it will be automatically connected as one.


        **Use Cases**:

        - Add contact persons to suppliers

        - Maintain supplier contact information

        - Enable supplier communication


        **Required permissions:** `access_public_products`, `access_public_mng_conn_contacts`, and `READ` on the target'
      operationId: createConnectionContact
      parameters:
      - name: supplierId
        in: path
        description: Supplier target ID for whom new contacts will be created. If the given target is not a supplier, it will be automatically created as one.
        required: true
        schema:
          type: integer
          format: int32
        example: 102006215
      requestBody:
        description: Connection contact email address.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicConnectionContactPayload'
            examples:
              Create connection contact:
                summary: Add a contact by email address
                description: Create connection contact
                value: '{"email":"new.contact@example.com"}'
        required: true
      responses:
        '200':
          description: Connection contact created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSupplierConnectionContact'
              examples:
                Created connection contact:
                  summary: Newly created contact with assigned ID
                  description: Created connection contact
                  value: '{"id":45,"email":"new.contact@example.com"}'
        '400':
          description: Invalid payload (e.g., missing required fields or invalid email format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              examples:
                Missing required fields:
                  summary: Required fields missing in payload
                  description: Missing required fields
                  value:
                    code: invalid_request
                    message: Email is required
                    solution: Provide all required fields in the payload
                Invalid email format:
                  summary: Email format is invalid
                  description: Invalid email format
                  value:
                    code: invalid_request
                    message: Invalid email format
                    solution: Provide a valid email address
        '404':
          description: Supplier not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              examples:
                Supplier not found:
                  summary: The specified supplier does not exist
                  description: Supplier not found
                  value:
                    code: not_found
                    message: Supplier with ID 102006215 not found
                    solution: Verify the supplier 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    }"
  /public/v2/eudr/customers/suppliers:
    get:
      tags:
      - EUDR - Customers - Suppliers
      summary: Find suppliers by their IDs or references where at least one of the two…
      description: 'Find suppliers by providing either a list of target IDs or a list of references. Exactly one of the two parameters must be provided. The maximum number of allowed IDs or references is limited to 100. Returns a list of supplier details for the provided identifiers, including screening status, references, connection contacts, and supplier maturity when available.


        **Use Cases**:

        - Look up suppliers by internal target IDs

        - Resolve suppliers by external reference codes

        - Retrieve supplier details for product or compliance workflows


        **Required permission:** `access_public_products`'
      operationId: findSuppliers_1
      parameters:
      - name: targetIds
        in: query
        description: 'List of supplier target IDs. Must not be provided together with ''refs''. Maximum allowed: 100.'
        required: false
        schema:
          type: integer
          format: int32
        example: 102006215
      - name: refs
        in: query
        description: 'List of supplier references. Must not be provided together with ''targetIds''. Maximum allowed: 100.'
        required: false
        schema:
          type: array
        example: ERP-12345
      responses:
        '200':
          description: List of suppliers matching the provided IDs or references.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicEUDRSupplier'
              examples:
                Suppliers by IDs or references:
                  summary: Suppliers with references, contacts, and maturity status
                  description: Suppliers by IDs or references
                  value: '[{"id":102006215,"name":"Acme Manufacturing Inc","location":"Vienna","isPublic":true,"organization":{"id":200,"name":"Acme Group","location":"Vienna"},"screened":true,"references":[{"id":"ERP-12345","source":"erp"},{"id":"ERP-789","source":"internal"}],"connectionContacts":[{"id":42,"email":"procurement@acme.example.com"},{"id":43,"email":"sustainability@acme.example.com"}],"supplierMaturity":{"answerStatus":"Good","answerHidden":false}},{"id":102006216,"name":"Beta Timber Ltd","location":"London","isPublic":false,"organization":null,"screened":false,"references":[{"id":"REF-001","source":"Manual"}],"connectionContacts":[],"supplierMaturity":null}]'
                No suppliers found:
                  summary: None of the provided identifiers matched a supplier
                  description: No suppliers found
                  value: []
        '400':
          description: 'Invalid parameters: both or neither of targetIds and refs provided, or exceeded maximum allowed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              examples:
                Both parameters provided:
                  summary: Both targetIds and refs provided
                  description: Both parameters provided
                  value:
                    code: invalid_request
                    message: Exactly one of targetIds or refs must be provided
                    solution: Provide either targetIds or refs, but not both
                Neither parameter provided:
                  summary: Neither targetIds nor refs provided
                  description: Neither parameter provided
                  value:
                    code: invalid_request
                    message: At least one of targetIds or refs must be provided
                    solution: Provide either targetIds or refs parameter
                Exceeded maximum:
                  summary: Too many identifiers provided
                  description: Exceeded maximum
                  value:
                    code: invalid_request
                    message: Maximum allowed identifiers exceeded
                    solution: Reduce the number of identifiers to the maximum allowed limit
        '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    }"
  /public/v2/eudr/customers/suppliers/search:
    get:
      tags:
      - EUDR - Customers - Suppliers
      summary: 'Search for supplier sites (max results: 100)'
      description: 'Search for supplier sites by a free-text query. Only site-type suppliers are returned.

        The query must be at least 3 characters long. The maximum number of results is limited to

        100. If the query is too short or no matching supplier type

        is found, an error is returned.


        **Use Cases**:

        - Search for suppliers by name or identifier

        - Find supplier sites for product associations

        - Discover available suppliers


        **Required permission:** `access_public_products`'
      operationId: queryPoiTargets
      parameters:
      - name: query
        in: query
        description: The search string (minimum 3 characters). Used to match supplier names or other identifying information.
        required: true
        schema:
          minLength: 3
          type: string
        example: Acme
      responses:
        '200':
          description: List of supplier sites matching the search criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicEUDRTarget'
              examples:
                Supplier search results:
                  summary: Supplier sites matching a free-text query
                  description: Supplier search results
                  value: '[{"id":102006215,"name":"Acme Manufacturing Inc","location":"Vienna","isPublic":true,"organization":{"id":200,"name":"Acme Group","location":"Vienna"}},{"id":102006216,"name":"Beta Timber Ltd","location":"London","isPublic":false,"organization":null}]'
                No matches:
                  summary: Query returned no supplier sites
                  description: No matches
                  value: []
        '400':
          description: Query too short or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              examples:
                Query too short:
                  summary: Query parameter is less than 3 characters
                  description: Query too short
                  value:
                    code: invalid_request
                    message: Query must be at least 3 characters long
                    solution: Provide a query string with at least 3 characters
        '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    }"
components:
  schemas:
    PublicSupplierReference:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: Reference ID
          example: REF-001
        source:
          type:
          - string
          - 'null'
          description: Source of the reference
          example: SAP
      description: Reference information for a supplier. Contains reference ID and source.
      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
    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
    PublicEUDRTarget:
      required:
      - id
      - isPublic
      - name
      type: object
      properties:
        id:
          type: integer
          description: Supplier ID
          format: int32
          example: 101
        name:
          type: string
          description: Supplier name
          example: Acme Corp
        location:
          type:
          - string
          - 'null'
          description: Supplier location
          example: Vienna
        isPublic:
          type: boolean
          description: Indicates if the supplier profile is public
          example: true
        organization:
          allOf:
          - $ref: '#/components/schemas/PublicEUDROrganization'
          example: null
      description: Public representation of a target. Contains basic target information and associated organization if available.
      example: null
    PublicEUDROrganization:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: integer
          description: Organization ID
          format: int32
          example: 201
        name:
          type: string
          description: Organization name
          example: Global Supplies Inc.
        location:
          type:
          - string
          - 'null'
          description: Organization location
          example: New York
      description: Organization information for a supplier. Contains organization ID, name, and location.
      example: null
    AccessDeniedErrorDTO:
      required:
      - code
      - loggedIn
      - message
      type: object
      properties:
        loggedIn:
          type: boolean
          example: null
        permission:
          type:
          - string
          - 'null'
          example: null
        code:
          type: string
          description: Error code
          example: null
        message:
          type: string
          description: Error message
          example: null
        solution:
          type:
          - string
          - 'null'
          description: Possible solution to the error
          example: null
      example: null
    PublicEUDRSupplier:
      required:
      - id
      - isPublic
      - name
      - screened
      type: object
      properties:
        id:
          type: integer
          description: Supplier ID
          format: int32
          example: 101
        name:
          type: string
          description: Supplier name
          example: Acme Corp
        location:
          type:
          - string
          - 'null'
          description: Supplier location
          example: Vienna
        isPublic:
          type: boolean
          description: Indicates if the supplier profile is public
          example: true
        organization:
          allOf:
          - $ref: '#/components/schemas/PublicEUDROrganization'
          example: null
        screened:
          type: boolean
          description: Indicates if the supplier has been screened or not
          example: true
        references:
          type:
          - array
          - 'null'
          description: List of references associated with the supplier
          items:
            $ref: '#/components/schemas/PublicSupplierReference'
          example: null
        connectionContacts:
          type:
          - array
          - 'null'
          description: List of connection contacts for the supplier
          items:
            $ref: '#/components/schemas/PublicSupplierConnectionContact'
          example: null
        supplierMaturity:
          allOf:
          - $ref: '#/components/schemas/PublicSupplierMaturity'
          example: null
      description: Public representation of a supplier. Contains detailed supplier information, screening status, references, and connection contacts.
      example: null
    PublicConnectionContactPayload:
      required:
      - email
      type: object
      properties:
        email:
          type: string
          description: Email address of the connection contact.
          format: email
          example: contact@example.com
      description: Payload for creating or updating a connection contact. Contains the contact's email address.
      example: null
    PublicSupplierMaturity:
      type: object
      properties:
        answerStatus:
          type:
          - string
          - 'null'
          description: Enum representing possible statuses for a supplier's questionnaire answer in the public API.
          enum:
          - Requested
          - InProgress
          - Good
          - Critical
          example: null
        answerHidden:
          type:
          - boolean
          - 'null'
          description: True if the answer is hidden due to permission status (e.g., denied or not requested), otherwise false.
          example: null
      description: Public API payload representing the status of a supplier maturity assessment
      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
          - 'null'
          description: Email address of the connection contact. May be null if not provided.
          format: email
          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
    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
          - 'null'
          description: Possible solution to the error
          example: null
      description: Error response
      example: null
  securitySchemes:
    Token_authentication:
      type: apiKey
      description: Generate an API token at https://www.prewave.com/management/api and paste it in here.
      name: X-Auth-Token
      in: header