Web Services Integrations (API)
An Integration is the "key" you hand to an external system (a website, your own mobile app, a middleware, or an integration with another piece of software) so it can talk to your company through the AdmCloud API. Each integration has its own identifier (appid), sent together with the user's credentials on every call, so you can identify and control who is calling the API and with what level of access.
What is it and what is it for?
AdmCloud exposes a REST API that lets an external system read and create your company's information (customers, items, invoices, accounts, subsidiaries and many other objects) without using the web screens. To call that API, every request must include a valid appid: the identifier of an Integration created here. This way, every system or project connecting to your company is identified, can be disabled independently once it's no longer used, and can be limited to the real calling user's own permissions instead of getting full access.
Creating an Integration does not replace the username and password used to authenticate the call: the appid travels alongside the user's credentials (using the Basic Authentication standard), not instead of them.
How to use it
- Open Web Services Integrations and click New Integration.
- Type a descriptive Name that identifies the system or project that will use this integration (for example, the name of your website or the integration with another system).
- Decide whether the integration should Execute as Admin (see below) and add any Notes that will help you remember what it's used for.
- Save the integration. AdmCloud assigns it an Integration ID (a unique identifier) that can't be changed afterward.
- Open the detail of the newly created integration to copy its ID and see the already-built example URLs you can use to call the API for each module (Customers, Vendors, Items, Accounts, Invoices, Purchase Orders, Deposits, Journal Entries, and more).
- In your external system, configure the API calls using those example URLs as a base, authenticating with Basic Authentication and passing the integration's appid and your database name (company) as parameters.
- Check the full technical documentation (Swagger), the explanatory video, the sample C# code and the API Explorer from the info banner at the top of the list, to learn about every available object and its parameters.
Key fields
| Field | What it's used for |
|---|---|
| Name | Identifies the integration in the list. It must be unique: you can't reuse the name of an existing integration. |
| Disabled | Turn this on and any API call using this integration's appid stops working immediately, with no need to delete it. Useful to temporarily suspend a suspicious connection or one you no longer use. |
| Execute as Admin | When on (the default), calls using this integration run with full access, without checking the authenticated user's permissions. Turn it off and the call respects the real user's permissions and security group, exactly as if they had logged into the web screens. |
| Notes | Free text to document, for example, who requested the integration or which system it's used for. Only visible to internal users. |
| Integration ID | The unique identifier (appid) AdmCloud generates when you save. Used as a parameter on every API call to identify this integration. |
| Database Name | Your company's identifier (company), which you must also send on every API call together with the appid. |
Validations when saving
- The Name is required and must be unique; if an integration with the same name already exists, AdmCloud rejects the save.
- The Integration ID (appid) is assigned automatically by AdmCloud when created and can't be edited.
- An integration with active recorded calls doesn't stop you from saving it; however, trying to delete an integration that already has history or other linked records will be blocked, so that traceability isn't lost.
- Calling the API with an appid that doesn't exist, or that belongs to an integration marked Disabled, gets the call rejected.
Availability
- Requires the Customization permission in your user group to view, create, edit or delete Integrations.
- On the Enterprise plan, API availability doesn't depend on turning other modules on or off — it's included in the edition.
Tips and common errors
Create one integration per system, not a single one for everything. If you connect several external systems (for example, your website and, separately, an integration with another piece of software), create a separate Integration for each. That way you can disable or track each connection independently without affecting the others.
Use "Execute as Admin" carefully. While it's on, any call using that appid gets full access without going through the user's permissions, even if that user would normally have limited access. Turn it off when you want the integration to respect exactly the same permissions the user would have inside the application.
I can't find the New Integration button, or the screen isn't available. Check that your plan includes the API (Basic or higher) and that your user has the Customization permission assigned.