openapi-directory/api/xero.com/xero_files.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","servers":[{"description":"Xero Files API","url":"https://api.xero.com/files.xro/1.0/"}],"info":{"contact":{"email":"api@xero.com","name":"Xero Platform Team","url":"https://developer.xero.com","x-twitter":"XeroAPI"},"description":"These endpoints are specific to Xero Files API","termsOfService":"https://developer.xero.com/xero-developer-platform-terms-conditions/","title":"Xero Files API","version":"2.9.4","x-apisguru-categories":["financial"],"x-origin":[{"format":"openapi","url":"https://raw.githubusercontent.com/XeroAPI/Xero-OpenAPI/master/xero_files.yaml","version":"3.0"}],"x-providerName":"xero.com","x-serviceName":"xero_files"},"tags":[{"description":"Operations available to regular developers","name":"Files"}],"paths":{"/Associations/{ObjectId}":{"get":{"description":"By passing in the appropriate options,","operationId":"getAssociationsByObject","parameters":[{"description":"Object id for single object","in":"path","name":"ObjectId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":"[ { \"FileId\":\"6beccb4a-0d7d-4518-93f3-e0cd1dccb254\", \"ObjectId\":\"1270bf7c-5d18-473a-9231-1e36c4bd33ed\", \"ObjectType\":\"Business\", \"ObjectGroup\":\"Contact\" } ]","schema":{"items":{"$ref":"#/components/schemas/Association"},"type":"array"}}},"description":"search results matching criteria"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves an association object using a unique object ID","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}]},"/Files":{"get":{"operationId":"getFiles","parameters":[{"description":"pass an optional page size value","in":"query","name":"pagesize","schema":{"example":50,"maximum":100,"type":"integer"}},{"description":"number of records to skip for pagination","in":"query","name":"page","schema":{"example":2,"minimum":1,"type":"integer"}},{"description":"values to sort by","in":"query","name":"sort","schema":{"enum":["Name","Size","CreatedDateUTC"],"example":"CreatedDateUTC DESC","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":"{ \"TotalCount\": 100, \"Page\": 1, \"PerPage\": 2, \"Items\": [ { \"Name\": \"helo-heros.jpg\", \"MimeType\": \"application/jpg\", \"Size\": 2878711, \"CreatedDateUtc\": \"2021-02-10T16:02:54.9930000\", \"UpdatedDateUtc\": \"2021-02-10T16:02:54.9930000\", \"User\": { \"Name\": \"sid.maestre@xero.com\", \"FirstName\": \"Sidney\", \"LastName\": \"Maestre\", \"FullName\": \"Sidney Maestre\", \"Id\": \"740add2a-a703-4b8a-a670-1093919c2040\" }, \"FolderId\": \"bf924975-7097-46f2-a143-1ecfbab3c8c3\", \"Id\": \"3d413bfe-f40f-4807-b953-9a42f834ff15\" }, { \"Name\": \"helo-heros.jpg\", \"MimeType\": \"application/jpg\", \"Size\": 2878711, \"CreatedDateUtc\": \"2021-02-09T21:16:00.6130000\", \"UpdatedDateUtc\": \"2021-02-09T21:16:00.6130000\", \"User\": { \"Name\": \"sid.maestre@xero.com\", \"FirstName\": \"Sidney\", \"LastName\": \"Maestre\", \"FullName\": \"Sidney Maestre\", \"Id\": \"740add2a-a703-4b8a-a670-1093919c2040\" }, \"FolderId\": \"bf924975-7097-46f2-a143-1ecfbab3c8c3\", \"Id\": \"22f87409-cdfd-4813-a868-559481bcb052\" } ] }","schema":{"$ref":"#/components/schemas/Files"}}},"description":"search results matching criteria"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves files","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}],"post":{"operationId":"uploadFile","parameters":[{"description":"pass an optional folder id to save file to specific folder","in":"query","name":"FolderId","schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"body":{"format":"byte","type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"name":{"description":"exact name of the file you are uploading","type":"string"}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"example":"{ \"Name\": \"helo-heros.jpg\", \"MimeType\": \"application/jpg\", \"Size\": 2878711, \"CreatedDateUtc\": \"2021-02-10T23:17:50.1930000\", \"UpdatedDateUtc\": \"2021-02-10T23:17:50.1930000\", \"User\": { \"Name\": \"sid.maestre@xero.com\", \"FirstName\": \"Sidney\", \"LastName\": \"Maestre\", \"FullName\": \"Sidney Maestre\", \"Id\": \"740add2a-a703-4b8a-a670-1093919c2040\" }, \"FolderId\": \"bf924975-7097-46f2-a143-1ecfbab3c8c3\", \"Id\": \"22f87409-cdfd-4813-a868-559481bcb052\" }","schema":{"$ref":"#/components/schemas/FileObject"}}},"description":"A successful request"},"400":{"content":{"application/json":{"example":"[ { \"type\":\"Validation\", \"title\":\"Validation failure\", \"detail\":\"Extension: boo is not a valid File extension.\" } ]"}},"description":"invalid input, object invalid"}},"security":[{"OAuth2":["files"]}],"summary":"Uploads a File","tags":["Files"]}},"/Files/{FileId}":{"delete":{"description":"Delete a specific file","operationId":"deleteFile","parameters":[{"description":"File id for single object","in":"path","name":"FileId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"204":{"description":"Successful deletion - return response 204 no content","x-isEmpty":true}},"security":[{"OAuth2":["files"]}],"summary":"Deletes a specific file","tags":["Files"]},"get":{"operationId":"getFile","parameters":[{"description":"File id for single object","in":"path","name":"FileId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":"{ \"Name\": \"helo-heros.jpg\", \"MimeType\": \"application/jpg\", \"Size\": 2878711, \"CreatedDateUtc\": \"2021-02-10T23:17:50.1930000\", \"UpdatedDateUtc\": \"2021-02-10T23:17:50.1930000\", \"User\": { \"Name\": \"sid.maestre@xero.com\", \"FirstName\": \"Sidney\", \"LastName\": \"Maestre\", \"FullName\": \"Sidney Maestre\", \"Id\": \"740add2a-a703-4b8a-a670-1093919c2040\" }, \"FolderId\": \"bf924975-7097-46f2-a143-1ecfbab3c8c3\", \"Id\": \"efd77bfc-7018-4da1-b251-7aa2d438382c\" }","schema":{"$ref":"#/components/schemas/FileObject"}}},"description":"search results matching criteria"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves a file by a unique file ID","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}],"put":{"description":"Updates file properties of a single file","operationId":"updateFile","parameters":[{"description":"File id for single object","in":"path","name":"FileId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"example":"{ \"FolderId\": \"bf924975-7097-46f2-a143-1ecfbab3c8c3\" }","schema":{"$ref":"#/components/schemas/FileObject"}}}},"responses":{"200":{"content":{"application/json":{"example":"{ \"Name\": \"helo-heros.jpg\", \"MimeType\": \"application/jpg\", \"Size\": 2878711, \"CreatedDateUtc\": \"2021-02-10T23:17:50.1930000\", \"UpdatedDateUtc\": \"2021-02-10T23:58:54.1000000\", \"User\": { \"Name\": \"sid.maestre@xero.com\", \"FirstName\": \"Sidney\", \"LastName\": \"Maestre\", \"FullName\": \"Sidney Maestre\", \"Id\": \"740add2a-a703-4b8a-a670-1093919c2040\" }, \"FolderId\": \"bf924975-7097-46f2-a143-1ecfbab3c8c3\", \"Id\": \"efd77bfc-7018-4da1-b251-7aa2d438382c\" }","schema":{"$ref":"#/components/schemas/FileObject"}}},"description":"A successful request"},"400":{"content":{"application/json":{"example":"[ { \"type\":\"Rename\", \"title\":\"Rename failed\", \"detail\":\"Unable to rename efd77bfc-7018-4da1-b251-7aa2d438382c to FooBar\" } ]"}},"description":"invalid input, object invalid"}},"security":[{"OAuth2":["files"]}],"summary":"Update a file","tags":["Files"]}},"/Files/{FileId}/Associations":{"get":{"description":"By passing in the appropriate options, \n","operationId":"getFileAssociations","parameters":[{"description":"File id for single object","in":"path","name":"FileId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":"[ { \"FileId\":\"6beccb4a-0d7d-4518-93f3-e0cd1dccb254\", \"ObjectId\":\"1270bf7c-5d18-473a-9231-1e36c4bd33ed\", \"ObjectType\":\"Business\", \"ObjectGroup\":\"Contact\" } ]","schema":{"items":{"$ref":"#/components/schemas/Association"},"type":"array"}}},"description":"search results matching criteria"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves a specific file associations","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}],"post":{"description":"By passing in the appropriate options, you can create a new folder","operationId":"createFileAssociation","parameters":[{"description":"File id for single object","in":"path","name":"FileId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"example":"{ \"ObjectId\": \"1270bf7c-5d18-473a-9231-1e36c4bd33ed\", \"ObjectGroup\": \"Contact\", \"ObjectType\": \"Business\" }","schema":{"$ref":"#/components/schemas/Association"}}}},"responses":{"201":{"content":{"application/json":{"example":"{ \"FileId\": \"6beccb4a-0d7d-4518-93f3-e0cd1dccb254\", \"ObjectId\": \"1270bf7c-5d18-473a-9231-1e36c4bd33ed\", \"ObjectType\": \"Business\", \"ObjectGroup\": \"Contact\" }","schema":{"$ref":"#/components/schemas/Association"}}},"description":"A successful request"},"400":{"content":{"application/json":{"example":"[ { \"type\":\"Validation\", \"title\":\"Validation failure\", \"detail\":\"Object is not a Account\" } ]"}},"description":"invalid input, object invalid"}},"security":[{"OAuth2":["files"]}],"summary":"Creates a new file association","tags":["Files"]}},"/Files/{FileId}/Associations/{ObjectId}":{"delete":{"description":"By passing in the appropriate options, you can create a new folder","operationId":"deleteFileAssociation","parameters":[{"description":"File id for single object","in":"path","name":"FileId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}},{"description":"Object id for single object","in":"path","name":"ObjectId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"204":{"description":"Successful deletion - return response 204 no content","x-isEmpty":true}},"security":[{"OAuth2":["files"]}],"summary":"Deletes an existing file association","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}]},"/Files/{FileId}/Content":{"get":{"description":"By passing in the appropriate options, retrieve data for specific file","operationId":"getFileContent","parameters":[{"description":"File id for single object","in":"path","name":"FileId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"returns the byte array of the specific file based on id"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves the content of a specific file","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}]},"/Folders":{"get":{"description":"By passing in the appropriate options, you can search for available folders","operationId":"getFolders","parameters":[{"description":"values to sort by","in":"query","name":"sort","schema":{"enum":["Name","Size","CreatedDateUTC"],"example":"CreatedDateUTC DESC","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":"[ { \"Name\":\"Inbox\", \"FileCount\":14, \"Email\":\"xero.inbox.jpf4.6oo29retajkhtfus@xerofiles.com\", \"IsInbox\":true, \"Id\":\"bf924975-7097-46f2-a143-1ecfbab3c8c3\" }, { \"Name\":\"Contracts\", \"FileCount\":7, \"IsInbox\":false, \"Id\":\"554ff1ad-4b94-4266-9b45-e29bcb75e6bf\" } ]","schema":{"items":{"$ref":"#/components/schemas/Folder"},"type":"array"}}},"description":"search results matching criteria"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves folders","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}],"post":{"description":"By passing in the appropriate properties, you can create a new folder","operationId":"createFolder","requestBody":{"content":{"application/json":{"example":"{ \"Name\": \"My Docs\" }","schema":{"$ref":"#/components/schemas/Folder"}}}},"responses":{"200":{"content":{"application/json":{"example":"{ \"Name\": \"My Docs\", \"FileCount\": 0, \"IsInbox\": false, \"Id\": \"913970ad-8c8e-4666-8294-35b9cac23206\" }","schema":{"$ref":"#/components/schemas/Folder"}}},"description":"search results matching criteria"},"400":{"content":{"application/json":{"example":"[ { \"type\":\"Validation\", \"title\":\"Validation failure\", \"detail\":\"Name contains one or more bad characters\" } ]"}},"description":"invalid input, object invalid"}},"security":[{"OAuth2":["files"]}],"summary":"Creates a new folder","tags":["Files"]}},"/Folders/{FolderId}":{"delete":{"description":"By passing in the appropriate ID, you can delete a folder","operationId":"deleteFolder","parameters":[{"description":"Folder id for single object","in":"path","name":"FolderId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"204":{"description":"Successful deletion - return response 204 no content","x-isEmpty":true}},"security":[{"OAuth2":["files"]}],"summary":"Deletes a folder","tags":["Files"]},"get":{"description":"By passing in the appropriate ID, you can search for specific folder","operationId":"getFolder","parameters":[{"description":"Folder id for single object","in":"path","name":"FolderId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":"{ \"Name\": \"My Docs\", \"FileCount\": 0, \"IsInbox\": false, \"Id\": \"4c5f3fe4-2516-4863-ac88-3029351773bf\" }","schema":{"$ref":"#/components/schemas/Folder"}}},"description":"search results matching criteria"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves specific folder by using a unique folder ID","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}],"put":{"description":"By passing in the appropriate ID and properties, you can update a folder","operationId":"updateFolder","parameters":[{"description":"Folder id for single object","in":"path","name":"FolderId","required":true,"schema":{"example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"example":"{ \"Name\": \"Your Docs\" }","schema":{"$ref":"#/components/schemas/Folder"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":"{ \"Name\": \"Your Docs\", \"FileCount\": 0, \"IsInbox\": false, \"Id\": \"4c5f3fe4-2516-4863-ac88-3029351773bf\" }","schema":{"$ref":"#/components/schemas/Folder"}}},"description":"return the updated object"},"400":{"content":{"application/json":{"example":"[ { \"type\":\"Validation\", \"title\":\"Validation failure\", \"detail\":\"Name contains one or more bad characters\" } ]"}},"description":"invalid input, object invalid"}},"security":[{"OAuth2":["files"]}],"summary":"Updates an existing folder","tags":["Files"]}},"/Inbox":{"get":{"description":"Search for the user inbox","operationId":"getInbox","responses":{"200":{"content":{"application/json":{"example":"{ \"Name\": \"Inbox\", \"FileCount\": 14, \"Email\": \"xero.inbox.jpf4.6oo29retajkhtfus@xerofiles.com\", \"IsInbox\": true, \"Id\": \"bf924975-7097-46f2-a143-1ecfbab3c8c3\" }","schema":{"$ref":"#/components/schemas/Folder"}}},"description":"search results matching criteria"}},"security":[{"OAuth2":["files.read"]}],"summary":"Retrieves inbox folder","tags":["Files"]},"parameters":[{"$ref":"#/components/parameters/requiredHeader"}]}},"components":{"parameters":{"requiredHeader":{"description":"Xero identifier for Tenant","example":"YOUR_XERO_TENANT_ID","in":"header","name":"xero-tenant-id","required":true,"schema":{"type":"string"}}},"schemas":{"Association":{"properties":{"FileId":{"description":"The unique identifier of the file","format":"uuid","type":"string"},"ObjectGroup":{"$ref":"#/components/schemas/ObjectGroup"},"ObjectId":{"description":"The identifier of the object that the file is being associated with (e.g. InvoiceID, BankTransactionID, ContactID)","format":"uuid","type":"string"},"ObjectType":{"$ref":"#/components/schemas/ObjectType"}},"type":"object"},"FileObject":{"properties":{"CreatedDateUtc":{"description":"Created date in UTC","example":"2025-04-15T13:51:57.288Z","type":"string"},"FolderId":{"description":"Folder relation object's UUID","example":"0f8ccf21-7267-4268-9167-a1e2c40c84c8","format":"uuid","type":"string"},"Id":{"description":"File object's UUID","example":"d290f1ee-6c54-4b01-90e6-d701748f0851","format":"uuid","type":"string"},"MimeType":{"description":"MimeType of the file (image/png, image/jpeg, application/pdf, etc..)","example":"image/jpeg","type":"string"},"Name":{"description":"File Name","example":"File2.jpg","type":"string"},"Size":{"description":"Numeric value in bytes","example":3615,"type":"integer"},"UpdatedDateUtc":{"description":"Updated date in UTC","example":"2025-04-15T13:51:57.288Z","type":"string"},"User":{"$ref":"#/components/schemas/User"}},"required":["id","name","manufacturer","releaseDate"],"type":"object"},"Files":{"properties":{"Items":{"items":{"$ref":"#/components/schemas/FileObject"},"type":"array"},"Page":{"example":1,"type":"integer"},"PerPage":{"example":50,"type":"integer"},"TotalCount":{"example":2,"type":"integer"}},"type":"object"},"Folder":{"properties":{"Email":{"description":"The email address used to email files to the inbox. Only the inbox will have this element.","example":"foo@bar.com","type":"string"},"FileCount":{"description":"The number of files in the folder","example":5,"type":"integer"},"Id":{"description":"Xero unique identifier for a folder  Files","example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"},"IsInbox":{"description":"to indicate if the folder is the Inbox. The Inbox cannot be renamed or deleted.","example":true,"type":"boolean"},"Name":{"description":"The name of the folder","example":"assets","type":"string"}},"required":["name"]},"Folders":{"properties":{"Folders":{"items":{"$ref":"#/components/schemas/Folder"},"type":"array"}},"type":"object"},"ObjectGroup":{"description":"The Object Group that the object is in. These roughly correlate to the endpoints that can be used to retrieve the object via the core accounting API.","enum":["Account","BankTransaction","Contact","CreditNote","Invoice","Item","ManualJournal","Overpayment","Payment","Prepayment","Receipt"],"type":"string"},"ObjectType":{"description":"The Object Type","enum":["Unknown","Accpay","AccPayCredit","AccPayPayment","AccRec","AccRecCredit","AccRecPayment","Adjustment","ApCreditPayment","ApOverPayment","ApOverPaymentPayment","ApOverPaymentSourcePayment","ApPrepayment","ApPrepaymentPayment","ApPrepaymentSourcePayment","ArCreditPayment","ArOverPayment","ArOverpaymentPayment","ArOverpaymentSourcePayment","ArPrepayment","ArPrepaymentPayment","ArPrepaymentSourcePayment","CashPaid","CashRec","ExpPayment","ManJournal","PurchaseOrder","Receipt","Transfer","Account","Contact","Business","Employee","Person","User","Org","FixedAsset","PayRun","PriceListItem","Bank","Current","Equity","Expense","Fixed","Liability","Prepayment","Revenue","Sales","Overheads","Depreciatn","OtherIncome","DirectCosts","Currliab","Termliab","NonCurrent"],"type":"string"},"User":{"properties":{"FirstName":{"description":"First name of user","example":"John","type":"string"},"FullName":{"description":"Last name of user","example":"Smith","type":"string"},"Id":{"description":"Xero identifier","example":"4ff1e5cc-9835-40d5-bb18-09fdb118db9c","format":"uuid","type":"string"},"LastName":{"description":"Last name of user","example":"Smith","type":"string"},"Name":{"description":"Key is Name, but returns Email address of user who created the file","example":"john.smith@mail.com","type":"string"}},"required":["Id"],"type":"object"}},"securitySchemes":{"OAuth2":{"description":"For more information","flows":{"authorizationCode":{"authorizationUrl":"https://login.xero.com/identity/connect/authorize","scopes":{"email":"Grant read-only access to your email","files":"Grant read-write access to files and folders","files.read":"Grant read-only access to files and folders","openid":"Grant read-only access to your open id","profile":"your profile information"},"tokenUrl":"https://identity.xero.com/connect/token"}},"type":"oauth2"}}}}