CommunitySupport PortalYouTubeStart a free trial

Vendors

Retrieving all vendors

get

Retrieves all vendors. You can filter, sort and paginate the results with query parameters.

Required scopes

  • vendor.vendor_read

  • vendor.vendor_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageNumberinteger · min: 1Optional

The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.

Default: 1
pageSizeinteger · min: 1Optional

The number of documents being retrieved on the page.

Default: 16
sortstringOptional

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case.

Example: name,metadata.createdAt:desc
qstringOptional

Query param for filtering entities by specified type. Examples of query params which are supported:

Q Param Description
name:"Exact match" find an entity with name field with Exact match value
name:~Supplier find an entity with name field containing Supplier value
type:COMPANY find an entity with type field with COMPANY value
metadata.createdAt:(>"2019-01-06T10:29:30.602Z" AND <"2020-01-07T10:29:30.602Z") find an entity with metadata.createdAt field with value between 2019-01-06T10:29:30.602Z and 2020-01-07T10:29:30.602Z
name:exists find an entity with existing name field
name:null find an entity with non-existing name field
Example: name:~supplier
fieldsstringOptional

Comma-separated list of fields to return in the response. If not specified, all fields are returned.

Example: name,type
idstringOptional

Vendor id. When specified, only vendor with the specified id will be returned.

namestringOptional

Vendor name. When specified, only vendors containing the specified name will be returned.

typestring · enumOptional

Vendor type. When specified, only vendors with the specified type will be returned.

Possible values:
parentIdstringOptional

The id of the parent vendor. When specified, only vendors with the specified parent will be returned.

legalInfo.legalNamestringOptional

The legal name of the vendor. When specified, only vendors containing the specified name will be returned.

legalInfo.registrationDatestringOptional

Vendor registration date. When specified, only vendors registered in the specified date will be returned.

legalInfo.countryOfRegistrationstringOptional

Vendor registration country. When specified, only vendors containing the specified registration country will be returned.

legalInfo.taxRegistrationNumberstringOptional

Vendor tax registration number. When specified, only vendors with the specified tax registration number will be returned.

Header parameters
X-Total-CountbooleanOptional

In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. If the header is provided and it is true then total count is returned in the X-Total-Count response header.

Default: false
Responses
200
The request was successful. A list of vendors is returned.
application/json
get
GET /vendor/{tenant}/vendors HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "VND001",
    "name": "Vendor Company",
    "type": "COMPANY",
    "parentId": "PARENT123",
    "legalInfo": {
      "legalName": "Vendor Company",
      "registrationDate": "2022-03-31T13:18:02.379Z",
      "countryOfRegistration": "US",
      "taxRegistrationNumber": "US-123456789"
    },
    "contactDetails": [
      {
        "emails": [
          "[email protected]"
        ],
        "phones": [
          "+1-555-0123"
        ],
        "addressLine1": "123 High Rd",
        "city": "South Bend",
        "state": "Indiana",
        "postcode": "46619",
        "countryCode": "US"
      }
    ],
    "locations": [
      {
        "id": "LOC001"
      }
    ],
    "metadata": {
      "version": 1,
      "mixins": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "createdAt": "text",
      "modifiedAt": "text"
    },
    "mixins": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Creating a vendor

post

Creates a new vendor for the tenant. A vendor represents a supplier or a business partner in the system.

Required scopes

  • vendor.vendor_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
Body
idstring · min: 1 · max: 66Optional

Custom vendor identifier. If not provided, it is automatically generated.

Example: VND001Pattern: ^[a-zA-Z0-9_-]+$
namestringRequired

The name of the vendor.

Example: Vendor Company
typestring · enumOptional

The type of the vendor. If not provided, the default value is: COMPANY.

Example: COMPANYPossible values:
parentIdstringOptional

The ID of the parent vendor.

Example: PARENT123
Responses
201
The request was successful. The vendor has been created.
application/json
post
POST /vendor/{tenant}/vendors HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 362

{
  "name": "Vendor Company",
  "type": "COMPANY",
  "legalInfo": {
    "legalName": "Vendor Company Inc.",
    "registrationDate": "2022-03-31T13:18:02.379Z",
    "countryOfRegistration": "US",
    "taxRegistrationNumber": "1234567890"
  },
  "contactDetails": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1-555-0123"
    }
  ],
  "locations": [
    {
      "id": "123e06ecf0452c2d6c0b81390"
    }
  ]
}
{
  "id": "53ac81fd0cce8b26b36f3492"
}

Searching with parameters for vendors

post

Retrieves all vendors that match the provided criteria.

Required scopes

  • vendor.vendor_read

  • vendor.vendor_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageNumberinteger · min: 1Optional

The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.

Default: 1
pageSizeinteger · min: 1Optional

The number of documents being retrieved on the page.

Default: 16
sortstringOptional

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case.

Example: name,metadata.createdAt:desc
fieldsstringOptional

Comma-separated list of fields to return in the response. If not specified, all fields are returned.

Example: name,type
idstringOptional

Vendor id. When specified, only vendor with the specified id will be returned.

namestringOptional

Vendor name. When specified, only vendors containing the specified name will be returned.

typestring · enumOptional

