# Talque Order API

## Read purchase orders by ID

> Looks up one or more purchase orders by their IDs.

```json
{"openapi":"3.0.3","info":{"title":"Talque Order API","version":"1.0.0"},"paths":{"/api/v1/purchase/order/read":{"post":{"summary":"Read purchase orders by ID","description":"Looks up one or more purchase orders by their IDs.","parameters":[{"name":"X-TQ-CLIENT-ID","in":"header","required":true,"schema":{"type":"string"},"description":"The API client ID for authentication."},{"name":"X-TQ-SECRET","in":"header","required":true,"schema":{"type":"string"},"description":"The API client secret for authentication."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"purchaseOrderIdList":{"type":"array","items":{"type":"string"},"description":"List of purchase order IDs to look up."}},"required":["orgId","purchaseOrderIdList"]}}}},"responses":{"200":{"description":"Lookup completed (individual orders may still be not found)","content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"orderById":{"type":"object","additionalProperties":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the purchase order was found."},"reason":{"type":"string","description":"Machine-readable result code."},"model":{"type":["object","null"],"properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"purchaseOrderId":{"type":"string","description":"The unique identifier of the purchase order."},"ctime":{"type":"integer","description":"Creation time of the purchase order (milliseconds since epoch)."},"mtime":{"type":"integer","description":"Last modification time of the purchase order (milliseconds since epoch)."},"expiresAt":{"type":"integer","description":"Expiration time of the purchase order (milliseconds since epoch)."},"status":{"type":"string","description":"Purchase order lifecycle status."},"approval":{"type":"string","description":"Approval status of the order."},"isInvalidated":{"type":"boolean","description":"Whether the order has been invalidated by an admin."},"isTest":{"type":"boolean","description":"Whether this is a test purchase order."},"accountId":{"type":"string","description":"Account ID of the buyer."},"purchaseEmail":{"type":["string","null"],"description":"Buyer email address at the time of purchase."},"locale":{"type":"string","description":"Locale used when placing the order."},"currency":{"type":"string","description":"ISO currency code for the order."},"invoiceId":{"type":["string","null"],"description":"Most recent invoice ID for the order, if any."},"billingAddress":{"type":"object","properties":{"billingAddressType":{"type":"string","description":"Type of billing address."},"companyName":{"type":["string","null"],"description":"Company name on the billing address."},"personalName":{"type":["string","null"],"description":"Personal name on the billing address."},"costCenter":{"type":["string","null"],"description":"Cost center."},"street":{"type":["string","null"],"description":"Street address."},"zipCode":{"type":["string","null"],"description":"Postal code."},"city":{"type":["string","null"],"description":"City."},"country":{"type":["string","null"],"description":"ISO country code."},"phone":{"type":["string","null"],"description":"Phone number."},"text":{"type":["string","null"],"description":"Free-text address field."},"wantHardcopy":{"type":["boolean","null"],"description":"Whether the buyer requested a printed invoice."}},"required":["billingAddressType"],"description":"Billing address for the order."},"initial":{"type":"object","properties":{"total":{"type":"integer","description":"Total amount in the smallest currency unit (e.g. cents)."},"net":{"type":"integer","description":"Net amount."},"tax":{"type":"integer","description":"Tax amount."},"currency":{"type":"string","description":"ISO currency code."}},"required":["total","net","tax","currency"],"description":"Initial amount paid for the order."},"refund":{"type":"object","properties":{"total":{"type":"integer","description":"Total amount in the smallest currency unit (e.g. cents)."},"net":{"type":"integer","description":"Net amount."},"tax":{"type":"integer","description":"Tax amount."},"currency":{"type":"string","description":"ISO currency code."}},"required":["total","net","tax","currency"],"description":"Accumulated refunded amount."},"lastPaymentError":{"type":["integer","null"],"description":"Timestamp of the last payment error, if any (milliseconds since epoch)."},"paymentErrorMessage":{"type":["string","null"],"description":"User-facing payment error message, if any."},"note":{"type":"string","description":"Admin comments on the order."},"customData":{"description":"Custom field data collected during checkout."},"attest":{"type":"object","properties":{"message":{"type":"string","description":"Optional message from the external validation API."},"extSurveyId":{"type":["string","null"],"description":"External survey identifier, if any."},"documents":{"type":"array","items":{"type":"string"},"description":"IDs of documents uploaded during order submission."},"categories":{"type":"array","items":{"type":"string"},"description":"Additional participant categories."},"info":{"type":"array","items":{"type":"object","properties":{"label":{"type":"object","description":"Translated label."},"value":{"type":"object","description":"Translated value."}},"required":["label","value"]},"description":"Extra key/value information from the external API."}},"required":["message","documents","categories","info"],"description":"Pre-order validation data."},"stats":{"type":"object","properties":{"utm":{"type":"object","properties":{"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"}},"description":"UTM tracking parameters present when the order was placed."},"country":{"type":["string","null"],"description":"Country of the buyer at the time of purchase."},"ticketCategories":{"type":"array","items":{"type":"string"},"description":"Ticket categories purchased."},"purchaser":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"jobTitle":{"type":"string"},"companyName":{"type":"string"}},"description":"Purchaser details collected at checkout."}},"required":["utm","ticketCategories","purchaser"],"description":"Statistical information about the order."}},"required":["orgId","purchaseOrderId","ctime","mtime","expiresAt","status","approval","isInvalidated","isTest","accountId","locale","currency","billingAddress","initial","refund","note","attest","stats"],"description":"The purchase order data, or null if not found."}},"required":["success","reason","model"]},"description":"Map from purchase order ID to its result."}},"required":["orgId","orderById"]}}}},"400":{"description":"Bad request (e.g., missing or invalid fields)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Organization not found"}}}}}}
```

