Managing Companies

Create, update, list, and delete company profiles in Recommand for Peppol document exchange. Includes Peppol registration and field reference.

This guide explains how to create, update, and manage company profiles in Recommand for Peppol document exchange using the Recommand API.

Overview

A company in Recommand represents a business entity that can send or receive Peppol documents. Each company must be registered before it can participate in document exchange.

Only add companies you operate

Only add companies that you are responsible for — typically your own organization or entities you manage. Do not add companies that you send documents to (customers) or receive documents from (suppliers). Those companies manage their own Peppol registration independently. Trying to add them to your account will cause registration conflicts.

Prerequisites

  • A Recommand account with API access
  • Your API key and secret
  • Your team ID

Retrieving Your Team ID

Your team ID is required for most company management operations. You can find it in the Recommand dashboard under Account > API Keys.

Strict Identifier Validation

Recommand enforces strict format validation on Peppol identifiers and company VAT and enterprise numbers. Numbers that do not pass national validation rules (such as the Belgian modulo-97 check digit) are rejected at creation and update time. Ensure the values you submit are correctly formatted.

Listing Companies

To retrieve all companies associated with your team using the list companies endpoint:

async function listCompanies() {
  const response = await fetch(
    `https://app.recommand.eu/api/v1/companies`,
    {
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
      },
    }
  );

  const result = await response.json();
  return result.companies;
}

// Example usage
const companies = await listCompanies("your_team_id");
companies.forEach((company) => {
  console.log(`${company.name} (${company.id})`);
});

Creating a Company

To create a new company using the create company endpoint. When creating a new company, it is automatically registered in the Peppol network. If the company is already registered through another provider, this will fail. Companies that are registered with the Belgian government portal Hermes (as is the case for most Belgian companies) are automatically migrated over to Recommand.

async function createCompany(companyData) {
  const response = await fetch(
    `https://app.recommand.eu/api/v1/companies`,
    {
      method: "POST",
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify(companyData),
    }
  );

  return response.json();
}

// Example usage
const newCompany = await createCompany("your_team_id", {
  name: "ACME Corporation",
  address: "123 Main Street",
  postalCode: "1000",
  city: "Brussels",
  country: "BE",
  enterpriseNumber: "0123456789",
  vatNumber: "BE0123456789",
});

if (newCompany.success) {
  console.log(`Company created with ID: ${newCompany.company.id}`);
  console.log(`Verification URL: ${newCompany.verificationUrl}`);
  // Present this URL to your user — they can complete or forward the identity check from there
} else {
  console.error("Failed to create company:", newCompany.errors);
}

Company Fields

FieldDescriptionRequiredExample
nameCompany nameYes"ACME Corporation"
addressStreet addressYes"123 Main Street"
postalCodePostal/zip codeYes"1000"
cityCityYes"Brussels"
countryCountry code (2-letter ISO code)Yes"BE"
enterpriseNumberEnterprise numberNo"0123456789"
vatNumberVAT registration numberNo"BE0123456789"
isVerifiedWhether the company has been verified (read-only)—false

Retrieving a Company

To get details about a specific company using the get company endpoint:

async function getCompany(companyId) {
  const response = await fetch(
    `https://app.recommand.eu/api/v1/companies/${companyId}`,
    {
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
      },
    }
  );

  return response.json();
}

// Example usage
const companyDetails = await getCompany("your_team_id", "company_id");
if (companyDetails.success) {
  console.log(companyDetails.company);
} else {
  console.error("Failed to retrieve company:", companyDetails.errors);
}

Updating a Company

To update an existing company using the update company endpoint:

async function updateCompany(companyId, updatedData) {
  const response = await fetch(
    `https://app.recommand.eu/api/v1/companies/${companyId}`,
    {
      method: "PUT",
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify(updatedData),
    }
  );

  return response.json();
}

// Example usage
const updateResult = await updateCompany("company_id", {
  name: "ACME Corporation Updated",
  address: "456 New Street",
  postalCode: "1000",
  city: "Brussels",
  country: "BE",
  enterpriseNumber: "0123456789",
  vatNumber: "BE0123456789",
});

if (updateResult.success) {
  console.log("Company updated successfully");
  // If vatNumber or enterpriseNumber changed, isVerified is reset to false — reverification required
} else {
  console.error("Failed to update company:", updateResult.errors);
}

Updating identifiers resets verification

If you update a company's vatNumber or enterpriseNumber, isVerified is automatically reset to false and the company must be verified again before it can participate on the Peppol network.

Deleting a Company

To delete a company using the delete company endpoint:

async function deleteCompany(companyId) {
  const response = await fetch(
    `https://app.recommand.eu/api/v1/companies/${companyId}`,
    {
      method: "DELETE",
      headers: {
        Authorization:
          "Basic " +
          Buffer.from("your_api_key:your_api_secret").toString("base64"),
      },
    }
  );

  return response.json();
}

// Example usage
const deleteResult = await deleteCompany("your_team_id", "company_id");
if (deleteResult.success) {
  console.log("Company deleted successfully");
} else {
  console.error("Failed to delete company:", deleteResult.errors);
}

Verifying a Company

After creating a company, an authorised representative must complete an identity check before the company can send or receive documents on the Peppol network. The isVerified field on a company object reflects whether this step has been completed.

