1) Introduction to Global API (BETA)
The “Global API” allows the creation of locations, customers, users etc for “any” client within an account with one set of API credentials. (As compared to requiring unique API credentials for each client)
2) Retrieving your Global API Credentials
The “Global API” credentials show for the “Account Owner only” in the Agency Dashboard under Account Owner details.
3) Retrieving Client Unique API Credentials (ideal for sharing)
Clicking into a Client and accessing “Account Owner” will show API credentials unique to that client. This allows resellers to share API credentials with their clients assuring that an API call made will only affect customers and locations within that client.
Important: Please do not confuse the unique client identifier number with the ClientID that is part of your API credentials. We therefore opted to call the API Parameter that specifies a client “agent”.
4) Using the “agent” Parameter
When using the Global API credentials all existing API calls continue to work as they do right now – with the optional Parameter of “agent” that can be added to specify the client.
For example, if you would like to add a new customer to Client Mario’s Pizza you would use https://app.gatherup.com/api/doc/customer/create as usual and add an extra Parameter into your request called “agent”: XXXXXX
Example Post Request
“agent”: 25271 // Add this Parameter to specify the client
5) Retrieving a list of existing Clients and their API agent number (ID)
You can get all your existing agent numbers (ID’s) (clients) using: https://app.gatherup.com/api/doc/agency/clients
Framing r’ Us = agent: 124661
Mario’s Pizza = agent: 25271
Atlantic Trailers = agent: 341490
Remember: What is called “Client” in the Agency Dashboard is called “agent” in the API. The “ClientID” is part of your API credentials. The agent number (ID) is what specifies the agency dashboard client in the API.
6) Retrieving the API AgentID for a single Location
To find the “agent” number for an existing (single) business location use: https://app.gatherup.com/api/doc/agency/find-clientid
7) Creating a new Client
We also offer an API call allowing the creation of a new Client. We kept it very simple for now to assure reliable results.
Future additions will allow the renaming and deletion of a client. But for now those actions (if needed) would need to be performed in the dashboard.
New to Agency Dashboard – but you have an existing API integration?
No problem – all you need to do is update your credentials and specify the client in your existing API call.
A) Update to the new Agency Dashboard (UserGuide link: https://userguide.gatherup.com/knowledge-base/how-to-build-your-agency-dashboard/
B) Create your Clients
C) Get your API credentials for the “Global API” as outlined in #2 above.
D) Update your existing API calls with the Global API credentials.
E) Add the “agent” parameter (which specifies the client) to the existing API calls. See # 4 above for using the agent parameter.