Skip to content

upload_deployments

Manufacturer subscribers submit every set deployed using their devices and promptly update changes to status, position or conditions. Send sets with all required and conditional fields in the Data Rules.

On this page

Try in sandboxSign-in required · shared test environment

POST/api/upload_deployments/

Send JSON over HTTPS with your assigned api_key in the body. Use the appropriate test or production host.

Inspect result.acknowledged, failed_sets (set_id and reason), and saved_sets. An HTTP 200 alone does not establish that every set was saved or that the submission complies with the Data Rules.

Request body

DeploymentsUpload

Protocol requirements come from OpenAPI 0.4.1. Credentials are required for access. Gear submissions must also satisfy the required and conditional Data Rules, even where the test schema allows omissions.

DeploymentsUpload request fields
Field / typeRequirementDescription
format_version numberRequiredFile Format Version, currently 0.3
api_key string · min length 32, max length 38Required for accessAPI credential. Keep credentials server-side and redact them from logs and support reports.
sets array<Set>RequiredAll gear deployments to be updated. View Set fields

Required gear data

Manufacturer subscribers must supply required data for every set deployed using their devices. Commercial subscriptions do not contribute data. Required fields must be supplied; conditional fields must follow their stated rule, including explicit null values where specified.

  • Use lowercase, 36-character UUID v4 identifiers.
  • Use UTC timestamps in YYYY-MM-DDThh:mm:ssZ format.
  • Field names and accepted values are case-sensitive. Submit coordinates at full available precision, at least five decimal places, without rounding.
  • Submit updates promptly when a set’s status, position or conditions change.
The test API allows some omissions and values that the policy does not. API acceptance does not establish compliance (Policy §5.6). Follow Appendix A even where validation is more permissive.

Set

Submission requirements · Data Policy Appendix A.2

Set submission fields and policy requirements
Field / typeRequirementDescription
vessel_id UUID v4RequiredAssign once to the vessel and use the same ID for every submission from it.
set_id UUID v4RequiredUnique to this deployment. Reuse only to update this same set; assign a new ID when gear is deployed again.
deployment_type stringRequiredsingle: one trap. trawl: at least two traps connected by groundlines, with only the ends marked. line: a series of singles, each with its own gear mark.
traps_in_set integerRequiredUse 1 for a single, the actual number of fishing traps for a trawl, or the number of traps in a line.
trawl_path TrawlPath | nullOptionalGeoJSON LineString; follow the trawl path rules below. View TrawlPath fields
share_with array<string> | nullOptionalAllowed destinations: PSMFC and Earth_Ranger. Name each separately. An empty selection excludes these destinations and Government Subscribers; ordinary permitted manufacturer sharing still applies.
traps array<Trap>RequiredOne object per marked gear unit, not per unmarked fishing trap in a trawl. View Trap fields
fishery stringRequiredUse a fishery name from the accepted values below, with exact case and underscores (Appendix A.5). Request additions through Polaris.
permit_number stringRequiredFisher’s permit number, consistent with the issuing state or federal management entity’s format.
fisher_name stringRequiredName of the fisher using the gear, in firstname lastname format.
vessel_name stringRequiredName of the vessel using the gear, in vessel name format.
when_updated_utc UTC timestamp | nullRead-onlySet by the server on upload. Omit from submissions; client values are ignored.

Trap

One marked gear unit · Data Policy Appendix A.4

Trap submission fields and policy requirements
Field / typeRequirementDescription
trap_id UUID v4RequiredAssign to the physical on-demand unit. If no unique unit exists, use a unique ID for that mark. For a trawl with a device on only one end, give the other end a separate ID. Reuse is allowed, but only one instance may be deployed at a time.
sequence integer > 0RequiredSingle: 1. Trawl: 1 and 2 for the two ends. Line: number each mark in order starting at 1. Zero is not a valid submission value.
latitude number, −90 to 90RequiredDeployed latitude in decimal degrees. Submit full available precision, at least five decimal places; do not round.
longitude number, −180 to 180RequiredDeployed longitude in decimal degrees. Submit full available precision, at least five decimal places; do not round.
deploy_datetime_utc UTC timestampRequiredWhen the gear mark was deployed.
surface_datetime_utc UTC timestamp | nullConditionalRequired for timed-release gear: when the buoy will surface. Set to null for gear without timed release.
retrieved_datetime_utc UTC timestamp | nullConditionalRequired when gear is retrieved: the time of retrieval.
status stringRequireddeployed, retrieved or lost. Submit updates promptly when status changes.
accuracy stringRequiredGPS, acoustic or estimated (case-sensitive).
release_type stringRequiredacoustic, timed, other or none. Send explicitly, including none when there is no release.
is_on_end booleanRequiredWhether this mark is on an end of the set. true for singles and both ends of a trawl.
manufacturer string | nullConditionalRequired when the device’s serial number is used for fishing purposes, such as an on-demand release; otherwise null. Use the listed uppercase manufacturer code (Appendix A.6).
model string | nullConditionalRequired under the same device condition as manufacturer; otherwise null. Use a model name or number consistently for that manufacturer.
serial_number string | nullConditionalRequired under the same device condition as manufacturer; otherwise null. Supply the manufacturer’s serial number; the test schema limits it to 32 characters.

Trawl paths