The create company response already includes a verificationUrl — present it to your user straight away. The verification page lets them forward the link to the right person within their organisation. If you need a fresh URL later (e.g. the link was lost or you want to verify an existing company), call the verify company endpoint:

const result = await fetch(
  `https://app.recommand.eu/api/v1/companies/${companyId}/verify`,
  {
    method: "POST",
    headers: {
      Authorization:
        "Basic " +
        Buffer.from("your_api_key:your_api_secret").toString("base64"),
    },
  }
).then((r) => r.json());

if (result.success) {
  console.log("Verification URL:", result.verificationUrl);
  // Present this URL to your user — they can complete or forward the identity check from there
}

Verification can also be completed directly from the Recommand dashboard without using the API. For the full flow, see the Company Verification guide.

Complete Example: Company Management

Here's a full example of creating, updating, and managing companies:

// Setup authentication
const API_KEY = "your_api_key";
const API_SECRET = "your_api_secret";
const TEAM_ID = "your_team_id";
const auth =
  "Basic " + Buffer.from(`${API_KEY}:${API_SECRET}`).toString("base64");
const baseUrl = "https://app.recommand.eu/api/peppol";

// Create a new company
async function createCompany() {
  const response = await fetch(`${baseUrl}/companies`, {
    method: "POST",
    headers: {
      Authorization: auth,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Test Company",
      address: "123 Test Street",
      postalCode: "1000",
      city: "Brussels",
      country: "BE",
      enterpriseNumber: "0123456789",
      vatNumber: "BE0123456789",
    }),
  });

  const result = await response.json();
  if (result.success) {
    console.log(`Company created with ID: ${result.company.id}`);
    return result.company.id;
  } else {
    console.error("Failed to create company:", result.errors);
    return null;
  }
}

// List all companies
async function listCompanies() {
  const response = await fetch(`${baseUrl}/companies`, {
    headers: { Authorization: auth },
  });

  const result = await response.json();
  if (result.success) {
    console.log("Companies:");
    result.companies.forEach((company) => {
      console.log(`- ${company.name} (${company.id})`);
    });
    return result.companies;
  } else {
    console.error("Failed to list companies:", result.errors);
    return [];
  }
}

// Update a company
async function updateCompany(companyId) {
  const response = await fetch(`${baseUrl}/companies/${companyId}`, {
    method: "PUT",
    headers: {
      Authorization: auth,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Updated Test Company",
      address: "456 Updated Street",
      postalCode: "1000",
      city: "Brussels",
      country: "BE",
      enterpriseNumber: "0123456789",
      vatNumber: "BE0123456789",
    }),
  });

  const result = await response.json();
  if (result.success) {
    console.log("Company updated successfully");
    return true;
  } else {
    console.error("Failed to update company:", result.errors);
    return false;
  }
}

// Delete a company
async function deleteCompany(companyId) {
  const response = await fetch(`${baseUrl}/companies/${companyId}`, {
    method: "DELETE",
    headers: { Authorization: auth },
  });

  const result = await response.json();
  if (result.success) {
    console.log("Company deleted successfully");
    return true;
  } else {
    console.error("Failed to delete company:", result.errors);
    return false;
  }
}

// Example workflow
async function manageCompanies() {
  // List existing companies
  console.log("Existing companies:");
  await listCompanies();

  // Create a new company
  console.log("\nCreating a new company...");
  const companyId = await createCompany();
  if (!companyId) return;

  // List companies again to see the new one
  console.log("\nUpdated company list:");
  await listCompanies();

  // Update the company
  console.log("\nUpdating the company...");
  await updateCompany(companyId);

  // List companies again to see the update
  console.log("\nAfter update:");
  await listCompanies();

  // Delete the company
  console.log("\nDeleting the company...");
  await deleteCompany(companyId);

  // Final company list
  console.log("\nFinal company list:");
  await listCompanies();
}

// Run the workflow
manageCompanies().catch((error) => {
  console.error("Error in company management workflow:", error);
});

Best Practices

  1. Check Peppol Registration: Before creating a company, check if the company is already registered in the Peppol network.
  2. Validate data: Ensure company information is accurate before creating or updating
  3. Handle errors: Implement proper error handling for API responses
  4. Check before delete: Ensure a company is not in use before deleting it
  5. Limit company creation: Create only the companies you need to avoid clutter

Next Steps

Sending Invoices

Create and send invoices from your companies.

Sending Credit Notes

Issue credit notes to correct invoices.

Working with Webhooks

Receive events across your companies and teams.

Company Verification

Verify a company before it can participate on the Peppol network.

Verifying Recipients

Check recipients before sending documents.

Complete API Reference

Explore all endpoints and models.

Authentication

Learn how to authenticate with the Recommand Peppol API using Basic API keys, JWT bearer tokens, or OAuth2 with JWT assertion.

Company Verification

Verify that a company representative is authorised to act on behalf of a company before it can participate on the Peppol network.

On this page

OverviewPrerequisitesRetrieving Your Team IDStrict Identifier ValidationListing CompaniesCreating a CompanyCompany FieldsRetrieving a CompanyUpdating a CompanyDeleting a CompanyVerifying a CompanyComplete Example: Company ManagementBest PracticesNext Steps