Skip to content
YoPrintDevelopers

List a customer's files in one collection

Open .md

GET/v1/api/store/{team_slug}/customer/{hash_id}/media/collection/{collection}

v1Operation ID v1_public_customer_media_get_media_by_collection

Lists the customer's files in one collection:

  • tax_exemption: tax exemption certificates. The customer sees these in the customer portal.
  • external_file: files shared with the customer. Also shown in the portal.
  • internal_file: files for your team only.

The list is paged: pagination gives total, count, perPage, currentPage and totalPages. Ask for the next page with page; the page size is the team's setting (50 unless changed), and per_page is ignored.

Permission

Any member of the team.

Path parameters

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • hash_idstringrequired

    The customer's id (id from List customers or Create a customer). A hash id from an earlier answer; unique keys and document numbers (such as PO0042) don't work here.

    • Example EDhVUaC6jbLbed
  • collectionstringrequired

    Which files: tax_exemption (tax exemption certificates), external_file (files the customer can see in the portal) or internal_file (your team only).

    • One of: "tax_exemption", "external_file", "internal_file"
    • Example tax_exemption

Query parameters

  • pageinteger

    The page to return. Pages hold the team's page size (pagination_per_page in team settings: 50 unless changed, 5 to 100). per_page is not read here.

    • Default 1
    • Minimum 1
    • Example 1

Request body

This operation takes no request body.

Response

200Successful response.

  • dataarray of objectsrequired
    Fields of each item (18)
    • collectionstringrequired

      Customer files: tax_exemption, internal_file or external_file. Vendor files: default, mockup or production_file.

    • created_atstring (date-time)required
    • file_namestringrequired
    • idstringrequired
    • mime_typestring | nullrequired
    • namestring | nullrequired

      The display name.

    • sizeintegerrequired

      Bytes.

    • custom_propertiesobject | array
    • customer_idstring

      Customer files only.

    • dimensionsobject | null

      Pixel size of an image, read from its header; null for other files and for images uploaded before the size was recorded.

      Child fields (2)
    • is_imageboolean
    • positioninteger | null

      Where the file sorts.

    • previewobject | null

      Preview image links small, medium and large (250, 800 and 1200 px), or null when there is no preview.

    • preview_statestring

      ready: the preview links work. processing: an image over 10 MB whose stored preview a worker is still making (seconds); read the file again, or in the web app wait for media.preview_state_changed on the team channel. too_large: an image over 120 megapixels; it never gets a preview. failed: the worker gave up. none: not an image.

      • One of: "ready", "processing", "too_large", "failed", "none"
    • show_in_pdfboolean | null
    • source_media_idstring | null
    • urlstring | null

      Where to download the file.

    • view_urlstring | null

      A signed link to view the file. It expires: read it fresh, and don't store it.

  • statusintegerrequired
  • successbooleanrequired
  • paginationobject
    Child fields (6)
    • countintegerrequired
    • currentPageintegerrequired
    • perPageintegerrequired
    • totalintegerrequired
    • totalPagesintegerrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

    When
    No live customer with this id in the team: deleted customers are not found here. error.code is null and error.message names the record type.
    Fix
    Check the id. Find deleted customers with the trashed_only filter and restore them first.

  • 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

    When
    The collection is not one of the three (error.code validation_error, with the reason in error.message).
    Fix
    Use tax_exemption, external_file or internal_file.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com