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

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
ParameterRequiredData typeDescription
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
ParameterData typeDescription
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"
}

Back to top

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
ParameterRequiredData typeDescription
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
ParameterData typeDescription
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"
    }
]

Back to top

Vessel Information

Returns information about a vessel.

Authentication required: None

Request

Request Url Parameters
ParameterRequiredData typeDescription
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
ParameterData typeDescription
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"
}

Back to top

ACE Transfer

Performs an ACE transfer

Note: Transferor must be set up for invoice payments

Authentication required: Bearer token

Request

Request Url Parameters
ParameterRequiredData typeDescription
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
ParameterRequiredData typeDescription
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
ParameterData typeDescription
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"
}

Back to top

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
ParameterRequiredData typeDescription
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
ParameterData typeDescription
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"
  }
]

Back to top

ACE Transfer History Lines

Returns all of the stocks included in the transaction

Authentication required: Bearer token

Request

Request Url Parameters
ParameterRequiredData typeDescription
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
ParameterData typeDescription
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"
}

Back to top