> ## Documentation Index > Fetch the complete documentation index at: https://docs.alvys.com/llms.txt > Use this file to discover all available pages before exploring further. # Update load reference > Update an existing custom reference on a load by load number and reference instance id, requiring If-Match with the current load ETag. Overwrites an existing custom reference on a load. **`If-Match` is required** with the current load `ETag` from [Get load](/en/api/reference/loads/get-load) or from a prior reference write. A successful update returns a refreshed load `ETag`. Requires `load:update`. See [Updating records safely](/en/api/guides/concurrency#custom-references-on-loads-and-stops). ### Path parameters | Name | Type | Required | Description | | - | - | - | - | | version | string | Yes | API version (for example `2.0`). | | loadNumber | string | Yes | Business load number of the load. | | referenceId | string | Yes | Existing **reference instance** id (from a load read or a prior create). | ### Headers | Header | Type | Required | Description | | - | - | - | - | | If-Match | string | Yes | Current load `ETag`. Omit → `428`; stale → `412`. | ### Request body | Field | Type | Required | Description | | - | - | - | - | | Name | string | Yes | Reference name. At most **50** characters. | | Value | string | Yes | Reference value. At most **40** characters (CFDI folio UUID length). `OrderNumber` / `PONumber` stay at **30**. | | ReferenceId | string | No | Optional catalog definition id. | ### Example ```bash theme={null} curl --location --request PUT 'https://integrations.alvys.com/api/p/v2.0/loads/{loadNumber}/references/{referenceId}' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --header 'If-Match: "00000000-0000-0000-0000-000000000001"' \ --data-raw '{ "Name": "Customer PO", "Value": "PO-456" }' ``` ### Status codes | Code | Description | | - | - | | 200 | Reference updated; refreshed load `ETag` on the response. | | 400 | Validation failed (including name or value length). | | 401 | Authentication failed or the token is missing. | | 403 | The token is not authorized to update loads. | | 404 | Load or reference instance was not found. | | 412 | The `If-Match` ETag did not match the load's current version. | | 428 | The `If-Match` header was not provided. | ## OpenAPI ````yaml PUT /api/p/v{version}/loads/{loadNumber}/references/{referenceId} openapi: 3.0.1 info: title: Alvys description: >- Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests. contact: name: Alvys Support url: https://www.alvys.com/resources/contact/ version: v1 servers: - url: https://integrations.alvys.com description: Public API Server - url: https://api.alvys.com/ description: Public API Server security: - Public: [] tags: - name: Authentication description: Obtain an OAuth 2.0 access token for the Alvys Public API. - name: Carrier Settlement Statements description: >- Search carrier settlement statements and retrieve a single statement by number. - name: Carriers description: Read carrier records, search carriers, and manage carrier documents. - name: Customers description: Create, read, update, delete, and search customer records. - name: Deductions description: >- Create one-time deductions and search or delete existing deduction records. - name: DispatchPreferences description: Dispatch preferences endpoints for reading dispatch rules and preferences. - name: Driver Settlement Statements description: >- Search driver settlement statements and retrieve a single statement by number. - name: Drivers description: >- Read driver records, search drivers and driver events, and manage driver documents. - name: Fuel description: Read and search fuel transactions. - name: Invoices description: >- Read invoices, create carrier invoices, and record carrier and customer payments. - name: Loads description: >- Read, update, and search loads; manage load documents, notes, and custom references. - name: Locations description: Read and search company location details. - name: Maintenance description: Read and search maintenance records. - name: References description: >- List tenant custom reference definitions and create or update values on existing loads and stops. - name: Subsidiaries description: >- List your company's subsidiaries and read a single subsidiary, so an integration can resolve a subsidiary id to a recognizable name. - name: Tenders description: Create, accept, reject, cancel, update, and search inbound EDI tenders. - name: Tolls description: Read and search toll transactions. - name: Tracking description: >- Record an asset's current location or telemetry from a third-party source, such as an external ELD or a self-reporting vehicle. - name: Trailers description: Read trailers, search trailer events, and manage trailer documents. - name: Trips description: >- Read and search trips; manage trip documents, stop appointments, arrivals, departures, and stop custom references. - name: Trucks description: Read trucks, search truck events, and manage truck documents. - name: Users description: List and search users. - name: Visibility description: >- Read inbound and outbound visibility history and search outbound visibility errors. - name: Webhooks description: >- Create, read, update, delete, enable, disable, verify, test, and rotate secrets for webhook subscriptions; read event types, delivery logs, and health metrics. - name: Accessorials - name: Credits paths: /api/p/v{version}/loads/{loadNumber}/references/{referenceId}: put: tags: - Loads summary: Update load reference description: >- Updates an existing custom reference on a load. **`If-Match` is required** with the current load `ETag` (from Get Load or a prior reference write). Missing header → `428`; stale → `412`. Returns the refreshed load `ETag`. `Name` ≤ 50 characters; `Value` ≤ **40** characters. Requires `load:update`. parameters: - name: loadNumber in: path required: true schema: type: string - name: referenceId in: path required: true schema: type: string - name: If-Match in: header schema: type: string - name: version in: path description: API version (e.g., 2.0) required: true schema: type: string default: '2.0' example: '2.0' requestBody: content: application/json-patch+json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.References.Request.ReferenceWriteRequest application/json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.References.Request.ReferenceWriteRequest text/json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.References.Request.ReferenceWriteRequest application/*+json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.References.Request.ReferenceWriteRequest required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse' '400': description: Bad Request content: application/json: schema: $ref: >- #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '412': description: Precondition Failed content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '428': description: Precondition Required content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' security: - Public: [] components: schemas: Alvys.Models.References.Request.ReferenceWriteRequest: required: - Name - Value type: object properties: Name: type: string maxLength: 50 description: >- Reference name. Must be 50 characters or fewer. For catalog-backed writes, must match the configured definition name. Value: type: string maxLength: 40 description: >- Reference value. Must be 40 characters or fewer — enough for a 36-character CFDI folio UUID. OrderNumber and PONumber stay at the X12 30-character bound and are unchanged by this field. ReferenceId: type: string nullable: true description: >- Optional tenant catalog definition id from List custom reference definitions. When set, the value is validated against that definition. additionalProperties: false Alvys.Models.References.ReferenceResponse: required: - Name - Value type: object properties: Id: type: string nullable: true ReferenceId: type: string nullable: true Name: type: string Value: type: string Type: type: string nullable: true Access: type: string nullable: true Origin: type: string nullable: true additionalProperties: false Microsoft.AspNetCore.Mvc.ValidationProblemDetails: required: - Errors type: object properties: Errors: type: object additionalProperties: type: array items: type: string Type: type: string nullable: true Title: type: string nullable: true Status: type: integer format: int32 nullable: true Detail: type: string nullable: true Instance: type: string nullable: true additionalProperties: {} Microsoft.AspNetCore.Mvc.ProblemDetails: type: object properties: Type: type: string nullable: true Title: type: string nullable: true Status: type: integer format: int32 nullable: true Detail: type: string nullable: true Instance: type: string nullable: true additionalProperties: {} securitySchemes: Public: type: http scheme: bearer bearerFormat: JWT description: >- OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as `Authorization: Bearer `. ````