Vendor type. When specified, only vendors with the specified type will be returned.

Possible values:
parentIdstringOptional

The id of the parent vendor. When specified, only vendors with the specified parent will be returned.

legalInfo.legalNamestringOptional

The legal name of the vendor. When specified, only vendors containing the specified name will be returned.

legalInfo.registrationDatestringOptional

Vendor registration date. When specified, only vendors registered in the specified date will be returned.

legalInfo.countryOfRegistrationstringOptional

Vendor registration country. When specified, only vendors containing the specified registration country will be returned.

legalInfo.taxRegistrationNumberstringOptional

Vendor tax registration number. When specified, only vendors with the specified tax registration number will be returned.

Header parameters
X-Total-CountbooleanOptional

In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. If the header is provided and it is true then total count is returned in the X-Total-Count response header.

Default: false
Body
qstringOptional

Query param for filtering entities by specified type.

Responses
200
The request was successful. A list of vendors is returned.
application/json
post
POST /vendor/{tenant}/vendors/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "q": "type:COMPANY"
}
[
  {
    "id": "VND001",
    "name": "Vendor Company",
    "type": "COMPANY",
    "parentId": "PARENT123",
    "legalInfo": {
      "legalName": "Vendor Company",
      "registrationDate": "2022-03-31T13:18:02.379Z",
      "countryOfRegistration": "US",
      "taxRegistrationNumber": "US-123456789"
    },
    "contactDetails": [
      {
        "emails": [
          "[email protected]"
        ],
        "phones": [
          "+1-555-0123"
        ],
        "addressLine1": "123 High Rd",
        "city": "South Bend",
        "state": "Indiana",
        "postcode": "46619",
        "countryCode": "US"
      }
    ],
    "locations": [
      {
        "id": "LOC001"
      }
    ],
    "metadata": {
      "version": 1,
      "mixins": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "createdAt": "text",
      "modifiedAt": "text"
    },
    "mixins": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Retrieving a vendor

get

Retrieves a vendor by the specified unique identifier.

Required scopes

  • vendor.vendor_read

  • vendor.vendor_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
vendorIdstringRequired

The vendor unique identifier.

Query parameters
fieldsstringOptional

Comma-separated list of fields to return in the response. If not specified, all fields are returned.

Example: name,type
Responses
200
The request was successful. The requested vendor is returned.
application/json
get
GET /vendor/{tenant}/vendors/{vendorId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "123e06ecf0452c2d6c0b81390",
  "name": "Vendor Company",
  "type": "COMPANY",
  "legalInfo": {
    "legalName": "Vendor Company Inc.",
    "registrationDate": "2022-03-31T13:18:02.379Z",
    "countryOfRegistration": "US",
    "taxRegistrationNumber": "1234567890"
  },
  "contactDetails": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1-555-0123"
    }
  ],
  "locations": [
    {
      "id": "627e06ecf0452c2d6c0b81391",
      "name": "Main HQ",
      "type": "HEADQUARTER",
      "contactDetails": {
        "emails": [
          "[email protected]"
        ],
        "phones": [
          "1234567890"
        ],
        "addressLine1": "W Sample St",
        "city": "South Bend",
        "state": "Indiana",
        "postcode": "46619",
        "countryCode": "US"
      },
      "metadata": {
        "createdAt": "2022-03-31T13:18:02.379Z",
        "modifiedAt": "2022-03-31T13:18:02.379Z",
        "version": 1
      }
    }
  ],
  "metadata": {
    "createdAt": "2022-03-31T13:18:02.379Z",
    "modifiedAt": "2022-03-31T13:18:02.379Z",
    "version": 1
  }
}

Upserting a vendor

put

Updates or creates a vendor with a given vendor ID. You can omit the metadata.version, but then optimistic locking is not enabled.

Required scopes

  • vendor.vendor_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
vendorIdstringRequired

The vendor unique identifier.

Body
namestringRequired

The name of the vendor.

Example: Vendor Company
typestring · enumRequired

The type of the vendor.

Example: COMPANYPossible values:
parentIdstringOptional

The ID of the parent vendor.

Example: PARENT123
Responses
201
The request was successful. The vendor has been created.
application/json
put
PUT /vendor/{tenant}/vendors/{vendorId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 403

{
  "name": "Updated Vendor Company",
  "type": "COMPANY",
  "legalInfo": {
    "legalName": "Updated Vendor Company Inc.",
    "registrationDate": "2022-03-31T13:18:02.379Z",
    "countryOfRegistration": "US",
    "taxRegistrationNumber": "1234567890"
  },
  "contactDetails": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1-555-0123"
    }
  ],
  "locations": [
    {
      "id": "123e06ecf0452c2d6c0b81390"
    }
  ],
  "metadata": {
    "version": 1
  }
}
{
  "id": "53ac81fd0cce8b26b36f3492"
}

Delete a vendor

delete

Deletes a vendor.

Required scopes

  • vendor.vendor_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
vendorIdstringRequired

The vendor unique identifier.

Responses
204
The vendor has been deleted successfully.
delete
DELETE /vendor/{tenant}/vendors/{vendorId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content
PreviousAPI ReferenceNextLocations

Was this helpful?