FishServe APIs

Explore the following list of APIs provided by FishServe for use in your own applications. You will find further information on each of the APIs below and technical information for developers is available here.

Available APIs

Get Client Information

This API can be used to retrieve client related information. For example, use this API to;

  • Confirm the client number is for the entity you require
  • Confirm a client's legal name so you can perform an ACE Transfer to them
  • Determine a client's permit status to confirm they are fishing against a current permit and you can receive fish from them. This is valid only at the point in time of the check, previous suspensions or permits are not available through this API.

The API request requires;

  • User token from the authentication API (optional)
  • Client Number

The response provides;

  • Legal Name
  • Trading Name
  • Client Status
  • Permit Status
  • Permit Start Date
  • Permit Expiry Date
  • Permit Suspension Start Date

Back to top

Get User information

This API can be used to retrieve clients for a user and their authorisations.

The API request requires;

  • User token from the authentication API

The response provides;

  • Title
  • First Name
  • Surname
  • Prefered Name
  • Middle Name
  • Email Address
  • Client Number
  • Legal Name (of client)
  • Trading Name
  • Authorisations

Back to top

Get Users for a Client

This API can be used to retrieve users for a client for a particular area. For example, use this API to;

  • View all users for a client for a particular area such as ERS

The API request requires;

  • User token from the authentication API
  • Client Number
  • User area, for example; ERS, ACE, Permits.

The response provides;

  • User ID
  • First Name
  • Prefered Name
  • Surname
  • Email Address
  • Authorisation Role

Back to top

Get Vessel Information

This API can be used to retrieve vessel related information. For example, use this API to;

  • Confirm the vessel number is for a valid vessel
  • Confirm a vesel name, call sign, operator client number and registration period of the vessel.
  • Determine a vessel's status. This is valid only at the point in time of the check.

The API request requires;

  • Vessel Number

The response provides;

  • Vessel Name
  • Call Sign
  • Valid from DateTime
  • Valid to DateTime
  • Vessel Registration Status
  • Operator Client Number

Back to top

Post ACE Transfer

This API can be used to perform an ACE transfer on behalf of the Transferor (Seller). There are specific requirements for the ACE Transfer within this API to be successful. These include;

  • The client details must be an exact match to the details stored on the register. Use the Get Client Information API above to ensure you have the correct legal names for the clients involved in the transfer.
  • The ACE Transfer must include the authorisation token for an ACE Manager of the Transferor
  • The Transferor must be authorised by FishServe to be invoiced for transaction fees
  • Each stock line must be unique. There cannot be duplicate stocks within the one request

The API request requires;

  • User token from the authentication API
  • Transferor Client Number
  • Transferor Legal Name
  • Transferee Client Number
  • Transferee Legal Name
  • Fishing Year
  • Stock Code
  • ACE Type (Regular ACE or TAC ACE)
  • Quantity
  • Price

The last four requirements, Stock Code, ACE Type, Quantity and Price, make up the Lines of a transfer and can be repeated as many times as necessary within the one API request. 

The response provides;

  • Document Number
  • Status of the Transfer

The Status of the Transfer in the response will be;

  • Placed – the ACE transfer has been received, has passed all initial checks and is for a fishing year currently being traded.  It will be actioned on a first come first served basis.  There is the possibility that the transfer may be rejected when being actioned, if one or more lines in the transfer are rejected then the whole document is rejected.  Placed transfers are normally actioned between 1 to 15mins, depending on the time of the year. You could use the Get ACE Transfer History API below to retrieve the final status.
  • Pendingplaced – similar to a Placed response but for a fishing year starting in the future.  May be referred to as a Forward ACE Transfer.  This will be actioned at the start of the requested fishing year on a first come first served basis.  There is the possibility that the transfer may be rejected when being actioned.
  • Rejected – This may occur if there is an error in the request, or the transfer has not been received and there is nothing to be actioned.  Correct the issue and request the ACE Transfer again.

Back to top

Get ACE Transfer History

This API can be used to retrieve a list of ACE Transactions for a client within a specified time frame. These transactions include purchases and sales/deductions of ACE (ACE Transfers) and all Allocations (Annual, Underfishing, Preseason and TAC). For example, use this API at the start of a fishing year to retrieve any ACE Allocations, then call the Get ACE Transfer History Lines API below to get all the stocks allocated to the client for the fishing year.

The API request requires;

  • User token from the authentication API
  • Client Number
  • From Date
  • To Date

The response provides;

  • Transferor Client Number
  • Transferor Legal Name
  • Transferor Trading Name
  • Transferee Client Number
  • Transferee Legal Name
  • Transferee Trading Name
  • Status of the Transfer
  • Fishing Year
  • Registered Date
  • Document Number
  • Transfer Type

You can use the Document Number returned in the response to call the Get ACE Transfer History Lines API below to retrieve the stock lines information for a ACE transfer/allocation. 

Back to top

Get ACE Transfer History Lines

This API can be used to retrieve all of the stocks and the quantities involved in a specific ACE transaction.  This includes ACE Transfers and all ACE Allocations. You can use the Get ACE Transfer History API above, if required, to find the document number.

The API request requires;

  • User token from the authentication API
  • Client Number
  • Document Number

The response provides;

  • Transferor Client Number
  • Transferor Legal Name
  • Transferor Trading Name
  • Transferee Client Number
  • Transferee Legal Name
  • Transferee Trading Name
  • Status of the Transfer
  • Fishing Year
  • Registered Date
  • Document Number
  • Transfer Type
  • Stock Code
  • ACE Type (Regular ACE or TAC ACE)
  • Quantity
  • Total Price

The Status of the Transfer in the response will be;

  • Registered – the ACE Transfer has been completed successfully.  The Transferors account has been decreased and the Transferees increased by the amount of the transfer.
  • Rejected – the ACE Transfer has been rejected and no stocks have been transferred.  This is normally as a result of the Transferor not having enough ACE for the Transfer.  If one or more lines in the transfer are rejected then the whole document is rejected

The Transfer Type in the response will be;

  • Standard Transfer - An ACE transfer between two consenting parties for an active fishing year
  • Forward Transfer - An ACE transfer between two consenting parties for a future fishing year
  • Annual Allocation - An ACE Allocation at the start of a fishing year
  • Pre-season TACC increase Allocation - An ACE allocation due to a TACC increase
  • In-season TAC increase Allocation - An ACE allocation due to a TAC increase
  • Underfishing Entitlement Allocation - An ACE allocation due to underfishing in a previous fishing year

Back to top

Put Licensed Fish Receiver Return

This API can be used to perform an LFRR submission or amendment. There are specific requirements for the LFRR within this API to be successful. These include;

  • The client details must be an exact match to the details stored on the register. Use the Get Client Information API above to ensure you have the correct clients involved in the LFRR.
  • Return number.

The API request requires;

  • User token from the authentication API
  • LFRR Client Number
  • Is Nil Return
  • Reported Period
  • Landing client
  • Landing lines from above client
  • Landed species
  • Landed species Quantity

Landing clients and respective Landing lines can be repeated as many times as necessary within one API request if it is not a Nil return.

The response provides;

  • Activity Guide
    • The unique reference number for the accepted LFRR populated on success.
  • Has Changed
    • A flag to indicate if the submitted LFRR was accepted but the content of the LFRR has not changed since the previous version
  • Validation Result
  • Is Valid
    • The flag to indicate whether the return is accepted
  • Errors
    • List of errors, if return is not accepted

Back to top