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.

🔬  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. You can list all the companies accessible by the 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!

If you're implementing a simple application for a single company, then you can use our API Reference or our Postman Collection to retrieve the Company ID, and then insert it as a constant in your code; this way, you'll avoid writing code to retrieve a value that will never change. Otherwise, if you need to manage multiple company IDs that are unknown at developing time, then you can check the SDK examples below to retrieve the Company ID from 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 a few examples using our SDKs:

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();
config.BasePath = "https://api-v2.fattureincloud.it";
// 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);
}

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! 😉 

🙋‍♂️  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 companyid 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"