Skip to main content

Create a business partner with delivery channels​


This recipe covers creating a business partner with the delivery channels available for their country, updating channel settings, and retrieving the partner's channel configuration.

Prerequisites​

Terminology

  • A business partner is represented by a connection in the API.
  • A delivery channel is represented by a connector.
  • Business partners can be customers or suppliers.
Step 1: Create a business partner

Depending on the business partner's country and the delivery channels available in Banqup, supported connectors are activated when you create the business partner.
Available connectors in Banqup: Peppol, Email, KSeF.


Endpoint: /network/core/transaction/v1/spaces/{spaceId}/connections


Path parameter:

  • spaceId

Requires a JSON request body.

curl -L -X POST 'https://{{serverURL}}/network/core/transaction/v1/spaces/{spaceId}/connections' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
        "type": "BUSINESS",
        "businessType": "ENTERPRISE",
        "globalIdentifiers": {
          "be:en": "0428074917", 
          "be:vat": "BE0428074917",
          "global:email": [
            "john@example.com"
          ],
          "global:phoneNumber": [ "+33612345678" ]
        },
        "alias": "UP",
        "connectionStatus": "CONNECTED",
        "relationType": "CUSTOMER",
        "addresses": {
          "main": {
            "streetName": "Fleurs",
              "house": "80728",
              "postalCode": "3110",
              "city": "Antwerp",
              "country": "Belgium",
              "countryCode": "BE"
          }
        },
        "tags": [
         "customer"
        ],
        "active": true,
        "metadata": {
            "department": "Accounting",
            "logo": "https://somelinks.com/logo.jpg",
            "website": "https://mycompanywebsite.com",
            "notes": "some notes",
            "industry": "Agriculture, Forestry And Fishing"
        },
        "legalName": "ABC Group",
        "tradeName": "ABC"
}'

Successful response: Save the id (connectionId) returned in the response for further use.


{
  "type": "BUSINESS",
  "id": "dc416b68-eeac-430f-a4fa-0441ae1b1768",
  "globalIdentifiers": {
    "global:email": [
      "john@example.com"
    ],
            "be:en": "0428074917",
            "be:vat": "BE0428074917",
            "global:participantId": "0208:0428074917",
            "global:phoneNumber": [
      "+33612345678"
    ]
  },
  "assignedAccountId": "000001",
          "alias": "UP",
          "connectionStatus": "CONNECTED",
          "relationTypes": [
    "CUSTOMER"
  ],
          "addresses": {
    "main": {
      "streetName": "Fleurs",
              "buildingNumber": "123",
              "postalCode": "3110",
              "city": "Antwerp",
              "country": "Belgium",
              "countryCode": "BE"
    }
  },
  "tags": [
    "customer"
  ],
          "active": true,
          "createdAt": "2026-04-16T12:09:08.058444Z",
          "metadata": {
    "logo": "https://somelinks.com/logo.jpg",
            "notes": "some notes",
            "website": "https://mycompanywebsite.com",
            "industry": "Agriculture, Forestry And Fishing",
            "department": "Accounting"
  },
  "connectors": [
    {
      "extensionId": "baf65c82-e645-4c75-89f1-69df0c017ec3",
      "active": true,
      "name": "peppol",
      "namespace": "com.unifiedpost.btx.connectors",
      "settings": {
        "matches": {
          "docTypes": [
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
              "scheme": "busdox-docid-qns"
            }
          ],
          "participantId": {
            "value": "0208:0428074917",
            "scheme": "iso6523-actorid-upis"
          }
        }
      }
    },
    {
      "extensionId": "c1fc7056-dfb3-4e55-9922-8fc76473a17e",
      "active": true,
      "name": "email",
      "namespace": "com.unifiedpost.btx.connectors",
      "settings": {
        "email": "john@example.com"
      }
    }
  ],
          "legalName": "ABC Group",
          "tradeName": "ABC",
          "businessType": "ENTERPRISE"
}

Step 2: Configure the business partner's delivery channels
Use case 1: Activate/deactivate a delivery channel

The request replaces the business partner's connector configuration. Include every connector that should remain configured, and set active to false for a connector you want to deactivate.


Endpoint: /network/core/transaction/v3/spaces/{spaceId}/connections/{connectionId}/connectors


