Assign Shipper, Consignee, and Other Parties

Use this guide to assign parties to your shipments from code instead of the dashboard bulk update.

How parties and roles work

A party is a company in your account, managed through /v2/parties.
A party role links one party to one shipment or container in one role.
Roles are a list, not a field. A shipment can carry two parties as consignee. To replace a party, remove its role and assign a new one.

Role	Tracking request creation	Shipment	Container
`customer`	Yes	Yes	No
`shipper`	Yes	Yes	No
`consignee`	Yes	Yes	No
`notify_party`	Yes	Yes	No
`customs_broker`	Yes	Yes	No
`freight_forwarder`	Yes	Yes	No
`pickup_dray_carrier`	Yes	Yes	Yes

You need an API key. See Start here.

Find or create the party

Search your parties by name:

curl -s "https://api.terminal49.com/v2/parties?query=ACME" \
  -H "Authorization: Token YOUR_API_KEY"

If the party does not exist, create it:

Request

{
  "data": {
    "type": "party",
    "attributes": {
      "company_name": "ACME LOGISTICS"
    }
  }
}

Keep the returned data.id. It is the PARTY_ID below.

Assign roles when creating the tracking request

Pass each party as a relationship named after its role. One party per role. Endpoint: POST - https://api.terminal49.com/v2/tracking_requests

Request

{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MEDUFR030802",
      "scac": "MSCU"
    },
    "relationships": {
      "customer": { "data": { "id": "CUSTOMER_PARTY_ID", "type": "party" } },
      "shipper": { "data": { "id": "SHIPPER_PARTY_ID", "type": "party" } },
      "consignee": { "data": { "id": "CONSIGNEE_PARTY_ID", "type": "party" } },
      "freight_forwarder": { "data": { "id": "FORWARDER_PARTY_ID", "type": "party" } }
    }
  }
}

The roles are copied to the shipment when it is created. The tracking request response does not list them; read them on the shipment as shown below. A party from another account fails the whole request with 422 and a pointer to the relationship.

Assign roles to an existing shipment

Use this to add roles later, or to add a second party in the same role. Endpoint: POST - https://api.terminal49.com/v2/shipments/SHIPMENT_ID/party_roles

Request

{
  "data": {
    "type": "party_role",
    "attributes": {
      "role": "shipper"
    },
    "relationships": {
      "party": {
        "data": {
          "id": "PARTY_ID",
          "type": "party"
        }
      }
    }
  }
}

Response

{
  "data": {
    "id": "PARTY_ROLE_ID",
    "type": "party_role",
    "attributes": {
      "role": "shipper",
      "roleable_type": "Shipment",
      "roleable_id": "SHIPMENT_ID",
      "created_at": "2026-09-01T14:02:11Z",
      "updated_at": "2026-09-01T14:02:11Z"
    },
    "relationships": {
      "party": {
        "data": {
          "id": "PARTY_ID",
          "type": "party"
        }
      }
    }
  },
  "included": [
    {
      "id": "PARTY_ID",
      "type": "party",
      "attributes": {
        "company_name": "ACME LOGISTICS"
      }
    }
  ]
}

Send one request per role. Repeat with "role": "consignee" and "role": "freight_forwarder".

Read the roles on the shipment

Request the shipment with flag[parties]=true and include the parties:

curl -sg "https://api.terminal49.com/v2/shipments/SHIPMENT_ID?flag[parties]=true&include=party_roles.party" \
  -H "Authorization: Token YOUR_API_KEY"

The shipment carries a party_roles relationship and the included array holds each party_role and its party. The same flag works on GET /v2/shipments. -g stops curl from treating the brackets in flag[parties] as a range. To list the roles alone, use GET /v2/shipments/SHIPMENT_ID/party_roles.

Replace a party

To replace the consignee:

List the roles and find the party_role with "role": "consignee".
DELETE https://api.terminal49.com/v2/shipments/SHIPMENT_ID/party_roles/PARTY_ROLE_ID. Returns 204.
POST the new consignee.

Assign a dray carrier to a container

Containers accept one role, pickup_dray_carrier: Endpoint: POST - https://api.terminal49.com/v2/containers/CONTAINER_ID/party_roles Read it back with GET /v2/containers/CONTAINER_ID/party_roles.

Errors

Status	Cause	Fix
`401`	The party or the record belongs to another account	Use a party from `GET /v2/parties` and a shipment you created
`404`	Unknown shipment, container, or party role ID	Check the ID
`422` `Party has already been taken`	The same party already has this role on the record	Nothing to do, the role is set
`422` `'x' is not a valid role`	Unknown role name	Use a role from the table above
`422` `Role is not allowed for Cargo`	A role other than `pickup_dray_carrier` on a container	Assign it on the shipment instead

Getting Started

Tracking Fundamentals

Webhooks & Events

Integrations & Embeds

Platform & Reference

Assign Shipper, Consignee, and Other Parties

How parties and roles work

Find or create the party

Assign roles when creating the tracking request

Assign roles to an existing shipment

Read the roles on the shipment

Replace a party

Assign a dray carrier to a container

Errors

​How parties and roles work

​Find or create the party

​Assign roles when creating the tracking request

​Assign roles to an existing shipment

​Read the roles on the shipment

​Replace a party

​Assign a dray carrier to a container

​Errors

How parties and roles work

Find or create the party

Assign roles when creating the tracking request

Assign roles to an existing shipment

Read the roles on the shipment

Replace a party

Assign a dray carrier to a container

Errors