FishServe - FishServe API Technical Info

FishServe API Technical Info

Below is the technical information required for setting up the following APIs;

Authentication: See our Getting Started page for technical information
Public Client Info
Users for a Client
User Information
Vessel Information
ACE Transfer
ACE Transfer History
ACE Transfer History Lines
LFRR Submission

Available Test URL

https://register.uat.kupe.fishserve.co.nz/

Production URL

https://fishserve.co.nz/

FishServe API Documentation

Public Client Info

Returns public information about a FishServe client.

Authentication required: None

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client

Request Url

GET https://api.uat.kupe.fishserve.co.nz/client/{clientNumber}/public-client-info

Example:

GET https://api.uat.kupe.fishserve.co.nz/client/12345678/public-client-info

Request Header

Content-Type: application/json

Response

Response Parameters

Parameter	Data type	Description
Client Number	String	The client number
Legal Name	String	The legal name of the client
Trading Name	String	The trading name of the client
Client Status	String	The status of the client. Possible statuses: "Approved", "Cancelled"
Permit Status	String	The status of the client's permit. Possible statuses: "Current", "Suspended", "No Current Permit", "Future Issued"
Permit Start Date	Date	The date the client is authorised to take fish from
Permit Expiry Date	Date	The date the authorisation finishes
Permit Suspension Start Date	Date	The date the permit was suspended

Response Body

{
  "clientNumber": "{ClientNumber}",
  "legalName": "{LegalName}",
  "tradingName": "{TradingName}",
  "clientStatus": "{ClientStatus}",
  "permitStatus": "{PermitStatus}",
  "permitStartDate": "{PermitStartDate}",
  "permitExpiryDate": "{PermitExpiryDate}",
  "permitSuspensionStartDate": "{PermitSuspensionStartDate}"
}

Example:

{
  "clientNumber": "12345678",
  "legalName": "My Company limited",
  "tradingName": "My Company",
  "clientStatus": "Approved",
  "permitStatus": "Suspended",
  "permitStartDate": "2016-01-01T00:00:00",
  "permitExpiryDate": "2020-12-31T23:59:59",
  "permitSuspensionStartDate": "2016-05-01T00:00:00"
}

Users for a Client

Returns a list of users for a client for a particular area such as ACE or ERS.

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client
Area	Mandatory	String	The area for which the user is approved. Options are; ACE, Client, ERS, Finance, LFR Licence, Permit, Quota, Returns, Vessels.

Request Url

GET https://client.uat.kupe.fishserve.co.nz/api/clients/{clientNumber}/usersForBusinessArea/{area}

Example:

GET https://client.uat.kupe.fishserve.co.nz/api/clients/1234567/usersForBusinessArea/ers

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
User Id	String	The unique ID number of the user.
First Name	String	The first name of the user.
Prefered Name	String	The prefered name of the user.
Surname	String	The surname of the user.
Email Address	String	The email address of the user.
Authorisation Role	String	The role the user is approved to perform for the client. For example; Manager, Viewer, or Reporter.

Response Body

    {
        "UserId": "{UserId}",
        "FirstName": "{FirstName}",
        "PreferedName": "{PreferedName}",
        "Surname": "{Surname}",
        "EmailAddress": "{EmailAddress}",
        "AuthorisationRole": "{AuthorisationRole}"
    }

Example:

[
    {
        "UserId": 23,
        "FirstName": "Peter",
        "PreferedName": null,
        "Surname": "One",
        "EmailAddress": "peter.one@fishserve.co.nz",
        "AuthorisationRole": "Manager"
    },
    {
        "UserId": 25,
        "FirstName": "Douglas",
        "PreferedName": "Doug",
        "Surname": "Two",
        "EmailAddress": "doug.two@fishserve.co.nz",
        "AuthorisationRole": "Reporter"
    },
    {
        "UserId": 5383,
        "FirstName": "Mary",
        "PreferedName": null,
        "Surname": "Three",
        "EmailAddress": "mary.three@fishserve.co.nz",
        "AuthorisationRole": "Viewer"
    }
]

User Information

Returns a list of clients that a user has authorisations to.

Authentication required: Bearer token

Request

Request Url

GET https://api.uat.kupe.fishserve.co.nz/user

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
Title	String	The title of the user.
First Name	String	The first name of the user.
Surname	String	The surname of the user.
Preferred Name	String	The prefered name of the user.
Middle Name	String	The middle name of the user.
Email Address	String	The email address of the user.
Client Number	String	The client number.
Legal Name	String	The legal name of the client.
Trading Name	String	The trading name of the client.
Authorisations	String	List all the authorisations the user has for the client e.g. ACE Manager, ERS Reporter.

