Skip to content

Business Partner Resource

Introduction

A business partner in the Open Publishing ecosystem are all persons a customer will interact with. They can be human beings or cooperations. Business partners can be buyers of products, contributors or owners of products or royalty recipients.

Example URL

https://api.openpublishing.com/resource/v3/business_partners/[ID]

Allowed methods: GET, PUT, DELETE.

For creating a business partner POST an object to https://api.openpublishing.com/resource/v3/business_partners.

Search Filters

List business_partners:

https://api.openpublishing.com/resource/v3/business_partners

General search (fulltext search on various fields).

https://api.openpublishing.com/resource/v3/business_partners?q=test

Filter by external identifiers:

https://api.openpublishing.com/resource/v3/business_partners?external_identifier_type=klopotek&external_identifier_value=503107

external_identifier_type / external_identifier_value : Search for business partners with an external identifier set. The external identifier type is the category of the businesspartner, e.g. "paypal" whereas the value is the id itself. If only external_identifier_type is specified, all business partners with the external identifier type set are returned. If you search for only external_identifier_value - the system will return all identifiers with the value, where the type is not set.

Search for all Business Partners which are contractors:

https://api.openpublishing.com/resource/v3/business_partners?contractor=true

Search for all Business Partners which are team members:

https://api.openpublishing.com/resource/v3/business_partners?team=true

Search for last name or firstname:

https://api.openpublishing.com/resource/v3/business_partners?last_name=test
https://api.openpublishing.com/resource/v3/business_partners?first_name=test

Fields

Academic title

academic_title string or null containing the academic title of the customer.

Bank Details

bank_details contain the information of a bank account of a customer. It contains a dict with the following fields:

  • account_holder: Name of the holder of the account.
  • iban: IBAN of the bank account.
  • bic: SWIFT BIC of the bank account. This field is required for none SEPA bank accounts.

Biography

biography of the business partner. Can be NULL or a string.

Company account

company_account is a boolean indicating if the business partner is a company or a person.

Corporate name

corporate_name describes the name of the company for company accounts.

Contractor

contractor is a boolean indicating if the business partner may be a contracting party. It is a read only field.

Creditor ID and Debitor ID

creditor_id and debitor_id refer to the identifier in an external accounting software (e.g. Datev or SAP).

Email

email : Email address of business partner. Can be null or a string.

External Identifiers

external_identifiers: List of external/foreign identifiers, e.g. the id of the business partner within Klopotek, Paypal or Amazon. The listed objects are dicts with the values type for the type of the identifier and value for the identifier itself.

Fax

fax field contains fax number of business partner.

First name

first_name: First name of business partner. Can be null or a string.

Gender

gender: Gender of business partner. 'm' (male), 'f' (female), 'd' (diverse) or null.

Labels

The labels field contains a list of strings internally used for marking and grouping business partners. These labels may be used to control the internal workflow and are not exported to external partners.

Language

language: Language of the business partner in ISO-639-2/B or null.

Last name

last_name: Last name of business partner. Can be null or a string.

Note

note field may be used to store internal notes about the customer. E.g. for which reason a value was changed.

ORCID

orcid: ORCD ID of the business partner.

Phone

phone field contains phone number of business partner.

Realm

realm is the Open Publishing terminology for tenant. It contains a dict with _id and name and screenname.

Screenname

screenname is a read only field with a calculated screen name of the business partner. The name is calculated out of the fields academic_title, first_name, last_name and corporate_name.

Tax details

tax_details contain the information related with taxing. It contains a dict with the following fields:

  • subject_to_german_ksk_fund: Boolean indicating if the publisher has to pay taxes for the German KSK for the business partner.
  • subject_to_vat: Boolean indicating if the business partner is subject to VAT.
  • tax_address: String with the tax address of the business partner ("Steuerwohnsitz").
  • tax_authority: Name of the tax authority.
  • tax_country: country in which the business partner has legal tax obligations.
  • tax_id: A string or null for the (income) tax id of the business partner.
  • vat_rate_type: Either null for automatic vat calculation or the string values "standard" or "reduced".
  • vat_id: String or null containing the VAT-ID of the business partner.

