Skip to main content

Company-scoped methods

Most of our API resources are not owned by the user, but by a company. This makes it possible for all the users who have access to a single company to interact with all the resources it owns (if the user has the related permissions, of course). This is why most of our methods are Company-scoped: it means that you need to provide an additional company_id parameter to use the method correctly.

There is much more!

The methods explained on this page provide some useful information other than the Company ID! Check the Plan Management page to know more about it!

🔬  Where can I find my company_id?​

One of the questions that we receive more often is: "How can I find my company_id?" Don't worry, it is really easy.

🗿  One-shot methods​

The one-shot methods are the easier way to retrieve the Company ID, but they can be used only if you have control of all the companies that will use your integration.

For example, if you are developing a one-time script or an application that is meant to be used with a single company, we suggest you retrieve the Company ID once and hardcode it. Similarly, while testing our APIs using Postman or our API Reference you will most probably deal with a single company, so you can retrieve the Company ID once and use it in your tests.

In this case, you can find your Company ID in two places.

The easier way is to access the Fatture in Cloud web application, you will find it at the top left of the page, next to the company name.

FIC Company ID



As an alternative, you can also use our Utilities tool to retrieve the Company ID, as explained here. Once the Login and Permission steps are completed, the Company ID will be shown on the page, so you just have to copy it and paste it into your code.

🐝  API method​

The API method is for sure the most complicated way to retrieve the Company ID, but at the same time, it is the most flexible way to obtain it, as it allows you to retrieve the ID dynamically.

For example, it is really useful if you don't know who will use your integration once published, and you want to provide the user with the list of Companies he can control through the Fatture in Cloud APIs.

You can dynamically list all the companies controlled by the current user using the List User Companies method, which will return you an array of companies. Of course, this method is not company-scoped! 😁  You just need to select the right company from the returned list and extract its ID, and you're done!

You can use the API method also for the use cases described in the previous section, for example using our API Reference or our Postman Collection to perform the API call, and then insert it as a constant in your code; these tools can also be used to test the API method before implementing it into your code.

Here you can find the steps to use the API Reference to retrieve the Company ID:

  • Obtain a valid Access Token using one of the available methods;
  • Open the Auth Section in the API Reference, and insert the copied access token in the "HTTP BEARER" Section (please, don't add "Bearer" to the token, the tool will take care of it!);
  • Search the List User Companies method and click the "Try" button, the Company ID will be included in the obtained response.

Here you can find some examples, based on our SDKs, to retrieve the Company ID from your code.

using System.Collections.Generic;
using System.Diagnostics;
using It.FattureInCloud.Sdk.Api;
using It.FattureInCloud.Sdk.Client;
using It.FattureInCloud.Sdk.Model;

Configuration config = new Configuration();
// Check out the Authentication section to retrieve the Access Token
config.AccessToken = "YOUR_ACCESS_TOKEN";

var apiInstance = new UserApi(config);

try
{
    // List User Companies
    ListUserCompaniesResponse result = apiInstance.ListUserCompanies();
    // In the result you'll find a list of companies, you must use the "Id" field of one of those
    Console.Write(result.Data.Companies[0].Id);
}
catch (ApiException  e)
{
    Console.Write("Exception when calling UserApi.ListUserCompanies: " + e.Message);
    Console.Write("Status Code: " + e.ErrorCode);
    Console.Write(e.StackTrace);
}
Retrieve your ACCESS TOKEN!

You can set the Access Token in the dedicated section, for more informations look here.

If you want more examples, you can find them in the Readme file of each SDK or in the Quickstart section.

If you want to retrieve the details of a specific company, you can always use the Get Company Info method, but in this case, this method is company-scoped, so you need an ID! 😉 

And what about Zapier?

Zapier will automatically retrieve the Companies list for you, so you can just select the one you want to use from the related dropdown menu.
The List User Companies Action is still available in our Zapier integration, so you can still use it if needed.

If you want to know more about it, check the Zapier Quickstart page.

🙋‍♂️  How can I know if a method is company-scoped?​

The majority of our methods are company-scoped, so there's a high probability that the method you need to use is included in this group. If you want to be sure if your API method is actually company-scoped, you just need to check if it requires a company_id parameter.

In order to do it, you have a few possibilities:

🌍  Check on the API Reference​

This is the easier option, that only requires you to search the method on our API Reference section. For example, let's check the List Issued Documents method. Checking the URL on top of the page, you can notice that it contains the /c/{company_id} portion, indicating that it is a company-scoped URL that requires to substitute the placeholder to be executed correctly.

API Reference Method URL API Reference Method URL

On the same page, you can also check if you have a company_id box in the Path Params section: here you must insert your companyid while trying to use the API method using the _Try button.

API Reference Method Path Params API Reference Method Path Params

💼  Check on your SDK documentation​

If you're using a specific SDK, probably it will be easier for you to take advantage of it to check if a method is company-scoped: all the methods that are in this category require an integer company_id to be executed correctly. You can check if the company_id parameter is required by checking the signature of your method (for example using your IDE's functionalities) or accessing your SDK's documentation. Read your SDK's page for further info.

For example, using our PHP SDK you have two alternatives:

  • Accessing the GitHub page of the List Issued Documents method and check if it requires the company_id parameter
  • Use your favorite IDE to check if the method requires it, without having to access our documentation online
  • Some of the SDKs provide standard documentation for the language they're based on; for example, Java's JavaDoc or Ruby's RubyDoc.

📬  Check our Postman Collection​

If you're testing our API using our Postman Collection, you can check if the method needs the companyid parameter. You can check if the method's URL includes the /c/:company_id portion, where :companyid is the placeholder that must be replaced with the actual numeric ID:

Postman url Postman url

Otherwise, similarly to what you can do in our API Reference section, you can just search for a companyid param in the _Path Variables section.

Postman Path Variables Postman Path Variables

📝  Check our OpenAPI file​

This is probably the most complicated method because it requires you to know how to read an OpenAPI file (or at least a YAML file) or to use an OpenAPI editor; at the same time, this is our source of truth: all the previous method derive from our OpenAPI specification, so this is where the company*id param is defined.

Checking our OpenAPI Specification, you can find out if our method requires a company_id parameter by checking the openapi.yaml file: below you can notice that the URL contains the {company_id} placeholder and that the company_id param is listed in the parameters section.

openapi.yaml
/c/\{company_id\}/issued_documents:
  parameters:
    - $ref: "#/components/parameters/company_id"
  get:
    summary: List Issued Documents
    tags:
      - Issued Documents
    responses:
      "200":
        $ref: "#/components/responses/ListIssuedDocumentsResponse"