## List purchase orders in an organization

> Returns a paginated list of purchase orders for the given organization, sorted by creation time descending.

```json
{"openapi":"3.0.3","info":{"title":"Talque Order API","version":"1.0.0"},"paths":{"/api/v1/purchase/order/list":{"post":{"summary":"List purchase orders in an organization","description":"Returns a paginated list of purchase orders for the given organization, sorted by creation time descending.","parameters":[{"name":"X-TQ-CLIENT-ID","in":"header","required":true,"schema":{"type":"string"},"description":"The API client ID for authentication."},{"name":"X-TQ-SECRET","in":"header","required":true,"schema":{"type":"string"},"description":"The API client secret for authentication."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"limit":{"type":"integer","description":"Maximum number of purchase orders to return (default: 100)."},"cursor":{"type":["string","null"],"description":"Pagination cursor from a previous response."}},"required":["orgId"]}}}},"responses":{"200":{"description":"Purchase orders successfully retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"purchaseOrders":{"type":"array","items":{"type":"object","properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"purchaseOrderId":{"type":"string","description":"The unique identifier of the purchase order."},"ctime":{"type":"integer","description":"Creation time of the purchase order (milliseconds since epoch)."},"mtime":{"type":"integer","description":"Last modification time of the purchase order (milliseconds since epoch)."},"expiresAt":{"type":"integer","description":"Expiration time of the purchase order (milliseconds since epoch)."},"status":{"type":"string","description":"Purchase order lifecycle status."},"approval":{"type":"string","description":"Approval status of the order."},"isInvalidated":{"type":"boolean","description":"Whether the order has been invalidated by an admin."},"isTest":{"type":"boolean","description":"Whether this is a test purchase order."},"accountId":{"type":"string","description":"Account ID of the buyer."},"purchaseEmail":{"type":["string","null"],"description":"Buyer email address at the time of purchase."},"locale":{"type":"string","description":"Locale used when placing the order."},"currency":{"type":"string","description":"ISO currency code for the order."},"invoiceId":{"type":["string","null"],"description":"Most recent invoice ID for the order, if any."},"billingAddress":{"type":"object","properties":{"billingAddressType":{"type":"string","description":"Type of billing address."},"companyName":{"type":["string","null"],"description":"Company name on the billing address."},"personalName":{"type":["string","null"],"description":"Personal name on the billing address."},"costCenter":{"type":["string","null"],"description":"Cost center."},"street":{"type":["string","null"],"description":"Street address."},"zipCode":{"type":["string","null"],"description":"Postal code."},"city":{"type":["string","null"],"description":"City."},"country":{"type":["string","null"],"description":"ISO country code."},"phone":{"type":["string","null"],"description":"Phone number."},"text":{"type":["string","null"],"description":"Free-text address field."},"wantHardcopy":{"type":["boolean","null"],"description":"Whether the buyer requested a printed invoice."}},"required":["billingAddressType"],"description":"Billing address for the order."},"initial":{"type":"object","properties":{"total":{"type":"integer","description":"Total amount in the smallest currency unit (e.g. cents)."},"net":{"type":"integer","description":"Net amount."},"tax":{"type":"integer","description":"Tax amount."},"currency":{"type":"string","description":"ISO currency code."}},"required":["total","net","tax","currency"],"description":"Initial amount paid for the order."},"refund":{"type":"object","properties":{"total":{"type":"integer","description":"Total amount in the smallest currency unit (e.g. cents)."},"net":{"type":"integer","description":"Net amount."},"tax":{"type":"integer","description":"Tax amount."},"currency":{"type":"string","description":"ISO currency code."}},"required":["total","net","tax","currency"],"description":"Accumulated refunded amount."},"lastPaymentError":{"type":["integer","null"],"description":"Timestamp of the last payment error, if any (milliseconds since epoch)."},"paymentErrorMessage":{"type":["string","null"],"description":"User-facing payment error message, if any."},"note":{"type":"string","description":"Admin comments on the order."},"customData":{"description":"Custom field data collected during checkout."},"attest":{"type":"object","properties":{"message":{"type":"string","description":"Optional message from the external validation API."},"extSurveyId":{"type":["string","null"],"description":"External survey identifier, if any."},"documents":{"type":"array","items":{"type":"string"},"description":"IDs of documents uploaded during order submission."},"categories":{"type":"array","items":{"type":"string"},"description":"Additional participant categories."},"info":{"type":"array","items":{"type":"object","properties":{"label":{"type":"object","description":"Translated label."},"value":{"type":"object","description":"Translated value."}},"required":["label","value"]},"description":"Extra key/value information from the external API."}},"required":["message","documents","categories","info"],"description":"Pre-order validation data."},"stats":{"type":"object","properties":{"utm":{"type":"object","properties":{"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"}},"description":"UTM tracking parameters present when the order was placed."},"country":{"type":["string","null"],"description":"Country of the buyer at the time of purchase."},"ticketCategories":{"type":"array","items":{"type":"string"},"description":"Ticket categories purchased."},"purchaser":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"jobTitle":{"type":"string"},"companyName":{"type":"string"}},"description":"Purchaser details collected at checkout."}},"required":["utm","ticketCategories","purchaser"],"description":"Statistical information about the order."}},"required":["orgId","purchaseOrderId","ctime","mtime","expiresAt","status","approval","isInvalidated","isTest","accountId","locale","currency","billingAddress","initial","refund","note","attest","stats"]},"description":"The list of purchase orders, sorted by creation time descending."},"cursor":{"type":["string","null"],"description":"Pagination cursor for the next page, or null if there are no more results."}},"required":["orgId","purchaseOrders","cursor"]}}}},"400":{"description":"Bad request (e.g., missing or invalid orgId)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Organization not found"}}}}}}
```

