> For the complete documentation index, see [llms.txt](https://support.pipefile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.pipefile.com/api-reference/file-requests.md).
# File Requests
A request asks one or more recipients for documents. Its checklist (`contents`) is either a flat list of items or a list of sections that each hold items, never a mix of the two.
Request IDs are UUIDs written as 32 hex characters without dashes.
## List file requests
> Returns the requests you can see, most recently modified first, 25 per\
> page. Drafts are included only when they are yours.
```json
{"openapi":"3.0.3","info":{"title":"Pipefile API","version":"1.0"},"tags":[{"name":"File requests","description":"A request asks one or more recipients for documents. Its checklist\n(`contents`) is either a flat list of items or a list of sections that\neach hold items, never a mix of the two.\n\nRequest IDs are UUIDs written as 32 hex characters without dashes.\n"}],"servers":[{"url":"https://api.pipefile.com/v1","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your API key with the `Token` prefix: `Authorization: Token `."}},"parameters":{"Page":{"name":"page","in":"query","description":"The page to return, starting at 1.","schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"page_size","in":"query","description":"Results per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"schemas":{"FileRequestPage":{"allOf":[{"$ref":"#/components/schemas/PageInfo"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/FileRequestSummary"}}},"required":["results"]}]},"PageInfo":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of results."},"num_pages":{"type":"integer"},"next":{"type":"string","nullable":true,"description":"URL of the next page, or null on the last page."},"previous":{"type":"string","nullable":true,"description":"URL of the previous page, or null on the first page."}},"required":["count","num_pages","next","previous"]},"FileRequestSummary":{"type":"object","properties":{"id":{"type":"string"},"user":{"$ref":"#/components/schemas/UserSummary"},"assigned_to":{"type":"array","items":{"$ref":"#/components/schemas/UserSummary"}},"status":{"$ref":"#/components/schemas/RequestStatus"},"unread":{"type":"boolean"},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"subject":{"type":"string"},"message":{"type":"string"},"checklist_metadata":{"type":"object","nullable":true,"description":"Item counts, or null when the request has no checklist items.","properties":{"responded":{"type":"integer"},"items":{"type":"integer"}}},"is_trash":{"type":"boolean"},"last_modified":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"UserSummary":{"type":"object","description":"A Pipefile user.","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"RequestStatus":{"type":"string","description":"`draft` not yet sent. `sent` waiting on the recipient. `responded` every\nchecklist item has a response. `completed` closed by your team.\n`archived` archived. `expired` the expiration date passed before the\nrecipient responded.\n","enum":["draft","sent","responded","completed","archived","expired"]},"Recipient":{"allOf":[{"$ref":"#/components/schemas/Contact"},{"type":"object","properties":{"client_link":{"type":"string","format":"uri","description":"This recipient's personal link to the request."}}}]},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"The contact ID (32 hex characters)."},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","description":"Phone number in international format, or an empty string."},"email_bounced":{"type":"boolean","description":"Email to this address bounced."},"email_complained":{"type":"boolean","description":"The recipient marked an email from Pipefile as spam."},"phone_unreachable":{"type":"boolean","description":"Text messages to this number could not be delivered."}},"required":["id","name","email","phone","email_bounced","email_complained","phone_unreachable"]},"ValidationErrors":{"type":"object","additionalProperties":true,"description":"Field name to a list of error messages. Nested fields (such as checklist items) return nested objects or lists in the same shape."},"Error":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}},"responses":{"ValidationError":{"description":"The request body or a query parameter is not valid. Each key is a field name (or `non_field_errors`) with a list of messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrors"}}}},"Forbidden":{"description":"The API key is missing, invalid or revoked, the account is not active, or you don't have access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Nothing with that ID, or that page, exists for you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Throttled":{"description":"Too many calls. Wait the number of seconds in the message, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/file/requests/":{"get":{"tags":["File requests"],"operationId":"listFileRequests","summary":"List file requests","description":"Returns the requests you can see, most recently modified first, 25 per\npage. Drafts are included only when they are yours.\n","parameters":[{"name":"search","in":"query","description":"Matches recipient name, email and phone, tag names, the sender's name and email, and the subject.","schema":{"type":"string"}},{"name":"status","in":"query","description":"One status, or several separated by commas. Omit it, or pass `all`,\nfor every status.\n","schema":{"type":"string"}},{"name":"my_requests","in":"query","description":"When `true`, only requests you created or that are assigned to you.","schema":{"type":"boolean","default":false}},{"name":"unread","in":"query","description":"When `true`, only requests with unread activity.","schema":{"type":"boolean","default":false}},{"name":"tags","in":"query","description":"Comma-separated tag names. Returns requests with any of them.","schema":{"type":"string"}},{"name":"trash","in":"query","description":"When `true`, returns requests in the trash instead of live ones.","schema":{"type":"boolean","default":false}},{"name":"start_date","in":"query","description":"Only requests created at or after this time (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"end_date","in":"query","description":"Only requests created at or before this time (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"One page of requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileRequestPage"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/Throttled"}}}}}}
```
## Create a file request
> Creates a request with the checklist you supply and sends it to the\
> recipients straight away.\
> \
> The body must include \`file\_pipe.key\`, the ID of the encryption key that\
> protects uploaded files. To find your key's ID, read \`file\_pipe.key.id\`\
> from any request you already have (\`GET /file/request/{request\_id}/detail/\`).\
> If you don't need a custom checklist, \`POST /file/request/create\_from\_template/\`\
> needs no key ID.\
> \
> On the Free plan you can have one open request at a time. A call that\
> would go over that limit returns \`402\`.
```json
{"openapi":"3.0.3","info":{"title":"Pipefile API","version":"1.0"},"tags":[{"name":"File requests","description":"A request asks one or more recipients for documents. Its checklist\n(`contents`) is either a flat list of items or a list of sections that\neach hold items, never a mix of the two.\n\nRequest IDs are UUIDs written as 32 hex characters without dashes.\n"}],"servers":[{"url":"https://api.pipefile.com/v1","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your API key with the `Token` prefix: `Authorization: Token `."}},"schemas":{"FileRequestCreate":{"type":"object","properties":{"recipients":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/RecipientInput"}},"subject":{"type":"string","maxLength":255},"message":{"type":"string"},"file_pipe":{"type":"object","description":"Where uploads are stored and which key encrypts them.","properties":{"key":{"type":"integer","description":"The ID of one of your encryption keys. Read it from `file_pipe.key.id` on an existing request."}},"required":["key"]},"attachments":{"type":"array","description":"Files attached to the whole request. Required; send an empty array for none.","items":{"$ref":"#/components/schemas/AttachmentRef"}},"contents":{"type":"array","description":"The checklist. Use all items or all sections, not both.","items":{"oneOf":[{"$ref":"#/components/schemas/ChecklistItemInput"},{"$ref":"#/components/schemas/ChecklistSectionInput"}]}},"tags":{"type":"array","description":"Required; send an empty array for no tags.","items":{"type":"string"}},"language":{"type":"string","enum":["en","es","fr","pt","ru","zh"],"default":"en","description":"The language the recipient sees the request in."},"reminder_frequency":{"type":"integer","minimum":0,"default":0,"description":"Days between automatic reminders. `0` turns them off."},"notification_sequence":{"type":"integer","nullable":true,"description":"The ID of one of your notification sequences."},"expiration_date":{"type":"string","format":"date-time","description":"When the request link expires."}},"required":["recipients","file_pipe","attachments","tags","expiration_date"]},"RecipientInput":{"type":"object","description":"Either an existing contact, by `id`, or a new recipient by `name` plus\n`email` and/or `phone`. A new recipient is added to your contacts, or\nmatched to an existing contact with the same name, email and phone.\n","properties":{"id":{"type":"string","description":"An existing contact's ID."},"name":{"type":"string","maxLength":255},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"AttachmentRef":{"type":"object","properties":{"attachment_id":{"type":"string"}},"required":["attachment_id"]},"ChecklistItemInput":{"type":"object","properties":{"type":{"type":"string","enum":["item"],"description":"Required at the top level of `contents`. Omit it for items inside a section."},"name":{"type":"string","maxLength":100},"instructions":{"type":"string"},"required":{"type":"boolean","default":false},"file_types":{"type":"array","items":{"type":"string","maxLength":10},"description":"Allowed file extensions without the dot, such as `pdf`. Leave empty to accept any type."},"attachments":{"type":"array","description":"Required. Send an empty array when the item has no attachments.","items":{"$ref":"#/components/schemas/AttachmentRef"}}},"required":["attachments"]},"ChecklistSectionInput":{"type":"object","properties":{"type":{"type":"string","enum":["section"]},"title":{"type":"string","description":"Defaults to \"Section N\" when blank."},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistItemInput"}}},"required":["type","items"]},"FileRequestDetail":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"message":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"contents":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistEntry"}},"tags":{"type":"array","items":{"type":"string"}},"language":{"type":"string","enum":["en","es","fr","pt","ru","zh"]},"reminder_frequency":{"type":"integer"},"notification_sequence":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"file_pipe":{"$ref":"#/components/schemas/FilePipe"},"user":{"$ref":"#/components/schemas/UserSummary"},"assigned_to":{"type":"array","items":{"$ref":"#/components/schemas/UserSummary"}},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"unsubscribed_recipients":{"type":"array","description":"Recipients who unsubscribed from this request's emails.","items":{"$ref":"#/components/schemas/Contact"}},"unread":{"type":"boolean"},"num_comments":{"type":"integer"},"num_unread_comments":{"type":"integer"},"status":{"$ref":"#/components/schemas/RequestStatus"},"is_active":{"type":"boolean"},"is_trash":{"type":"boolean"},"tracking_events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"}},"reminder_last_sent":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time"},"last_modified":{"type":"string","format":"date-time"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"storage_integration":{"type":"object","nullable":true,"description":"The cloud storage connection files export to, if set."},"destination_path":{"type":"string","nullable":true},"destination_folder_parents":{"type":"array","nullable":true,"items":{"type":"string"}},"destination_folder_id":{"type":"string","nullable":true},"destination_context":{"type":"object","nullable":true},"destination_display_path":{"type":"string","nullable":true},"destination_link":{"type":"string","nullable":true,"description":"Link to the export folder, when there is one."},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}}},"additionalProperties":true},"Attachment":{"type":"object","description":"A file you attached for the recipient to see.","properties":{"attachment_id":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer","description":"Size in bytes."},"form":{"type":"object","nullable":true,"description":"The fillable form built on this attachment, if any."},"can_create_form":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"ChecklistEntry":{"oneOf":[{"$ref":"#/components/schemas/ChecklistItem"},{"$ref":"#/components/schemas/ChecklistSection"}],"discriminator":{"propertyName":"type","mapping":{"item":"#/components/schemas/ChecklistItem","section":"#/components/schemas/ChecklistSection"}}},"ChecklistItem":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["item"]},"name":{"type":"string"},"instructions":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"status":{"type":"string","enum":["incomplete","pending_review","approved","rejected","marked_not_applicable"],"description":"`incomplete` nothing submitted yet, or a review marked it incomplete.\n`pending_review` the recipient responded and it awaits review.\n`approved` / `rejected` the review result. `marked_not_applicable`\nthe recipient marked it as not applicable.\n"},"required":{"type":"boolean"},"file_types":{"type":"array","items":{"type":"string"},"description":"Allowed file extensions, without the dot. Empty means any type."},"not_applicable":{"type":"boolean"},"responded":{"type":"boolean"},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/ItemReview"}},"num_files":{"type":"integer"},"num_comments":{"type":"integer"},"num_unread_comments":{"type":"integer"},"editable":{"type":"boolean"},"list_index":{"type":"integer"}}},"ItemReview":{"type":"object","properties":{"status":{"type":"string","enum":["approved","rejected","incomplete"]},"user":{"$ref":"#/components/schemas/UserSummary"},"message":{"type":"string"},"resolved":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"UserSummary":{"type":"object","description":"A Pipefile user.","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"ChecklistSection":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["section"]},"title":{"type":"string"},"description":{"type":"string"},"list_index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistItem"}}}},"FilePipe":{"type":"object","description":"Where the request's uploads are stored, and the key that encrypts them.","properties":{"id":{"type":"string"},"key":{"$ref":"#/components/schemas/PGPKey"},"enabled":{"type":"boolean"},"num_files":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"PGPKey":{"type":"object","properties":{"id":{"type":"integer"},"fingerprint":{"type":"string"},"public_key":{"type":"string"},"managed":{"type":"boolean","description":"True when Pipefile manages the key for you."},"primary":{"type":"boolean"},"active":{"type":"boolean"}}},"Recipient":{"allOf":[{"$ref":"#/components/schemas/Contact"},{"type":"object","properties":{"client_link":{"type":"string","format":"uri","description":"This recipient's personal link to the request."}}}]},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"The contact ID (32 hex characters)."},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","description":"Phone number in international format, or an empty string."},"email_bounced":{"type":"boolean","description":"Email to this address bounced."},"email_complained":{"type":"boolean","description":"The recipient marked an email from Pipefile as spam."},"phone_unreachable":{"type":"boolean","description":"Text messages to this number could not be delivered."}},"required":["id","name","email","phone","email_bounced","email_complained","phone_unreachable"]},"RequestStatus":{"type":"string","description":"`draft` not yet sent. `sent` waiting on the recipient. `responded` every\nchecklist item has a response. `completed` closed by your team.\n`archived` archived. `expired` the expiration date passed before the\nrecipient responded.\n","enum":["draft","sent","responded","completed","archived","expired"]},"TrackingEvent":{"type":"object","description":"One time the request link was opened.","properties":{"id":{"type":"integer"},"contact":{"allOf":[{"$ref":"#/components/schemas/Contact"}],"nullable":true},"ip_address":{"type":"string"},"viewed_ts":{"type":"string","format":"date-time"}}},"Role":{"type":"object","description":"A signer role on the request.","properties":{"role_key":{"type":"string"},"label":{"type":"string"},"order_index":{"type":"integer"},"color":{"type":"string"},"coupled_field_count":{"type":"integer"},"standard_field_count":{"type":"integer"},"has_signed_fields":{"type":"boolean"},"signers":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}}}}}},"ValidationErrors":{"type":"object","additionalProperties":true,"description":"Field name to a list of error messages. Nested fields (such as checklist items) return nested objects or lists in the same shape."},"Error":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}},"responses":{"ValidationError":{"description":"The request body or a query parameter is not valid. Each key is a field name (or `non_field_errors`) with a list of messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrors"}}}},"RequestLimit":{"description":"Your plan's open-request limit is reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid or revoked, the account is not active, or you don't have access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Throttled":{"description":"Too many calls. Wait the number of seconds in the message, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/file/request/":{"post":{"tags":["File requests"],"operationId":"createFileRequest","summary":"Create a file request","description":"Creates a request with the checklist you supply and sends it to the\nrecipients straight away.\n\nThe body must include `file_pipe.key`, the ID of the encryption key that\nprotects uploaded files. To find your key's ID, read `file_pipe.key.id`\nfrom any request you already have (`GET /file/request/{request_id}/detail/`).\nIf you don't need a custom checklist, `POST /file/request/create_from_template/`\nneeds no key ID.\n\nOn the Free plan you can have one open request at a time. A call that\nwould go over that limit returns `402`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileRequestCreate"}}}},"responses":{"201":{"description":"The request was created and sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileRequestDetail"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"402":{"$ref":"#/components/responses/RequestLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/Throttled"}}}}}}
```
## Create a file request from a template
> Creates a request from one of your templates and sends it. The checklist,\
> subject, message, reminders, expiration and export settings all come\
> from the template.\
> \
> For one recipient, pass \`name\` and \`email\` (and optionally \`phone\`). For\
> a template with signer roles, pass \`signers\` instead, one entry per role.\
> \
> \*\*Sending as a teammate.\*\* Add the \`X-Pipefile-On-Behalf-Of\` header with a\
> team member's Pipefile email address and the request is created as\
> theirs: they own it and the recipient hears from them. Your API key must\
> belong to a team admin, and the member must be active on that team.\
> This is the only endpoint that accepts the header; any other endpoint\
> returns \`400\` if you send it.\
> \
> On the Free plan you can have one open request at a time. A call that\
> would go over that limit returns \`402\`.
```json
{"openapi":"3.0.3","info":{"title":"Pipefile API","version":"1.0"},"tags":[{"name":"File requests","description":"A request asks one or more recipients for documents. Its checklist\n(`contents`) is either a flat list of items or a list of sections that\neach hold items, never a mix of the two.\n\nRequest IDs are UUIDs written as 32 hex characters without dashes.\n"}],"servers":[{"url":"https://api.pipefile.com/v1","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your API key with the `Token` prefix: `Authorization: Token `."}},"schemas":{"FileRequestFromTemplateCreate":{"type":"object","properties":{"template":{"type":"string","description":"The template `id`."},"name":{"type":"string","description":"Recipient name. Required unless you send `signers`."},"email":{"type":"string","format":"email","description":"Recipient email. Required unless you send `signers`."},"phone":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags for the new request."},"signers":{"type":"array","items":{"$ref":"#/components/schemas/SignerInput"}},"roles":{"type":"array","description":"Signer roles, used only when the template defines none. Each needs a unique `role_key`.","items":{"type":"object","properties":{"role_key":{"type":"string"},"label":{"type":"string"}},"required":["role_key"]}}},"required":["template"]},"SignerInput":{"type":"object","description":"One signer for a template role. Give an existing contact (`uuid` or `contact_uuid`) or a `name` plus `email`.","properties":{"role_key":{"type":"string","description":"A `role_key` from the template's `template_data.roles`."},"uuid":{"type":"string"},"contact_uuid":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}},"required":["role_key"]},"FileRequestDetail":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"message":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"contents":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistEntry"}},"tags":{"type":"array","items":{"type":"string"}},"language":{"type":"string","enum":["en","es","fr","pt","ru","zh"]},"reminder_frequency":{"type":"integer"},"notification_sequence":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"file_pipe":{"$ref":"#/components/schemas/FilePipe"},"user":{"$ref":"#/components/schemas/UserSummary"},"assigned_to":{"type":"array","items":{"$ref":"#/components/schemas/UserSummary"}},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"unsubscribed_recipients":{"type":"array","description":"Recipients who unsubscribed from this request's emails.","items":{"$ref":"#/components/schemas/Contact"}},"unread":{"type":"boolean"},"num_comments":{"type":"integer"},"num_unread_comments":{"type":"integer"},"status":{"$ref":"#/components/schemas/RequestStatus"},"is_active":{"type":"boolean"},"is_trash":{"type":"boolean"},"tracking_events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"}},"reminder_last_sent":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time"},"last_modified":{"type":"string","format":"date-time"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"storage_integration":{"type":"object","nullable":true,"description":"The cloud storage connection files export to, if set."},"destination_path":{"type":"string","nullable":true},"destination_folder_parents":{"type":"array","nullable":true,"items":{"type":"string"}},"destination_folder_id":{"type":"string","nullable":true},"destination_context":{"type":"object","nullable":true},"destination_display_path":{"type":"string","nullable":true},"destination_link":{"type":"string","nullable":true,"description":"Link to the export folder, when there is one."},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}}},"additionalProperties":true},"Attachment":{"type":"object","description":"A file you attached for the recipient to see.","properties":{"attachment_id":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer","description":"Size in bytes."},"form":{"type":"object","nullable":true,"description":"The fillable form built on this attachment, if any."},"can_create_form":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"ChecklistEntry":{"oneOf":[{"$ref":"#/components/schemas/ChecklistItem"},{"$ref":"#/components/schemas/ChecklistSection"}],"discriminator":{"propertyName":"type","mapping":{"item":"#/components/schemas/ChecklistItem","section":"#/components/schemas/ChecklistSection"}}},"ChecklistItem":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["item"]},"name":{"type":"string"},"instructions":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"status":{"type":"string","enum":["incomplete","pending_review","approved","rejected","marked_not_applicable"],"description":"`incomplete` nothing submitted yet, or a review marked it incomplete.\n`pending_review` the recipient responded and it awaits review.\n`approved` / `rejected` the review result. `marked_not_applicable`\nthe recipient marked it as not applicable.\n"},"required":{"type":"boolean"},"file_types":{"type":"array","items":{"type":"string"},"description":"Allowed file extensions, without the dot. Empty means any type."},"not_applicable":{"type":"boolean"},"responded":{"type":"boolean"},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/ItemReview"}},"num_files":{"type":"integer"},"num_comments":{"type":"integer"},"num_unread_comments":{"type":"integer"},"editable":{"type":"boolean"},"list_index":{"type":"integer"}}},"ItemReview":{"type":"object","properties":{"status":{"type":"string","enum":["approved","rejected","incomplete"]},"user":{"$ref":"#/components/schemas/UserSummary"},"message":{"type":"string"},"resolved":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"UserSummary":{"type":"object","description":"A Pipefile user.","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"ChecklistSection":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["section"]},"title":{"type":"string"},"description":{"type":"string"},"list_index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistItem"}}}},"FilePipe":{"type":"object","description":"Where the request's uploads are stored, and the key that encrypts them.","properties":{"id":{"type":"string"},"key":{"$ref":"#/components/schemas/PGPKey"},"enabled":{"type":"boolean"},"num_files":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"PGPKey":{"type":"object","properties":{"id":{"type":"integer"},"fingerprint":{"type":"string"},"public_key":{"type":"string"},"managed":{"type":"boolean","description":"True when Pipefile manages the key for you."},"primary":{"type":"boolean"},"active":{"type":"boolean"}}},"Recipient":{"allOf":[{"$ref":"#/components/schemas/Contact"},{"type":"object","properties":{"client_link":{"type":"string","format":"uri","description":"This recipient's personal link to the request."}}}]},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"The contact ID (32 hex characters)."},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","description":"Phone number in international format, or an empty string."},"email_bounced":{"type":"boolean","description":"Email to this address bounced."},"email_complained":{"type":"boolean","description":"The recipient marked an email from Pipefile as spam."},"phone_unreachable":{"type":"boolean","description":"Text messages to this number could not be delivered."}},"required":["id","name","email","phone","email_bounced","email_complained","phone_unreachable"]},"RequestStatus":{"type":"string","description":"`draft` not yet sent. `sent` waiting on the recipient. `responded` every\nchecklist item has a response. `completed` closed by your team.\n`archived` archived. `expired` the expiration date passed before the\nrecipient responded.\n","enum":["draft","sent","responded","completed","archived","expired"]},"TrackingEvent":{"type":"object","description":"One time the request link was opened.","properties":{"id":{"type":"integer"},"contact":{"allOf":[{"$ref":"#/components/schemas/Contact"}],"nullable":true},"ip_address":{"type":"string"},"viewed_ts":{"type":"string","format":"date-time"}}},"Role":{"type":"object","description":"A signer role on the request.","properties":{"role_key":{"type":"string"},"label":{"type":"string"},"order_index":{"type":"integer"},"color":{"type":"string"},"coupled_field_count":{"type":"integer"},"standard_field_count":{"type":"integer"},"has_signed_fields":{"type":"boolean"},"signers":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}}}}}},"ValidationErrors":{"type":"object","additionalProperties":true,"description":"Field name to a list of error messages. Nested fields (such as checklist items) return nested objects or lists in the same shape."},"Error":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}},"responses":{"ValidationError":{"description":"The request body or a query parameter is not valid. Each key is a field name (or `non_field_errors`) with a list of messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrors"}}}},"RequestLimit":{"description":"Your plan's open-request limit is reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid or revoked, the account is not active, or you don't have access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Throttled":{"description":"Too many calls. Wait the number of seconds in the message, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/file/request/create_from_template/":{"post":{"tags":["File requests"],"operationId":"createFileRequestFromTemplate","summary":"Create a file request from a template","description":"Creates a request from one of your templates and sends it. The checklist,\nsubject, message, reminders, expiration and export settings all come\nfrom the template.\n\nFor one recipient, pass `name` and `email` (and optionally `phone`). For\na template with signer roles, pass `signers` instead, one entry per role.\n\n**Sending as a teammate.** Add the `X-Pipefile-On-Behalf-Of` header with a\nteam member's Pipefile email address and the request is created as\ntheirs: they own it and the recipient hears from them. Your API key must\nbelong to a team admin, and the member must be active on that team.\nThis is the only endpoint that accepts the header; any other endpoint\nreturns `400` if you send it.\n\nOn the Free plan you can have one open request at a time. A call that\nwould go over that limit returns `402`.\n","parameters":[{"name":"X-Pipefile-On-Behalf-Of","in":"header","required":false,"description":"The email address of the team member to send as. Omit the header when you are not sending as someone else; an empty value returns `400`.","schema":{"type":"string","format":"email"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileRequestFromTemplateCreate"}}}},"responses":{"201":{"description":"The request was created and sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileRequestDetail"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"402":{"$ref":"#/components/responses/RequestLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No Pipefile user matches the address in `X-Pipefile-On-Behalf-Of`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/Throttled"}}}}}}
```
## Get a file request
> Returns one request with its full checklist, recipients, review results and open history.
```json
{"openapi":"3.0.3","info":{"title":"Pipefile API","version":"1.0"},"tags":[{"name":"File requests","description":"A request asks one or more recipients for documents. Its checklist\n(`contents`) is either a flat list of items or a list of sections that\neach hold items, never a mix of the two.\n\nRequest IDs are UUIDs written as 32 hex characters without dashes.\n"}],"servers":[{"url":"https://api.pipefile.com/v1","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your API key with the `Token` prefix: `Authorization: Token `."}},"schemas":{"FileRequestDetail":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"message":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"contents":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistEntry"}},"tags":{"type":"array","items":{"type":"string"}},"language":{"type":"string","enum":["en","es","fr","pt","ru","zh"]},"reminder_frequency":{"type":"integer"},"notification_sequence":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"file_pipe":{"$ref":"#/components/schemas/FilePipe"},"user":{"$ref":"#/components/schemas/UserSummary"},"assigned_to":{"type":"array","items":{"$ref":"#/components/schemas/UserSummary"}},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"unsubscribed_recipients":{"type":"array","description":"Recipients who unsubscribed from this request's emails.","items":{"$ref":"#/components/schemas/Contact"}},"unread":{"type":"boolean"},"num_comments":{"type":"integer"},"num_unread_comments":{"type":"integer"},"status":{"$ref":"#/components/schemas/RequestStatus"},"is_active":{"type":"boolean"},"is_trash":{"type":"boolean"},"tracking_events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"}},"reminder_last_sent":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time"},"last_modified":{"type":"string","format":"date-time"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"storage_integration":{"type":"object","nullable":true,"description":"The cloud storage connection files export to, if set."},"destination_path":{"type":"string","nullable":true},"destination_folder_parents":{"type":"array","nullable":true,"items":{"type":"string"}},"destination_folder_id":{"type":"string","nullable":true},"destination_context":{"type":"object","nullable":true},"destination_display_path":{"type":"string","nullable":true},"destination_link":{"type":"string","nullable":true,"description":"Link to the export folder, when there is one."},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}}},"additionalProperties":true},"Attachment":{"type":"object","description":"A file you attached for the recipient to see.","properties":{"attachment_id":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer","description":"Size in bytes."},"form":{"type":"object","nullable":true,"description":"The fillable form built on this attachment, if any."},"can_create_form":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"ChecklistEntry":{"oneOf":[{"$ref":"#/components/schemas/ChecklistItem"},{"$ref":"#/components/schemas/ChecklistSection"}],"discriminator":{"propertyName":"type","mapping":{"item":"#/components/schemas/ChecklistItem","section":"#/components/schemas/ChecklistSection"}}},"ChecklistItem":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["item"]},"name":{"type":"string"},"instructions":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"status":{"type":"string","enum":["incomplete","pending_review","approved","rejected","marked_not_applicable"],"description":"`incomplete` nothing submitted yet, or a review marked it incomplete.\n`pending_review` the recipient responded and it awaits review.\n`approved` / `rejected` the review result. `marked_not_applicable`\nthe recipient marked it as not applicable.\n"},"required":{"type":"boolean"},"file_types":{"type":"array","items":{"type":"string"},"description":"Allowed file extensions, without the dot. Empty means any type."},"not_applicable":{"type":"boolean"},"responded":{"type":"boolean"},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/ItemReview"}},"num_files":{"type":"integer"},"num_comments":{"type":"integer"},"num_unread_comments":{"type":"integer"},"editable":{"type":"boolean"},"list_index":{"type":"integer"}}},"ItemReview":{"type":"object","properties":{"status":{"type":"string","enum":["approved","rejected","incomplete"]},"user":{"$ref":"#/components/schemas/UserSummary"},"message":{"type":"string"},"resolved":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"UserSummary":{"type":"object","description":"A Pipefile user.","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"ChecklistSection":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["section"]},"title":{"type":"string"},"description":{"type":"string"},"list_index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistItem"}}}},"FilePipe":{"type":"object","description":"Where the request's uploads are stored, and the key that encrypts them.","properties":{"id":{"type":"string"},"key":{"$ref":"#/components/schemas/PGPKey"},"enabled":{"type":"boolean"},"num_files":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"PGPKey":{"type":"object","properties":{"id":{"type":"integer"},"fingerprint":{"type":"string"},"public_key":{"type":"string"},"managed":{"type":"boolean","description":"True when Pipefile manages the key for you."},"primary":{"type":"boolean"},"active":{"type":"boolean"}}},"Recipient":{"allOf":[{"$ref":"#/components/schemas/Contact"},{"type":"object","properties":{"client_link":{"type":"string","format":"uri","description":"This recipient's personal link to the request."}}}]},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"The contact ID (32 hex characters)."},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","description":"Phone number in international format, or an empty string."},"email_bounced":{"type":"boolean","description":"Email to this address bounced."},"email_complained":{"type":"boolean","description":"The recipient marked an email from Pipefile as spam."},"phone_unreachable":{"type":"boolean","description":"Text messages to this number could not be delivered."}},"required":["id","name","email","phone","email_bounced","email_complained","phone_unreachable"]},"RequestStatus":{"type":"string","description":"`draft` not yet sent. `sent` waiting on the recipient. `responded` every\nchecklist item has a response. `completed` closed by your team.\n`archived` archived. `expired` the expiration date passed before the\nrecipient responded.\n","enum":["draft","sent","responded","completed","archived","expired"]},"TrackingEvent":{"type":"object","description":"One time the request link was opened.","properties":{"id":{"type":"integer"},"contact":{"allOf":[{"$ref":"#/components/schemas/Contact"}],"nullable":true},"ip_address":{"type":"string"},"viewed_ts":{"type":"string","format":"date-time"}}},"Role":{"type":"object","description":"A signer role on the request.","properties":{"role_key":{"type":"string"},"label":{"type":"string"},"order_index":{"type":"integer"},"color":{"type":"string"},"coupled_field_count":{"type":"integer"},"standard_field_count":{"type":"integer"},"has_signed_fields":{"type":"boolean"},"signers":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}}}}}},"Error":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}},"responses":{"NotFound":{"description":"Nothing with that ID, or that page, exists for you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Throttled":{"description":"Too many calls. Wait the number of seconds in the message, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/file/request/{request_id}/detail/":{"get":{"tags":["File requests"],"operationId":"getFileRequest","summary":"Get a file request","description":"Returns one request with its full checklist, recipients, review results and open history.","parameters":[{"name":"request_id","in":"path","required":true,"description":"The request's `id`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileRequestDetail"}}}},"403":{"description":"The request exists but you don't have access to it, or the API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/Throttled"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://support.pipefile.com/api-reference/file-requests.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.