Team

team is a read only boolean field describing if the business partner is part of the team of the publisher. If set to yes, this person has right to log in to the backend.

Example JSON

{
    "_id": 147,
    "academic_title": "Dr.",
    "bank_details": {
      "account_holder": "John Doe",
      "bic": "HYVEDEMMXXX",
      "iban": "DE28700202700123456789"
    },
    "biography": "Lorem ipsum",
    "company_account": false,
    "contractor": false,
    "corporate_name": null,
    "creditor_id": null,
    "debitor_id": null,
    "email": "john.doe@openpublishing.com",
    "external_identifiers":
       [
          {
             "type": "PAYPAL",
             "value": "LRXSQA2JR8X4"
          },
          {
             "type": "FACEBOOK",
             "value": "510952107"
          }
       ],
    "fax": "+49 89 123124",
    "first_name": "John",
    "gender": "m",
    "labels": ["one", "two", "three"],
    "language": "eng",
    "last_name": "Doe",
    "note": "Changed bank details on customer request, 2022-01-23",
    "orcid": null,
    "phone": "+49 89 123123",
    "realm": {
      "_id": 23,
      "name": "testpublisher",
      "screenname": "Test Publisher"
    },
    "screenname": "John Doe",
    "tax_details": {
      "subject_to_german_ksk_fund": true,
      "subject_to_vat": true,
      "tax_address": null,
      "tax_authority": null,
      "tax_country": null,
      "tax_id": null,
      "vat_rate_type": null,
      "vat_id": null
    }
    "team": false
}

Files

Additionally assets and files associated with a business partner may be stored to the following endpoint. URL:

https://api.openpublishing.com/resource/v3/business_partners/[ID]/files
https://api.openpublishing.com/resource/v3/business_partners/[ID]/files/[ID]

For adding files, POST to above URL with an multipart/form encoded body with the following parameters:

  • file the file itself
  • type of the file. An arbitrary string, e.g. avatar.

The URL also supports GET for retrieving information about uploaded files. It contains a JSON with the following fields:

  • file_name : File name of uploaded file.
  • file_size : File size in bytes.
  • mime_type : mime type of file, e.g. application\/xml.
  • href : URL to download file.
  • labels : labels of file - at the moment read only.
  • properties : Properties of file - at the moment read only.
  • sha1 : SHA1 checksum of uploaded file..
  • timestamp : Unix timestamp when file was uploaded.
  • type : type of the file. An arbitrary string, e.g. avatar.

Example JSON:

{
  "_id": 14657,
  "file_name": "10667364.png",
  "file_size": 450978,
  "mime_type": "image\/png",
  "href": "https:\/\/api.openpublishing.com\/resource\/v3\/business_partners\/128\/file\/14657\/file",
  "labels": [],
  "properties": {},
  "sha1": "5fc48f2945b36f886ae9588a887bf1a4ebc00fae",
  "timestamp": 1645561315,
  "type": "avatar"
}

E-Mail Addresses

The Email Address sub-resource provides contact email information for a Business Partner. This resource supports multiple email addresses per Business Partner and allows designation of a primary email, verification status, and activation state.

Endpoint:

GET https://api.openpublishing.com/resource/v3/business_partners/[ID]/email_addresses
GET https://api.openpublishing.com/resource/v3/business_partners/[ID]/email_addresses/[ID]

The email_address resource includes the following fields:

  • _id: Unique identifier for the email address
  • active: Boolean value that tndicates whether the email address is active (default: true), e.g. blacklisted emails are not active.
  • email: The email address
  • primary: Boolean value that marks the email as the primary contact (default: false)
  • verified: Boolean value that indicates whether the email has been verified (default: false)

Example JSON:

{
    "_id": 621453,
    "_links": {
    "self": "https://api.dev.openpublishing.com/resource/v3/business_partners/358370/email_addresses/621453"
    },
    "active": true,
    "email": "bob.martin@company.com",
    "primary": true,
    "verified": true
}