API access is included with some subscriptions. Not sure if it's part of yours? Connect with our Support team for help!
đŻ Introduction to the API
Our API enables you to communicate with the backend of our platform. With the help of a developer or engineer, you can create a variety of custom features to suit your teams specific needs. Automate campaign workflows, impress clients with a custom login page, and more!
The in-app API playground is available to Admin and Staff users on our more robust plans. It contains important API information and a code builder.
We recommend inviting the engineer or developer working with you to your AgencyAnalytics account as a staff user, so they can easily access API resources.
Where to find API information
If you're already signed into AgencyAnalytics, click here to open the API Overview in-app. Alternatively, click the cog on the left-hand menu to open Settings, then scroll and click the page you wish to view. The table below explains the purpose of each section.
Overview | Covers the terminology we use as well as some basic information about how the API works. |
API Key | Your API key (also know as your API auth) is required to make any calls to the AgencyAnalytics API. For security purposes, it's only available to the account Admin. |
Request | Shares example code blocks of the Read / Delete and Create / Update Operation - POST JSON. |
Response | Covers Statuses, Codes, as well as Success and Error code examples. |
API Playground | Allows you to quickly and easily generate or test code blocks. The API playground is not a sandbox environment and will make calls against your real data. |
API Code Builder
To get started, select the provider from the dropdown on the left. Next, click the drop down menus to select the appropriate asset, operation, etc. for what you're trying to achieve.
The code block provided by the Playground should be edited to include your clients specifics. For example, if the API is being used to quickly create campaigns you would need to enter the Company name, and URL into the code for the test to run successfully.
When ready, click 'Execute' at the top to test the code or click Copy to copy the code. We can see in this example below that the query executed was incomplete by reviewing the returned error on the right:
After successfully updating the query, executing will return a positive status instead, as shown on the right of the screenshot below.
Now that the code is returning a positive status, your engineer or developer can copy the code block to use in your own instance.
Important: The playground manipulates live data, so donât delete information that you donât want to delete, and remember to delete your test data (if you want to.)
Available Assets and Operations
You can perform queries related to the API Assets & Operations listed in the table below.
âAssets | Operations |
backlink | create, read, update, delete |
âcampaign | create, read, update, delete |
user | create, read, update, delete |
âcompetitor | create only |
login-grant | create only |
âtag | create only |
âcampaign-rankings | read only |
dashboard-campaign | read only |
keyword | read only |
keyword-rankings | read only |
global-report-template | read only |
â API FAQ
Do API access tokens expire?
The API access tokens generated by the "copy cURL" button expire every 30 days. The API key does not expire however.
I am unable to convert my API Key into BASE64_ENCODE({{API_KEY}})
You will need to do this as BASE64_ENCODE(:API_KEY) - you'll need to include the colon in front of the API key. Essentially, basic authorization is username:password encoded in base64 and the password is the API key, with no username.
How can I create queries through Postman?
Find your API-key, add a colon (:) to the start and convert to base64. If you have access to a bash/zsh shell this can be done with the command below - please be careful using online converters; donât paste your api key anywhere you wouldnât paste your bank password:
printf :API_KEY | base64
Open postman, create a new request, change to âPOSTâ type and enter https://apirequest.app/query as the url
In headers, add a key Authorization with value Basic B64_ENCODED_API_KEY
Note: Donât touch the âAuthorizationâ tab; leave it as âNo Authâ
Add in the body and press send (you can use the API playground to generate the bodies.) As an example, below is the request body for getting a list of the first 50 users associated with your account:
Please note: The API playground has a button to copy the JSON query - this is the same as copying the body. It also has an option to copy the cURL command - this cURL command comes with an authorization header that uses your login session, not the API key. This means that if you use that authorization header it will expire and stop working after a while.
If you are having issues we recommend reaching out to a developer for assistance.
Where can I read more about generating federated logins?
This API process and set up is covered in this separate 'âCreate your own custom login page' article.
Where can I locate the Campaign ID & Keyword ID to create JSON Queries?
If you want to get a full list of all your campaigns and their IDs, the quickest and easiest way to do this is to use the campaign asset in the query builder, as per the example screenshot below.
Similarly, you can can also retrieve the keyword_id using the keyword asset in the query builder; this will generate a list of all your keywords and their respective IDs, as per the example in the screenshot below. You will also need to ensure that you add a campaign_id filter, since you can only query a list of keywords and their IDs for one campaign at a time.
Can I use the API to pull data from AgencyAnalytics?
You can pull some data from AgencyAnalytics; this is limited to the endpoints currently available. For example you can pull keyword rankings through the keyword-rankings asset.
Also, while we donât have any specific numbers to share, some endpoints may be rate limited, where the endpoints may not allow more than a certain number of calls per second.
Important: The AgencyAnalytics API is not designed to push the AgencyAnalytics platform to another location or to pull in data from a 3rd party platform.
Instead, the AgencyAnalytics API can be used for operations such as creating/editing/deleting/updating campaigns and users, viewing keyword data, viewing backlink manager data & for SSO (Single Sign-On.) As an example, if a new user signs up on your site, you can create the user account, and make a new campaign for the user via our API.
đŹ Need additional help?
If you have any questions, concerns, or feedback contact our friendly support team for assistance! We're available 24/5 to help đ