When supplying trawl_path, use a GeoJSON LineString with numeric [longitude, latitude] points. The first and last points must match the set’s first and last trap locations. Update path points as the vessel moves; the recommended distance increment is 100 m.

If either end is retrieved, the entire set and its path are retrieved. Appendix A.3 specifies that a path whose endpoints no longer match the updated set positions is greyed out, with a straight dashed line between the trawl ends.

TrawlPath

TrawlPath fields
Field / typeRequirementDescription
type stringRequired by Data RulesMust be LineString when a trawl_path is supplied. Default: "LineString"
coordinates array<array<number>>Required
Accepted fishery names and manufacturer codes

Use the exact values in Appendix A.5–A.6. Request additions through Polaris for RMW approval. A manufacturer code does not establish an active integration.

Fishery names

  • CA_Box_Crab
  • CA_Coonstripe_Shrimp
  • CA_Dungeness_Crab
  • CA_Hagfish
  • CA_Rock_Crab
  • CA_Spiny_Lobster
  • CA_Spot_Prawn
  • MA_American_Lobster
  • ME_American_Lobster
  • OR_Dungeness_Crab
  • RI_American_Lobster
  • WA_Dungeness_Crab
  • FF_American_Lobster
  • FF_Sablefish
  • FF_SE_Black_Sea_Bass
  • CAN_American_Lobster
  • CAN_Snow_Crab
  • AUS_Southern_Rock_Lobster
  • IDN_Lobster

Manufacturer codes

ASH
Ashored Innovations
DES
Desert Star Systems
DEV
DevOcean Solutions
EDG
EdgeTech
FIO
Fio Marine
GUA
Guardian Ropeless
LIF
Lift Labs
NOV
Nova Robotics
PUG
Puget Buoy
ROP
Ropeless Systems
SME
Smelts
SUB
Sub Sea Sonics

Example request

Replace the credential placeholder with your test key in your server-side client. All gear values are synthetic. This example has no timed release and no device whose serial number is used for fishing; use fresh test identifiers and accurate values for real submissions.

upload_deployments request
{
  "api_key": "YOUR_TEST_API_KEY",
  "format_version": 0.3,
  "sets": [
    {
      "vessel_id": "ef3d9aa2-7e60-42f6-8bb0-b7ae1e57c001",
      "set_id": "58b28f35-9d3b-4cb1-8caf-a2cfbb7d1002",
      "deployment_type": "single",
      "traps_in_set": 1,
      "fishery": "MA_American_Lobster",
      "permit_number": "TEST-ONLY-001",
      "fisher_name": "Example Fisher",
      "vessel_name": "Example Vessel",
      "share_with": [],
      "trawl_path": null,
      "traps": [
        {
          "trap_id": "8483f040-d633-4338-80ab-e9098268c003",
          "sequence": 1,
          "latitude": 41.2980618,
          "longitude": -70.9859833,
          "deploy_datetime_utc": "2026-10-17T12:00:00Z",
          "surface_datetime_utc": null,
          "retrieved_datetime_utc": null,
          "status": "deployed",
          "accuracy": "GPS",
          "release_type": "none",
          "is_on_end": true,
          "manufacturer": null,
          "model": null,
          "serial_number": null
        }
      ]
    }
  ]
}

For timed gear, supply surface_datetime_utc. When a device’s serial number is used for fishing, supply manufacturer, model and serial_number. Otherwise follow the null rules above.

To report retrieval, update the same set with all required fields, status: "retrieved" and the actual retrieved_datetime_utc. A subsequent deployment needs a new set_id; a reused trap_id may have only one deployed instance at a time.

Response

HTTP 200 · DeploymentsUploadResponse

The published response model describes possible fields. Your category, record sharing and field approvals determine the data you may receive.

DeploymentsUploadResponse response fields
Field / typeRequirementDescription
result UploadResult | nullOptional View UploadResult fields

UploadResult

UploadResult nested response fields
Field / typeRequirementDescription
description stringOptional Default: "Update confirmation"
acknowledged booleanRequiredtrue if data successfully saved
datetime_utc string (date-time)RequiredUTC timestamp when saved. ISO 8601 format.
trap_count integerRequiredNumber of traps in this upload.
failed_sets array<FailedSet>RequiredList of sets that failed to upload. View FailedSet fields
saved_sets array<SavedSet>RequiredList of sets that were saved. View SavedSet fields

FailedSet

FailedSet nested response fields
Field / typeRequirementDescription
set_id stringRequiredUUID of set that failed to upload.
reason stringRequiredReason for failure.

SavedSet

SavedSet nested response fields
Field / typeRequirementDescription
set_id stringRequiredUUID of set that was saved.

Errors and updates

HTTP 422 returns validation errors in detail, including loc (field location), msg (message) and type. Handle other HTTP errors and connection failures as well.

Inspect saved_sets and failed_sets; HTTP 200 alone does not confirm every set was saved. Submit updates promptly when status, position or conditions change.

When notified of inaccurate location, status or identity data, acknowledge within one business day and correct within two. For other issues, acknowledge within two and correct within five, unless Polaris agrees a longer period under Policy §4.4.

HTTPValidationError

HTTPValidationError error fields
Field / typeRequirementDescription
detail array<ValidationError>Optional View ValidationError fields

ValidationError

ValidationError error fields
Field / typeRequirementDescription
loc array<string | integer>Required
msg stringRequired
type stringRequired
input anyOptional
ctx objectOptional