lastscanned Account API

openapi: 3.2.0
info:
  title: lastscanned Account API
  version: '1'
  description: 'Package tracking across 542 carriers: UPS, USPS, DHL, FedEx, Amazon Logistics, OnTrac, UniUni, GOFO, Veho, Spee-Dee, CDL Last Mile, Better Trucks, AxleHire (Jitsu), CIRRO, Yanwen, 4PX, Cainiao, YunExpress, SpeedX, Intelcom, Canada Post, Purolator, TForce Final Mile, GLS US, OSM Worldwide, Pitney Bowes, CNE Express, SunYou, UBI Smart Parcel, Sendle, Asendia, Japan Post, SingPost, Korea Post, NZ Post, DPD UK, APC Postal Logistics, Landmark Global, Canpar, Loomis Express, GLS Canada, Nationex, bpost, PostNord, Austrian Post, Poczta Polska, GLS, InPost, Packeta, Hermes Germany, YDH, Equick China, TopYou, La Poste, PostNL, Correos, Poste Italiane, CJ Logistics, Yamato Transport, Delhivery, Blue Dart, Evri, An Post, Swiss Post, BRT, Aramex Australia, CouriersPlease, Team Global Express, Ninja Van, Flash Express, ICS Courier, Chit Chats, Passport, ePost Global, JYExpress, Sagawa Express, Aramex, T-cat, Hanjin, Lotte Global Logistics, Logen, Shadowfax, SFC, Anjun, Winit, NZ Couriers, Post Haste, Castle Parcels, Gaopost, YF Express, GDWSE, Chronopost, Bring, Posti, Česká pošta, CTT, SEUR, Nova Poshta, Sameday, FAN Courier, Econt, Meest, Yurtiçi Kargo, Paquetexpress, Andreani, The Courier Guy, PostNet, 99minutos, Mainfreight, YTO Express, SPL Saudi Post, KEX Express, Pos Malaysia, GDEX, City-Link Express, LBC Express, DHL eCommerce, DHL Parcel NL, DHL Parcel Iberia, DHL Parcel PL, DHL eCommerce UK, DHL Freight, DHLink, XQ Express, Ali Business Logistics, Omniva, Ukrposhta, Speedy, DPD Romania, DPD Poland, DPD, DPD Portugal, Thailand Post, Chunghwa Post, EMS, ELTA, Estafeta, Total Express, Sagawa Global, MRW, Nacex, HuaHan, Chukou1, ZTO International, STO Express, OCA, OCASA, Coordinadora, HCT Logistics, Starken, Hunter Express, Aras Kargo, SMSA Express, Naqel Express, AUS Express, BDTPost, Boyi Hongda, BYT Logistics, CD International, CHH Logistics, Chuangyu Logistics, DHFEX, EDL Express, ED POST, ETSCP, Fuhai Wulian, FJEX, JSH Galaxy Express, ASGYL, Tianhai Supply Chain, YouMeiYuTong, HLSZ56, HOYANG Express, Heping Logistics, HSD Express, JTEX, PD Express, Jiuhao International, JDT Logistics, LeiYi Logistics, Lingdong International, Mayi Yinfu, Miuson Express, Pingda International, PY Express, QFL Express, QYEXP, Qyun Express, Shang Fang International, SHSGEXP, StarGlobal, TDE Logistics, Tianhui Hengyuan, Usky Express, WM Cloud, XS Express, YJI Logistics, Yilong Logistics, Yincag Logistics, ESHUN, ACS Courier, Airpak Express, Allegro One, Anteraja, AyMakan, Cargus, CDEK, Correos Express, CTT Express, DAI Post, ECMS Express, Ecoscooting, Geis, Jeebly, DHL eCommerce Türkiye, Northline, Nova Global, OMGO, Pakistan Post, Paperfly, Pathao Courier, PHLPost, Planzer, Pos Indonesia, Posta Shqiptare, Pošta Slovenije, PostEx, Pósturinn, Pro Carrier, PTS Worldwide Express, Quantium Solutions, Qwintry, Redur, RedX, South African Post Office, Seino Transportation, Sendex, Sending, Serpost, Servientrega, Shipa, ShipEntegra, Shree Maruti Courier, SkyNet Worldwide Express, SkyPostal, Speedaf, SpeedPAK, PostNL (Spring GDS), Slovak Parcel Service, SPX Express Indonesia, SPX Express Malaysia, SPX Express Philippines, SPX Express Thailand, SPX Express Vietnam, Stallion Express, Starex, ST Courier, Straightship, Swiss Post Cargo, TIPSA, TMM Express, TNT, TOPTRANS, TracX Logis, TWS Express Courier, Urvaam, Valmo, Vasp Expresso, Venipak, Vinted Go, Vozovoz, Zeleris, ZR Express, 4-72, Kuehne+Nagel, MailPlus, Amerijet, Matkahuolto, NOEST Express, 17FEIA, 2GO Express, 4Sides, 5Post, A1 POST, ABF Freight, A.'
