> ## 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.

# Create load reference

> Create a custom reference on an existing load by load number, optionally tied to a tenant catalog definition, with values up to 40 characters.

Adds a custom reference to a load that already exists. Creating a reference does **not** take an `If-Match` header; the server retries bounded concurrency conflicts internally. The response includes a refreshed load `ETag` you can carry into a later update.

Requires `load:update`.

See [Updating records safely](/en/api/guides/concurrency#custom-references-on-loads-and-stops) for how create and update differ on this surface.

### Path parameters

| Name | Type | Required | Description |
| - | - | - | - |
| version | string | Yes | API version (for example `2.0`). |
| loadNumber | string | Yes | Business load number of the load. |

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| Name | string | Yes | Reference name. At most **50** characters. For catalog-backed writes, must match the configured definition name. |
| Value | string | Yes | Reference value. At most **40** characters (enough for a 36-character CFDI folio UUID). `OrderNumber` / `PONumber` stay at X12 **30**. |
| ReferenceId | string | No | Optional catalog definition id from [List reference definitions](/en/api/reference/references/list-reference-definitions). |

```json theme={null}
{
  "Name": "Customer PO",
  "Value": "PO-123",
  "ReferenceId": "tenant-reference-id"
}
```

### Example

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v2.0/loads/{loadNumber}/references' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "Name": "Customer PO",
    "Value": "PO-123",
    "ReferenceId": "tenant-reference-id"
  }'
```

### Status codes

| Code | Description |
| - | - |
| 201 | Reference created; body is the reference; `ETag` header is the refreshed load validator. |
| 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 | No load was found for the load number, or the catalog definition is not visible for loads. |
| 409 | This load already has a value for that catalog definition — update the existing instance instead. |

<Warning>
  Free-form creates (no `ReferenceId`) are not idempotent. Do not automatically replay a `POST` unless you have confirmed the first request did not commit. Use [Update load reference](/en/api/reference/loads/update-load-reference) with the returned instance id to overwrite.
</Warning>


## OpenAPI

````yaml POST /api/p/v{version}/loads/{loadNumber}/references
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:
    post:
      tags:
        - Loads
      summary: Create load reference
      description: >-
        Creates a custom reference on an existing load. No `If-Match` header is
        required; the server retries bounded concurrency conflicts internally.
        Both create and update return a refreshed load `ETag` on the response.


        `Name` must be 50 characters or fewer. `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 not raised by
        this endpoint.


        When `ReferenceId` names a catalog definition, a second create for the
        same definition on this load returns `409 Conflict`. Free-form creates
        are not idempotent — use `PUT` with the returned instance id to
        overwrite. Requires `load:update`.
      parameters:
        - name: loadNumber
          in: path
          required: true
          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'
        '201':
          description: Created
          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'
        '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 <token>`.

````