Path parameters:

  • spaceId
  • connectionId

Requires a JSON request body (see curl example below - deactivating the Email connector).

curl -L -X PUT 'https://{{serverURL}}/network/core/transaction/v3/spaces/{spaceId}/connections/{connectionId}/connectors' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '[
{
  "name": "peppol",
        "active": true,
        "settings": {
  "matches": {
    "docTypes": [
      {
        "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
        "scheme": "busdox-docid-qns"
      },
      {
        "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1",
        "scheme": "busdox-docid-qns"
      },
      {
        "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        "scheme": "busdox-docid-qns"
      },
      {
        "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
        "scheme": "busdox-docid-qns"
      },
      {
        "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        "scheme": "busdox-docid-qns"
      },
      {
        "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
        "scheme": "busdox-docid-qns"
      }
    ],
            "participantId": {
      "value": "9925:BE0428074917",
              "scheme": "iso6523-actorid-upis"
    }
  }
},
  "namespace": "com.unifiedpost.btx.connectors",
        "extensionId": "baf65c82-e645-4c75-89f1-69df0c017ec3"
},
{
  "name": "email",
        "active": false,
        "namespace": "com.unifiedpost.btx.connectors",
        "extensionId": "c1fc7056-dfb3-4e55-9922-8fc76473a17e",
        "searchResults": []
}
]'


Successful response:


[
  {
    "name": "peppol",
    "active": true,
    "settings": {
      "matches": {
        "docTypes": [
          {
            "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
            "scheme": "busdox-docid-qns"
          },
          {
            "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1",
            "scheme": "busdox-docid-qns"
          },
          {
            "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
            "scheme": "busdox-docid-qns"
          },
          {
            "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
            "scheme": "busdox-docid-qns"
          },
          {
            "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
            "scheme": "busdox-docid-qns"
          },
          {
            "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
            "scheme": "busdox-docid-qns"
          }
        ],
        "participantId": {
          "value": "9925:BE0428074917",
          "scheme": "iso6523-actorid-upis"
        }
      }
    },
    "namespace": "com.unifiedpost.btx.connectors",
    "extensionId": "baf65c82-e645-4c75-89f1-69df0c017ec3"
  },
  {
    "name": "email",
    "active": false,
    "namespace": "com.unifiedpost.btx.connectors",
    "extensionId": "c1fc7056-dfb3-4e55-9922-8fc76473a17e",
    "searchResults": []
  }
]

Use case 2: Change the Peppol participant ID

Endpoint: datastore/documents/transaction/v2/spaces/{spaceId}/connections/{connectionId}


Path parameters:

  • spaceId
  • connectionId

Requires a JSON request body.

curl -L -X PATCH 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/connections/{connectionId}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-data-raw '{
"type": "BUSINESS",
        "globalIdentifiers": {
  "be:en": "0428074917",
          "be:vat": "BE0428074917",
          "global:participantId": "9925:BE0428074917",
          "global:email": [ "john@example.com" ]}
}'

Successful response:


{
    "type": "BUSINESS",
    "id": "dc416b68-eeac-430f-a4fa-0441ae1b1768",
    "globalIdentifiers": {
        "be:en": "0428074917",
        "be:vat": "BE0428074917",
        "global:participantId": "9925:BE0428074917",
        "global:email": [
            "john@example.com"
        ]
    },
    "assignedAccountId": "000001",
    "alias": "UP",
    "connectionStatus": "CONNECTED",
    "relationTypes": [
        "CUSTOMER"
    ],
    "addresses": {
        "main": {
            "streetName": "St-Hendriksvoorplein",
            "buildingNumber": "44",
            "postalCode": "1200",
            "city": "Sint-Lambrechts-Woluwe",
            "country": "Belgium",
            "countryCode": "BE"
        },
        "registration": {
            "country": "Belgium",
            "countryCode": "BE"
        }
    },
    "tags": [
        "customer"
    ],
    "active": true,
    "createdAt": "2026-04-14T13:27:29.059239Z",
    "metadata": {
        "logo": "https://somelinks.com/logo.jpg",
        "notes": "some notes",
        "website": "https://mycompanywebsite.com",
        "industry": "Agriculture, Forestry And Fishing",
        "department": "Accounting"
    },
    "connectors": [
        {
            "extensionId": "baf65c82-e645-4c75-89f1-69df0c017ec3",
            "active": true,
            "name": "peppol",
            "namespace": "com.unifiedpost.btx.connectors",
            "settings": {
                "matches": {
                    "participantId": {
                        "scheme": "iso6523-actorid-upis",
                        "value": "9925:BE0428074917"
                    },
                    "docTypes": [
                        {
                            "scheme": "busdox-docid-qns",
                            "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1"
                        },
                        {
                            "scheme": "busdox-docid-qns",
                            "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1"
                        },
                        {
                            "scheme": "busdox-docid-qns",
                            "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
                        },
                        {
                            "scheme": "busdox-docid-qns",
                            "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1"
                        },
                        {
                            "scheme": "busdox-docid-qns",
                            "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
                        },
                        {
                            "scheme": "busdox-docid-qns",
                            "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1"
                        }
                    ]
                }
            }
        },
        {
            "extensionId": "c1fc7056-dfb3-4e55-9922-8fc76473a17e",
            "active": true,
            "name": "email",
            "namespace": "com.unifiedpost.btx.connectors",
            "settings": {
                "email": "john@example.com"
            }
        }
    ],
    "legalName": "ABC Group",
    "tradeName": "ABC",
    "businessType": "ENTERPRISE"
}

Troubleshooting:


Peppol delivery failures
  • Verify that the participant ID uses the expected scheme and format.
  • Verify that the docTypes values match the document types supported by the Peppol connector.
Email connector not receiving messages
  • Verify that active: true is set for the email connector in the connectors array.
  • Verify that settings.email contains the correct recipient email address.
Step 3: View a business partner's delivery channels

Endpoint: /network/core/transaction/v1/spaces/{spaceId}/connections/{connectionId}


Path parameter:

  • spaceId
  • connectionId 
curl -L 'https://{{serverURL}}/network/core/transaction/v1/spaces/{spaceId}/connections/{connectionId}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

{
  "type": "BUSINESS",
  "id": "dc416b68-eeac-430f-a4fa-0441ae1b1768",
  "globalIdentifiers": {
    "be:en": "0428074917",
            "be:vat": "BE0428074917",
            "global:email": [
      "john@example.com"
    ],
    "global:participantId": "9925:BE0428074917"
  },
  "assignedAccountId": "000001",
          "alias": "UP",
          "connectionStatus": "CONNECTED",
          "relationTypes": [
    "CUSTOMER"
  ],
  "addresses": {
    "main": {
      "streetName": "St-Hendriksvoorplein",
              "buildingNumber": "44",
              "postalCode": "1200",
              "city": "Sint-Lambrechts-Woluwe",
              "country": "Belgium",
              "countryCode": "BE"
    },
    "registration": {
      "country": "Belgium",
              "countryCode": "BE"
    }
  },
  "tags": [
   "customer"
  ],
  "active": true,
  "createdAt": "2026-04-14T13:27:29.059239Z",
  "metadata": {
    "logo": "https://somelinks.com/logo.jpg",
    "notes": "some notes",
    "website": "https://mycompanywebsite.com",
    "industry": "Agriculture, Forestry And Fishing",
    "department": "Accounting"
  },
  "connectors": [
    {
      "name": "peppol",
      "active": true,
      "settings": {
        "matches": {
          "docTypes": [
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
              "scheme": "busdox-docid-qns"
            },
            {
              "value": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
              "scheme": "busdox-docid-qns"
            }
          ],
          "participantId": {
            "value": "9925:BE0428074917",
            "scheme": "iso6523-actorid-upis"
          }
        }
      },
      "namespace": "com.unifiedpost.btx.connectors",
      "extensionId": "baf65c82-e645-4c75-89f1-69df0c017ec3"
    },
    {
      "name": "email",
      "active": false,
      "settings": {
        "email": "john@example.com"
      },
      "namespace": "com.unifiedpost.btx.connectors",
      "extensionId": "c1fc7056-dfb3-4e55-9922-8fc76473a17e"
    }
  ],
          "displayName": "ABC Group",
          "legalName": "ABC Group",
          "tradeName": "ABC",
          "businessType": "ENTERPRISE"
}