servers:
- url: https://api.lastscanned.com
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Account
paths:
  /v1/account:
    get:
      operationId: getAccount
      tags:
      - Account
      summary: Get the account
      responses:
        '200':
          description: The account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  name:
                    type:
                    - string
                    - 'null'
                  dailyLimit:
                    type:
                    - integer
                    - 'null'
                    description: Tracking numbers per UTC day; `null` for no daily limit.
                  createdAt:
                    type: string
                  usedToday:
                    type: integer
                    description: Tracking numbers counted today (UTC).
                  keys:
                    type: array
                    description: Active keys. Only prefixes are kept; a full key is shown once, when it is made.
                    items:
                      $ref: '#/components/schemas/KeySummary'
              example:
                id: acct_9c4e1b7a2d6f3e80
                email: you@example.com
                name: null
                dailyLimit: 5
                createdAt: '2026-10-01T09:12:44Z'
                usedToday: 2
                keys:
                - prefix: lREDACTED_STRIPE_KEY
                  name: default
                  createdAt: '2026-10-01T09:12:44Z'
                  lastUsedAt: '2026-10-26T18:06:20Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/usage:
    get:
      operationId: getUsage
      tags:
      - Account
      summary: Daily usage
      parameters:
      - name: days
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 366
          default: 30
      responses:
        '200':
          description: One row per UTC day with activity, newest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - usage
                properties:
                  usage:
                    type: array
                    items:
                      type: object
                      properties:
                        day:
                          type: string
                          format: date
                        lookups:
                          type: integer
                          description: Tracking numbers asked for.
                        live:
                          type: integer
                          description: Lookups that went to the carrier rather than cache.
              example:
                usage:
                - day: '2026-10-26'
                  lookups: 4
                  live: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/lookups:
    get:
      operationId: getLookups
      tags:
      - Account
      summary: Lookup history
      description: One entry per tracking number per request, newest first, from the last 30 days.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: cursor
        in: query
        description: The previous page's nextCursor.
        schema:
          type: string
      - name: number
        in: query
        description: Only this tracking number, or numbers starting with it.
        schema:
          type: string
      responses:
        '200':
          description: A page of lookups.
          content:
            application/json:
              schema:
                type: object
                required:
                - lookups
                - nextCursor
                properties:
                  lookups:
                    type: array
                    items:
                      type: object
                      properties:
                        number:
                          type: string
                        carrier:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                          description: Null when the lookup failed; see error.
                        error:
                          type: string
                          nullable: true
                          description: The error code when there was no result.
                        source:
                          type: string
                          enum:
                          - api
                          - mcp
                          - playground
                        cached:
                          type: boolean
                        createdAt:
                          type: string
                          format: date-time
                  nextCursor:
                    type: string
                    nullable: true
                    description: Null on the last page.
              example:
                lookups:
                - number: 1Z999AA10123456784
                  carrier: ups
                  status: delivered
                  error: null
                  source: api
                  cached: false
                  createdAt: '2026-10-26T18:06:20Z'
                nextCursor: null
        '400':
          description: '`bad_request`: the cursor isn''t one this route returned.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: bad_request
                  message: Invalid cursor
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/keys:
    post:
      operationId: createKey
      tags:
      - Account
      summary: Create a key
      description: The full key is in this response only.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 60
            example:
              name: production
      responses:
        '200':
          description: The new key.
          content:
            application/json:
              schema:
                type: object
                required:
                - key
                - prefix
                - name
                properties:
                  key:
                    type: string
                    description: '`lsk_live_` + 32 hex characters.'
                  prefix:
                    type: string
                  name:
                    type:
                    - string
                    - 'null'
              example:
                key: lsk_live_…
                prefix: lREDACTED_STRIPE_KEY
                name: production
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/keys/{prefix}:
    delete:
      operationId: revokeKey
      tags:
      - Account
      summary: Revoke a key
      parameters:
      - name: prefix
        in: path
        required: true
        description: '`lsk_live_` + the key''s first 8 hex characters.'
        schema:
          type: string
          pattern: ^lsk_live_[0-9a-f]{8}$
        example: lREDACTED_STRIPE_KEY
      responses:
        '200':
          description: Revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked:
                    type: string
              example:
                revoked: lREDACTED_STRIPE_KEY
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ErrorBody:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - bad_request
          - unknown_carrier
          - unauthorized
          - free_lookup_used
          - payment_required
          - credits_used
          - not_found
          - rate_limited
          - internal_error
          - not_configured
          - carrier_error
        message:
          type: string
    KeySummary:
      type: object
      properties:
        prefix:
          type: string
          example: lREDACTED_STRIPE_KEY
        name:
          type:
          - string
          - 'null'
        createdAt:
          type: string
        lastUsedAt:
          type:
          - string
          - 'null'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
  responses:
    NotFound:
      description: '`not_found`: the carrier has no record of the number, or no such key.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: UPS returned no track details for that number
    Unauthorized:
      description: '`unauthorized`: missing, wrong or revoked key, or a disabled account.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer lsk_live_…`'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: '`x-api-key: lsk_live_…`'