Response Body

{
        "user_info": {
        "title": "{Title}",
        "firstName": "{FirstName}",
        "surname": "{Surname}",
        "preferedName": "{PreferedName}",
        "middleName": "{MiddleName}",
        "emailAddress": [ 
                "{EmailAddress}"
         ]
      },
      "clients": [
        {
        "clientNumber": "{ClientNumber}",
        "legalName": "{LegalName}",
        "tradingName": "{TradingName}",
        "authorisations": [
                "{ClientAuthorisations}"
        }
      ]
}

Example:

{  
        "user_info": {
        "title": "Mr",
        "firstName": "Max",
        "surname": "Fisher",
        "preferedName": null,
        "middleName": null,
        "emailAddress": [ 
           "max.fisher@quotamanagers.co.nz",
        ]
     },
     "clients": [
        {
            "clientNumber": "7700001"
            "legalName": "Acme Fishing Company",
            "tradingName": null,         
            "authorisations": [
               "ACE Manager",
               "Catch Effort Manager",
               "Client Manager",
               "Finance Manager",
               "LFR Manager",
               "Permit Manager",
               "Quota Manager",
               "Returns Manager",
               "Vessel Manager"
               ]
        },
        {
            "clientNumber": "6600001",
            "legalName": "A Fishing Company",
            "tradingName": null
            "authorisations": [
               "ACE Manager",
               "Catch Effort Manager",
               "Client Manager",
               "ERS Viewer",
               "Finance Manager",
               "LFR Manager",
               "Permit Manager",
               "Quota Manager",
               "Returns Manager",
               "Vessel Manager"
               ]
         }
     ]
}

Vessel Information

Returns information about a vessel.

Authentication required: None

Request

Request Url Parameters

Parameter	Required	Data type	Description
Vessel Number	Mandatory	String	The registered vessel number

Request Url

GET https://licence.uat.kupe.fishserve.co.nz/api/vessels/get/{vesselNumber}

Example:

GET https://licence.uat.kupe.fishserve.co.nz/api/vessels/get/12345

Request Header

Content-Type: application/json

Response

Response Parameters

Parameter	Data type	Description
Vessel Name	String	The name of the vessel
Call sign	String	The call sign of the vessel
Valid From Date Time	String	The start date from when the vessel has been continuously registered to the Operator Client. Date 24hr + UTC offset
Valid To Date Time	String	The latest end date for the continuous vessel registration period for the Operator Client. This may be a future date. Date 24hr + UTC offset
Status	String	The status of the vessel registration. Possible statuses: "Current", "Expired", "Cancelled", "Issued".
Operator Client Number	String	The client number for the registered operator of the vessel

Response Body

{
    "VesselName": "{VesselName}",
    "CallSign": "{CallSign}",
    "ValidFromDateTime": "{ValidFromDateTime}",,
    "ValidToDateTime": "{ValidToDateTime}",
    "Status": "{Status}",
    "OperatorClientNumber": "{OperatorClientNumber}",
}

Example:

{
    "VesselName": "Princess",
    "CallSign": "ZMA1234",
    "ValidFromDateTime": "2004-10-01T00:00:00+12:00",
    "ValidToDateTime": "2018-03-31T23:59:59+13:00",
    "Status": "Current",
    "OperatorClientNumber": "7654321"
}

ACE Transfer

Performs an ACE transfer

Note: Transferor must be set up for invoice payments

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	Transferor for the ACE transfer

Request Url

GET https://api.uat.kupe.fishserve.co.nz/client/{clientNumber}/ace/transfer

Example:

GET https://api.uat.kupe.fishserve.co.nz/client/12345678/ace/transfer

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters

Parameter	Required	Data type	Description
Transferor Client Number	Mandatory	String	Transferor for the ACE transfer
Transferor Legal Name	Mandatory	String	Legal name of the transferor
Transferee Client Number	Mandatory	String	Transferee for the ACE transfer
Transferee Legal Name	Mandatory	String	Legal name of the transferee
Fishing Year	Mandatory	Date	Fishing year of the ACE transfer. Must be an open, or future fishing year
Stock Code	Mandatory	String	Stock code of ACE to transfer
Ace Type	Mandatory	String	Type of ACE to transfer. Valid options: "Regular ACE", "TAC ACE"
Quantity	Mandatory	Number	Amount of ACE to transfer
Price	Mandatory	Decimal	The total price for the stock being transferred
Sub Stocks	Optional	Array of sub stocks	This section allows for sub stock transfer details to be recorded for the statutory ACE transfer provided in this same call.
			This information can be entered manually by a user into Kupe or detail included in this request if they are transferring a stock which has sub stocks associated with it e.g. HOK1 has HOK1East and HOK1West as associated sub stocks
			Can only be provided if the Stock Code has sub stocks.
Reject if Sub Stocks Fail	Optional	Boolean	Defines if statutory ACE transfer should happen only if Sub Stocks will also be accepted.
Reject if Sub Stocks Fail	Optional	Boolean	Applies only if there is a Stock Code that has sub stocks.
Use Industry Stock Split Ratio	Optional	Boolean	Defines if a stock’s Quantity should be distributed among its sub stocks based on industry split ratios.
			Applies only
			- to Stock Codes that have sub stocks
			- if Sub Stocks array is not provided

Request Body Parameters

Parameter	Required	Data type	Description
Sub Stock Code	Mandatory	String	Sub Stock code
Quantity	Mandatory	Number	Sub Stock split amount.
Quantity	Mandatory	Number	Total of all sub stock quantities in this array must match its parent stock’s Quantity.

Request Body

{
            "transferor": {
                "clientNumber": "{TransferorClientNumber}",
                "legalName": " {TransferorLegalName}"
            },
            "transferee": {
                "clientNumber": "{TransfereeClientNumber}",
                "legalName": " {TransfereeLegalName}"
            },
            "fishingYear": "{Fishing Year}",
            "lines": [
                {
                    "stockCode": "{Stock Code}",
                    "aceType": "{Ace Type}",
                    "quantity": {Quanitity},
                    "price": {Price},
                    "substocks": [
                        {
                            "substockCode": "{Sub Stock 1 Code}",
                            "quantity": {Sub Stock 1 Quantity}
                        },
                        {
                            "substockCode": "{Sub Stock n Code}",
                            "quantity": {Sub Stock n Quantity}
                        }
                    ]
                }
            ],
            "rejectIfSubstocksFail": {Reject if Sub Stocks Fail},
            "useIndustryStockSplitRatio": {Use Industry Stock Split Ratio}
        }

Example:

{
            "transferor": {
                "clientNumber": "987654321",
                "legalName": "My Fishing Group Limited"
            },
            "transferee": {
                "clientNumber": "96428754",
                "legalName": "Some Seafoods Limited"
            },
            "fishingYear": "2021-10-01T00:00:00",
            "lines": [
                {
                    "stockCode": "HOK1",
                    "aceType": "Regular ACE",
                    "quantity": 1500,
                    "price": 75.0,
                    "substocks": [
                        {
                            "substockCode": "HOK1EAST",
                            "quantity": 300
                        },
                        {
                            "substockCode": "HOK1WEST",
                            "quantity": 1200
                        }
                    ]
                }
            ],
            "rejectIfSubstocksFail": false,
            "useIndustryStockSplitRatio": true
        }

Response

Response Parameters

Parameter	Data type	Description
Document Number	String	The document number of the ACE transfer
Status	String	The status of the ACE transfer. Possible options: "placed", "pending placed"

Response Body

{
  "documentNumber": "{DocumentNumber}",
  "status": "{Status}"
}

Example:

{
            "documentNumber": "ATR1000624",
            "status": "placed"
          }

ACE Transfer History

Returns a list of ACE Transactions for a client. These transactions include purchases and sales or deductions of ACE (ACE Transfers) and all Allocations (Annual, Underfishing, Preseason and TAC)

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client involved in the ACE Transaction
From Date	Optional	Date	Filters transactions registered before this date
To Date	Optional	Date	Filters transactions registered after this date

Request Url

GET https://api.uat.kupe.fishserve.co.nz/client/{clientNumber}/ace/transferhistory/?FromDate={FromDate}&ToDate={ToDate}

Example:

GET https://api.uat.kupe.fishserve.co.nz/client/12345678/ace/transferhistory

GET https://api.uat.kupe.fishserve.co.nz/client/12345678/ace/transferhistory/?FromDate=2015-10-01

GET https://api.uat.kupe.fishserve.co.nz/client/12345678/ace/transferhistory/?FromDate=2015-10-01&ToDate=2016-10-01

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
Transferor Client Number	String	Transferor of the ACE transfer
Transferor Legal Name	String	Legal name of the transferor
Transferor Trading Name	String	Trading name of the transferor
Transferee Client Number	String	Transferee of the ACE transfer
Transferee Legal Name	String	Legal name of the transferee
Transferee Trading Name	String	Trading name of the transferee
Status	String	The status of the transfer
Fishing Year	Date	Fishing year the ACE transfer is for
Registered Date	Date	Date the ACE transfer was registered
Document Number	String	Document number of the ACE transfer
Transfer Type	String	Type of ACE transfer

Response Body

[
  {
    "transferor": {
      "clientNumber": "{TransferorClientNumber}",
      "legalName": "{TransferorLegalName}",
      "tradingName": "{TransferorTradingName}"
    },
    "transferee": {
      "clientNumber": "{TransfereeClientNumber}",
      "legalName": "{TransfereeLegalName}",
      "tradingName": "{TransfereeTradingName}"
    },
    "status": "{Status}",
    "fishingYear": "{FishingYear}",
    "registeredDate": "{RegisteredDate}",
    "documentNumber": "{DocumentNumber}",
    "transferType": "{TransferType}"
  }
]

Example:

[
  {
    "transferor": {
      "clientNumber": "7654321",
      "legalName": "Client 2 Legal Name",
      "tradingName": "Client 2 Trading Name"
    },
    "transferee": {
      "clientNumber": "1234567",
      "legalName": "Client 1 Legal Name",
      "tradingName": "Client 1 Trading Name"
    },
    "status": "Registered",
    "fishingYear": "2015-10-01T00:00:00",
    "registeredDate": "2016-04-15T00:00:00",
    "documentNumber": "ATR1000624",
    "transferType": "Regular Transfer FA96-s133"
  }
]

ACE Transfer History Lines

Returns all of the stocks included in the transaction

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client involved in the ACE Transaction
Document Number	Mandatory	String	The ACE Transaction document number

Request Url

GET https://api.uat.kupe.fishserve.co.nz/client/{clientNumber}/ace/transfer/{documentNumber}

Example:

GET https://api.uat.kupe.fishserve.co.nz/client/12345678/ace/transfer/ABC123456

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
Transferor Client Number	String	Transferor of the ACE transfer
Transferor Legal Name	String	Legal name of the transferor
Transferor Trading Name	String	Trading name of the transferor
Transferee Client Number	String	Transferee of the ACE transfer
Transferee Legal Name	String	Legal name of the transferee
Transferee Trading Name	String	Trading name of the transferee
Status	String	The status of the transfer
Fishing Year	Date	Fishing year the ACE transfer is for
Registered Date	Date	Date the ACE transfer was registered
Document Number	String	Document number of the ACE transfer
Transfer Type	String	Type of ACE transfer
Stock Code	String	Stock code of ACE transfered
Ace Type	String	Type of ACE transfered. Possible options: "Regular ACE", "TAC ACE"
Quantity	Number	Amount of ACE transfered
Total Price	Decimal	The total price of the transferred stock

Response Body

{
  "lines": [
    {
      "stockCode": "{StockCode}",
      "aceType": "{AceType}",
      "quantity": "{Quantity}",
      "totalPrice": "{TotalPrice}"
    }
  ],
  "transferor": {
    "clientNumber": "{TransferorClientNumber}",
    "legalName": "{TransferorLegalName}",
    "tradingName": "{TransferorTradingName}"
  },
  "transferee": {
    "clientNumber": "{TransfereeClientNumber}",
    "legalName": "{TransfereeLegalName}",
    "tradingName": "{TransfereeTradingName}"
  },
  "status": "{Status}",
  "fishingYear": "{FishingYear}",
  "registeredDate": "{RegisteredDate}",
  "documentNumber": "{DocumentNumber}",
  "transferType": "{TransferType}"
}

Example:

{
  "lines": [
    {
      "stockCode": "HOK1",
      "aceType": "Regular ACE",
      "quantity": 100,
      "totalPrice": 100.0
    }
  ],
  "transferor": {
    "clientNumber": "7654321",
    "legalName": "Client 2 Legal Name",
    "tradingName": "Client 2 Trading Name"
  },
  "transferee": {
    "clientNumber": "1234567",
    "legalName": "Client 1 Legal Name",
    "tradingName": "Client 1 Trading Name"
  },
  "status": "Registered",
  "fishingYear": "2015-10-01T00:00:00",
  "registeredDate": "2016-04-15T00:00:00",
  "documentNumber": "ATR1000624",
  "transferType": "Regular Transfer FA96-s133"
}

LFRR Submission

Submits an LFRR

Note: Submitter must have LFRR submission rights

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	LFR Client Number
Report period	Mandatory	String	Report month

PUT https://transaction.uat.kupe.fishserve.co.nz/api/returns/{Client Number}/lfrr/{Report Period}/update-and-submit

Example:

https://transaction.uat.kupe.fishserve.co.nz/api/returns/12345678/lfrr/2022-01/update-and-submit

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters

Parameter	Required	Data type	Description
ClientNumber	Mandatory	String	The client number
ReportPeriod	Mandatory	Date	First day or report period
IsNilReturn	Mandatory	Boolean	Whether this is a nil return
AmendmentReason	Conditional	String	Must be provided for Update.
			Must be null for Create.
			Will be ignored if provided for create
Landings	Conditional	Array of Landings from clients	List of clients and their respective landings.
Landings	Conditional	Array of Landings from clients	Must be provided if IsNilReturn is false, and vice versa

Landings Parameters

Parameter	Required	Data type	Description
ClientNumber	Mandatory	String	Fisher client number who landed their fish to you
LandingLines	Mandatory	Array of landed species and respective amounts	List of all species and respective quantities from this fisher

LandingLines Parameters

Parameter	Required	Data type	Description
Species	Mandatory	String	Landed species
Quantity	Mandatory	Number	Quantity of landed species

Request Body

{
            "ClientNumber": "{Client Number}",
            "ReportPeriod": "{Reporting Period}",
            "AmendmentReason": "{Amendment reason}",
            "IsNilReturn": {is nil return?},
        
            "Landings": [
                {
                    "ClientNumber": "{Fisher 01 Client Number}",
                    "LandingLines": [
                        {
                                "Quantity": {Quantity},
                                "Species": "{Species}"
                        },
                        {
                                "Quantity": {Quantity},
                                "Species": "{Species}"
                        }
                    ]
                },
                {
                    "ClientNumber": "{Fisher 02 Client Number}",
                    "LandingLines": [
                        {
                                "Quantity": {Quantity},
                                "Species": "{Species}"
                        }
                    ]
                }
            ]
        }

Example:

{
            "ClientNumber": "7654321",
            "ReportPeriod": "2022-07-01T00:00:00",
            "AmendmentReason": "an example amendment reason",
            "IsNilReturn": false,
            "Landings": [
                {
                    "ClientNumber": "1234567",
                    "LandingLines": [
                        {
                                "Quantity": 11,
                                "Species": "BAR"
                        },
                        {
                                "Quantity": 222,
                                "Species": "DAN"
                        }
                    ]
                },
                {
                    "ClientNumber": "112233445",
                    "LandingLines": [
                        {
                                "Quantity": 3333,
                                "Species": "SNA"
                        }
                    ]
                }
            ]
        }

Response

Response Status

Status	Description
200 OK	Status when LFRR has been accepted successfully.
400 Bad Request	Status when there are missing headers or missing parameters.
401 Unauthorised	Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters

Parameter	Data Type	Validation and Additional Notes
ActivityGuid	String	The unique reference number for the accepted LFRR populated on success.
HasChanged	Boolean	This will be false if the submitted LFRR was accepted however the content of the submission has not changed since the previous version
Errors	Array	List of errors, if any. See Errors Parameters below.

Errors Parameters

Parameter	Data Type	Validation and Additional Notes
Property Name	String	The name of the property that has an error.
Attempted Value	String	The attempted value used.
Error Code	String	The type of error.
Error Message	String	The description of the error.

Example 1:

The following example of the response body is returned when there are no errors, and the request is accepted (Status Code – 200).

{
        "ActivityGuid": "B058AB43-B482-43BA-B377-3B06D57AC48E",
        "HasChanged": true,
        "ValidationResult": {
    "IsValid": true,
                    "Errors": []
        }
    }

Example 2:

The following example of the response body is returned when there are errors and the request is rejected (Status Code – 400).

 {
        "ActivityGuid": null,
        "HasChanged": null,
        "ValidationResult": {
            "IsValid": false,
            "Errors": [
                {
                    "ErrorMessage": "The LFRR you have requested does not exist.",
                    "ErrorCode": "LfrrDoesNotExist",
                    "PropertyName": null,
                    "AttemptedValue": null
                }
            ]
        }
    }