The Barracuda PhishLine REST API provides remote administration and configuration of Barracuda PhishLine . This article gives a brief description of REST API and the API methods you can use to access your Barracuda PhishLine .
Representational State Transfer (REST) is a stateless architecture that runs over HTTP. REST API is a simple web service API you can use to interact with Barracuda PhishLine. For more information on REST API, visit http://en.wikipedia.org/wiki/Representational_state_transfer .
Barracuda PhishLine API
|API Endpoint||Functions||Permission Required|
|Authentication||None. Uses API key, username, and password.|
|Campaign||Email Campaign – Can Edit All|
|CampaignResult||Email Campaign – Can Edit All|
One of the following:
For an example of writing Barracuda PhishLine API in PHP, refer to Example - API in PHP .
Getting API Access
PhishLine user accounts are used to access the API. In addition, you will need to acquire an API key. API keys can be generated by administrators from the PhishLine interface, under "System > API Keys". Note that API keys expire after 1 year.
Base API URL
The base API URL is:
https://api.phishline.com/<phishline_example>/rest. Substitute your instance name for
Endpoints add to the URL. For example, the '/authenticate' endpoint will be
https://api.phishline.com/<phishline_example>/rest/authenticate. Again, substitute your instance name for
Using the API key
The API key, username, and password are used to make a call to the authentication endpoint per the /authenticate endpoint section.
Using the Access Token
After retrieving an access token from /authenticate, include it with all subsequent requests.
The token can be passed in the query string OR as an
Authorization: Bearer header.
Query string example:
If this header was sent, and the token was valid:
Authorization: Bearer 283efd73abd654cf92fd8g7a23742
Then this would be a valid GET request:
If you receive an authorization error (HTTP code 401), retrieve a new access token from the /authenticate endpoint.
Access tokens are guaranteed to expire after 24 hours, and may expire much more quickly based on the last time it was used. Access tokens that have not been used for a period of time may expire before 24 hours.
The envelope for your request will have the following attributes.
- jobid - If a job cannot be completed in a timely manner, you may receive a jobid instead. This is provided for future enhancement.
- status: This will be the same as the HTTP status returned.
- statusMessage: This is the short human readable name of the result of the request. In case of error, please reference this error in this API documentation.
- statusDetails: If the status requires more in-depth details, they will be enumerated here as an array of objects. This will often include the number of total results.
- entity: The name of the returned object(s) (if any). For example, "campaign". In case of error, the type may be "unknown".
- notifications: You will receive notifications including, but not necessarily limited to:
- The number of API calls allowed.
- The number of API calls completed.
- The expiration date for your API key.
- totalRowCount: The total number of rows the request returned or could return. The maximum number of rows a request can return is 5,000.
- pageRowCount: The number of rows returned in this request.
- remainingRowCount: The remaining number of rows available to request.
- MaxIdReturned: The maximum record id returned in the current request.
- data: If data is returned, it is returned as an array of objects, even if there is only one item returned. Even if there are 0 returned results, the data array will be present on requests that are expected to return data.
A note about data types
All data returned in the "data" section of the envelope will be string data. You will need to convert data to other variable types as required. The endpoint documentation will show you the variable types you can expect to be able to convert the data to.
When sending requests, note the following:
- Unless otherwise noted, when posting data, only
Content-Type: application/jsonis accepted.
- Any endpoint that is not available via public API will return a 405 NOT ALLOWED error.
- All endpoints except /authentication will require an access_key. Access keys are generated from the /authentication endpoint.
- Be aware that a user account being used for API access must have the appropriate access levels assigned in the User Manager. For example, if a user cannot browse to "Results -> Outbound Analysis", they will also not be able to use the /campaignresults/ endpoint.