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
Available Test URL
https://register.uat.kupe.fishserve.co.nz/
Production URL
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 - Request Body
-
{ "transferee": { "clientNumber": "{TransfereeClientNumber}", "legalName": "{TransfereeLegalName}" }, "transferor": { "clientNumber": "{TransferorClientNumber}", "legalName": "{TransferorLegalName}" }, "fishingYear": "{FishingYear}", "lines": [ { "stockCode": "{StockCode}", "aceType": "{AceType}", "quantity": "{Quantity}", "price": "{Price}" } ] }
Example:
{ "transferee": { "clientNumber": "1234567", "legalName": "Client 1 Legal Name" }, "transferor": { "clientNumber": "7654321", "legalName": "Client 2 Legal Name" }, "fishingYear": "2015-10-01T00:00:00", "lines": [ { "stockCode": "HOK1", "aceType": "Regular ACE", "quantity": 100, "price": 100.0 } ] }
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", "pendingplaced"
- 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" }