## Get a signed URL for an attest document

> \
> Since the documents submitted during the accreditation may be sensitive in nature,\
> we never create long-lived serving URLs for those. This API returns a time-limited\
> signed download URL for a single attest document that is only valid for a relatively\
> short period of time.\
> \
> If you need do further process the images you have to download the file. You can\
> assume that the file is immutable, that is, if the document ID did not change then\
> the file also did not change.<br>

```json
{"openapi":"3.0.3","info":{"title":"Talque Order API","version":"1.0.0"},"paths":{"/api/v1/purchase/attest/document":{"post":{"summary":"Get a signed URL for an attest document","description":"\nSince the documents submitted during the accreditation may be sensitive in nature,\nwe never create long-lived serving URLs for those. This API returns a time-limited\nsigned download URL for a single attest document that is only valid for a relatively\nshort period of time.\n\nIf you need do further process the images you have to download the file. You can\nassume that the file is immutable, that is, if the document ID did not change then\nthe file also did not change.\n","parameters":[{"name":"X-TQ-CLIENT-ID","in":"header","required":true,"schema":{"type":"string"},"description":"The API client ID for authentication."},{"name":"X-TQ-SECRET","in":"header","required":true,"schema":{"type":"string"},"description":"The API client secret for authentication."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"purchaseOrderId":{"type":"string","description":"The unique identifier of the purchase order."},"attestDocumentId":{"type":"string","description":"The unique identifier of the attest document."}},"required":["orgId","purchaseOrderId","attestDocumentId"]}}}},"responses":{"200":{"description":"Signed URL generated (null if document is deleted)","content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"The unique identifier of the organization."},"purchaseOrderId":{"type":"string","description":"The unique identifier of the purchase order."},"attestDocumentId":{"type":"string","description":"The unique identifier of the attest document."},"signedUrl":{"type":["string","null"],"description":"Signed GCS URL for downloading the document, or null if the document is deleted."},"expires":{"type":["integer","null"],"description":"Expiration time of the signed URL (milliseconds since epoch), or null."}},"required":["orgId","purchaseOrderId","attestDocumentId","signedUrl","expires"]}}}},"400":{"description":"Bad request (e.g., missing or invalid fields)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Organization, purchase order, or attest document not found"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://talque.gitbook.io/public/json-api/purchase-orders/talque-order-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.