> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Label

> Create a label for a label request.

#### Required API key scopes
- Labels (Write)




## OpenAPI

````yaml post /labels
openapi: 3.1.0
info:
  title: Labels API
  description: API for managing label requests
  version: v1
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Label Requests
paths:
  /labels:
    post:
      tags:
        - Label Requests
      summary: Create Label
      description: |
        Create a label for a label request.

        #### Required API key scopes
        - Labels (Write)
      operationId: create-label-request-label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLabelRequest'
      responses:
        '201':
          description: Created
          headers:
            Location:
              description: >
                URL of the created label's status-update endpoint (`PUT
                /labels/{id}`).
              schema:
                type: string
              example: https://api.loopreturns.com/api/v1/labels/67329889100573
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The associated label request could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelOperationError'
              example:
                errors: Label request not found.
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          description: An unexpected error occurred while creating the label.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelOperationError'
              example:
                errors: Error posting label create request.
      security:
        - oauth2:
            - labels:write
        - labels-write: []
components:
  schemas:
    CreateLabelRequest:
      type: object
      properties:
        label_request_id:
          type: integer
          description: The label request id this label applies to.
          example: 67329889100573
        tracking_number:
          type: string
          maxLength: 256
          description: The tracking number associated with the label.
          example: '9400136105440512280610'
        tracking_url:
          type:
            - string
            - 'null'
          maxLength: 2048
          description: The tracking URL associated with the label.
          example: >-
            https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610
        carrier:
          type: string
          maxLength: 32
          description: The carrier associated with the label.
          example: USPS
        label_url:
          type:
            - string
            - 'null'
          maxLength: 2048
          description: |
            The URL containing the printable PDF of the labels.
            Required unless `qrcode_url` is provided.
          example: https://s3.amazonaws.com/example-bucket/label.pdf
        qrcode_url:
          type:
            - string
            - 'null'
          maxLength: 512
          description: The QR Code URL containing the printable PDF of the labels.
          example: https://s3.amazonaws.com/example-bucket/qrcode.pdf
        rate:
          $ref: '#/components/schemas/MoneySetData'
      required:
        - label_request_id
        - tracking_number
        - carrier
        - rate
      anyOf:
        - required:
            - label_url
        - required:
            - qrcode_url
    LabelResponse:
      type: object
      required:
        - id
        - tracking_number
        - carrier
        - rate
        - status
        - created_at
      properties:
        id:
          type: integer
          format: int64
          description: The id of the label you created.
          example: 67329889100573
        tracking_number:
          type: string
          description: The tracking number associated with the label.
          example: '9400136105440512280610'
        tracking_url:
          type:
            - string
            - 'null'
          description: The tracking URL associated with the label.
          example: >-
            https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610
        carrier:
          type: string
          description: The carrier associated with the label.
          example: USPS
        label_url:
          type:
            - string
            - 'null'
          description: The URL containing the printable PDF of the labels.
          example: https://s3.amazonaws.com/example-bucket/label.pdf
        qrcode_url:
          type:
            - string
            - 'null'
          description: The QR Code URL containing the printable PDF of the labels.
          example: https://s3.amazonaws.com/example-bucket/qrcode.pdf
        rate:
          $ref: '#/components/schemas/MoneySetData'
        status:
          $ref: '#/components/schemas/LabelFullStatusEnum'
        created_at:
          $ref: '#/components/schemas/Date'
    LabelOperationError:
      type: object
      description: >
        Error envelope returned by the label create and update operations.
        Unlike the generic

        error responses, `errors` is a single message string rather than an
        object or array.
      required:
        - errors
      properties:
        errors:
          type: string
          example: Label not found.
    MoneySetData:
      type: object
      example:
        - amount: 50000
          currency_code: USD
        - amount: 25000
          currency_code: CAD
        - amount: 1500
          currency_code: EUR
      properties:
        amount:
          type: integer
          format: int32
          description: The amount represented in cents.
          example: 25000
        currency_code:
          type: string
          example: EUR
          description: The 3 character (ISO 4217) currency code.
      required:
        - amount
        - currency_code
    LabelFullStatusEnum:
      type: string
      description: The current status of the label.
      enum:
        - queueable
        - queued
        - queued_for_purchase
        - purchase_failed
        - new
        - pre_transit
        - in_transit
        - out_for_delivery
        - delivered
        - available_for_pickup
        - cancelled
        - unknown
        - return_to_sender
        - failure
        - error
        - refund_requested
      example: new
    Date:
      type: string
      description: The date the label was created.
      format: date-time
      example: '2023-04-25T13:25:00-05:00'
  responses:
    Unauthorized:
      description: The request could not be authorized.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: '401'
                  http_code:
                    type: string
                    example: GEN-UNAUTHORIZED
                  message:
                    type: string
                    example: Unauthorized.
    Unprocessable:
      description: >
        Validation failed. Returned when the request body does not satisfy the
        endpoint's

        validation rules.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: The status field is required.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
                example:
                  status:
                    - The status field is required.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.loopreturns.com/authorize
          tokenUrl: https://oauth.loopreturns.com/oauth/token
          scopes:
            labels:read: Read access to labels
            labels:write: Create and modify labels
            label_requests:read: Read access to label requests
            label_requests:write: Create and modify label requests
            returns: Access to returns operations
    labels-write:
      name: X-Authorization
      type: apiKey
      in: header
      description: 'API Scope: "Labels (write)"'
      x-scope: Labels (Write)

````