> ## Documentation Index > Fetch the complete documentation index at: https://terminal49.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Assign a shipment party role > Assign a party to a shipment in the Terminal49 API as shipper, consignee, freight forwarder, or another role. Attaches a party from your account to the shipment in one role. ## Path parameters | Parameter | Required | Description | | ------------- | -------- | ---------------------- | | `shipment_id` | Yes | The ID of the shipment | ## Roles `shipper`, `consignee`, `notify_party`, `customs_broker`, `customer`, `freight_forwarder`, `pickup_dray_carrier` ## Behavior * Roles are additive. Posting a second party with the same role keeps both * To replace a party, delete its role and create a new one * Posting the same party and role twice returns `422` * The party must belong to your account, otherwise the request returns `401` ## OpenAPI ````yaml post /shipments/{shipment_id}/party_roles openapi: 3.0.0 info: title: Terminal49 API Reference version: 0.2.0 contact: name: Terminal49 API support url: https://www.terminal49.com email: support@terminal49.com description: >- The Terminal 49 API offers a convenient way to programmatically track your shipments from origin to destination. Please enter your API key into the "Variables" tab before using these endpoints within Postman. x-label: Beta termsOfService: https://www.terminal49.com/terms servers: - url: https://api.terminal49.com/v2 description: Production security: - authorization: [] tags: - name: Containers - name: Custom Field Definitions - name: Custom Field Options - name: Custom Fields - name: Shipments - name: Locations - name: Events - name: Tracking Requests - name: Webhooks - name: Webhook Notifications - name: Ports - name: Metro Areas - name: Terminals - name: Routing (Paid) - name: Documents - name: Email Submissions - name: Document Schemas - name: Search - name: Parties paths: /shipments/{shipment_id}/party_roles: parameters: - schema: type: string name: shipment_id in: path required: true description: Shipment ID post: tags: - Parties summary: Assign a shipment party role description: >- Attaches a party to the shipment in the given role. Roles are additive: posting a second party with the same role keeps both. To replace a party, delete its role and create a new one. Posting the same party and role twice returns `422`. operationId: post-shipments-party-roles requestBody: content: application/json: schema: type: object required: - data properties: data: type: object required: - type - attributes - relationships properties: type: type: string enum: - party_role attributes: type: object required: - role properties: role: type: string enum: - shipper - consignee - notify_party - customs_broker - customer - freight_forwarder - pickup_dray_carrier description: >- Accepted values: `shipper`, `consignee`, `notify_party`, `customs_broker`, `customer`, `freight_forwarder`, `pickup_dray_carrier`. relationships: type: object required: - party properties: party: type: object required: - data properties: data: type: object required: - id - type properties: id: type: string format: uuid description: >- ID of a party in your account. See `GET /parties`. type: type: string enum: - party example: data: type: party_role attributes: role: shipper relationships: party: data: id: ba4cb904-827f-4038-8e31-1e92b3356218 type: party responses: '201': description: Created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/party_role' included: type: array items: $ref: '#/components/schemas/party' links: $ref: '#/components/schemas/link-self' examples: Party role: value: data: id: 1d0f2a0e-5c3b-4c7e-9a52-3b6f8d2e4a11 type: party_role attributes: role: shipper roleable_type: Shipment roleable_id: 8f0c6b1a-2d4e-4f7b-9c3a-5e6d7f8a9b0c created_at: '2026-09-01T14:02:11Z' updated_at: '2026-09-01T14:02:11Z' relationships: party: data: id: ba4cb904-827f-4038-8e31-1e92b3356218 type: party included: - id: ba4cb904-827f-4038-8e31-1e92b3356218 type: party attributes: company_name: ACME LOGISTICS nickname: ACME links: self: >- /v2/shipments/8f0c6b1a-2d4e-4f7b-9c3a-5e6d7f8a9b0c/party_roles '401': description: >- Unauthorized. Also returned when the party or the record belongs to another account. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/error' examples: Party from another account: value: errors: - detail: You are not allowed to perform this action '404': description: Not Found '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/error' examples: Duplicate role: value: errors: - status: '422' source: pointer: '' title: Unprocessable Entity detail: Party has already been taken code: taken Unknown role: value: errors: - detail: '''owner'' is not a valid role' components: schemas: party_role: title: Party role model type: object properties: id: type: string format: uuid type: type: string enum: - party_role attributes: type: object properties: role: type: string enum: - shipper - consignee - notify_party - customs_broker - customer - freight_forwarder - pickup_dray_carrier description: >- Role the party plays on the record. Shipments accept every value. Containers accept only `pickup_dray_carrier`. roleable_type: type: string enum: - Shipment - Cargo description: >- Type of the record the role is attached to. `Cargo` is returned for containers. roleable_id: type: string format: uuid description: ID of the shipment, container, or tracking request. created_at: type: string format: date-time updated_at: type: string format: date-time relationships: type: object properties: party: type: object properties: data: type: object properties: id: type: string format: uuid type: type: string enum: - party party: title: Party model type: object properties: id: type: string format: uuid attributes: type: object required: - company_name properties: company_name: type: string description: Company name type: type: string enum: - party required: - attributes link-self: title: link type: object properties: self: type: string format: uri error: title: Error model type: object properties: detail: type: string nullable: true title: type: string nullable: true source: type: object nullable: true properties: pointer: type: string nullable: true parameter: type: string nullable: true code: type: string nullable: true status: type: string nullable: true meta: type: object nullable: true additionalProperties: true required: - title securitySchemes: authorization: name: Authorization type: apiKey in: header description: >- Use a Terminal49 API key in the `Authorization` header with the `Token` prefix. `Authorization: Token YOUR_API_KEY` ````