{"openapi":"3.1.0","info":{"title":"Files","description":"Automate payments across banks with a single API","version":"1","contact":{"name":"API Support","email":"dev@numeral.io"}},"tags":[{"name":"Files","description":"Files endpoints"}],"servers":[{"url":"https://sandbox.numeral.io/v1"}],"components":{"securitySchemes":{"sec0":{"type":"apiKey","in":"header","name":"x-api-key"}},"responses":{"errors.400.validation":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"errors.404.not_found":{"description":"The specified resource was not found."}},"schemas":{"error":{"type":"object","properties":{"error":{"type":"string","example":"validation_error"},"message":{"type":"string","example":"validation errors occurred while processing request"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"reason":{"type":"string"}}}},"correlation_id":{"type":"string","format":"uuid"}}},"file.category":{"type":"string","enum":["bank_file","payment_file","report_file","return_request_file","return_file","account_report","account_statement","account_notification","inquiry_category","denied_inquiry_file","denied_return_request_file","error_file_format","unknown_file_format","forwarded_message"],"description":"The category of the file."},"file.direction":{"type":"string","enum":["incoming","outgoing"],"description":"The direction of the file."},"file.format":{"type":"string","enum":["pain.001","pain.002","pain.008","pacs.002","pacs.003","pacs.004","pacs.007","pacs.008","pacs.028","camt.027","camt.029","camt.052","camt.053","camt.054","camt.056","camt.087","mt.950","head.002","error.format","unknown.format","multiple.formats","custom.format"],"description":"The format of the file."},"file.connected_account_ids":{"type":"array","items":{"type":"string","example":"6669205e-e306-4b44-bf40-0475899eeb60"},"description":"The IDs of the connected accounts used to send or receive the file."},"file.connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account used to send or receive the file.","deprecated":true},"file.status":{"type":"string","enum":["created","approved","canceled","sent","rejected","processed","received"],"description":"The status of the file. See [file's lifecycle](ref:file-lifecycle)."},"file.details":{"type":"object","description":"A file is received from or sent to a bank. A file can be a payment file, a payment status report, an account statement, etc.","required":["id","object","connected_account_id","connected_account_ids","direction","category","format","filename","size","summary","status","bank_data","status_details","created_at"],"properties":{"id":{"type":"string","description":"The UUID of the file.","example":"3ad331b9-12b2-48fd-ad35-203fe8b5e78e"},"object":{"type":"string","enum":["file"],"description":"Label used to identify this kind of object.","example":"file"},"connected_account_id":{"$ref":"#/components/schemas/file.connected_account_id","deprecated":true},"connected_account_ids":{"$ref":"#/components/schemas/file.connected_account_ids"},"direction":{"type":"string","enum":["outgoing","incoming"],"description":"The transfer direction for the file_id: - `outgoing` for files sent or to be sent to the bank - `incoming` for files received from the bank\n","example":"outgoing"},"category":{"$ref":"#/components/schemas/file.category"},"format":{"type":"string","description":"The format of the file.","example":"pain.001"},"filename":{"type":"string","description":"The name of the file.","example":"SFPP30X40.3ad331b9-12b2-48fd-ad35-203fe8b5e78e.1659349967"},"size":{"type":"integer","minimum":0,"description":"The size of the file, expressed in bytes.","example":2234},"summary":{"type":"object","properties":{},"description":"A summary of the file, depending on its content."},"status":{"$ref":"#/components/schemas/file.status"},"bank_data":{"type":"object","required":["message_ids"],"properties":{"message_ids":{"type":"array","items":{"type":"string","example":"211012231391882"}}},"description":"Bank data, such as message ID, in JSON `key:value` format."},"status_details":{"type":"string","description":"The details of the status of this file, such as the rejection reason for instance.","example":"generated on 2022-08-01"},"created_at":{"type":"string","format":"date-time","description":"The UTC timestamp of the creation of the file.","example":"2022-08-01T06:00:05Z"}}}},"parameters":{"file.id":{"name":"id","in":"path","description":"The UUID of the file.","schema":{"type":"string","format":"uuid"},"required":true},"files.search_parameters.limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":0,"maximum":100,"default":25}},"files.search_parameters.starting_after":{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string","format":"uuid"}},"files.search_parameters.start_date":{"name":"start_date","in":"query","schema":{"type":"string","format":"date"},"description":"The creation date of the file."},"files.search_parameters.end_date":{"name":"end_date","in":"query","schema":{"type":"string","format":"date"},"description":"The creation date of the file."},"list.common_parameters.sort_order":{"name":"sort_order","in":"query","description":"Order is based on attribute `created_at`. If `asc`, results are fetched in chronological order. If `desc`, results are fetched in reversed chronological order. Default order is `desc`.\n","schema":{"type":"string","enum":["asc","desc"]}}}},"security":[{"sec0":[]}],"paths":{"/files/{id}/approve":{"post":{"summary":"Approve file","description":"Approve a file in status `created`. Approving a file updates its status to `approved`. Only files in status `approved` are sent to the bank.","operationId":"approve-file","tags":["Files"],"parameters":[{"$ref":"#/components/parameters/file.id"}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/file.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/files/{id}/cancel":{"post":{"summary":"Cancel file","description":"Cancel a file in status `created`. Canceling a file updates its status to `canceled`. The payment orders, returns, or return requests included in the file are updated to their previous status.","operationId":"cancel-file","tags":["Files"],"parameters":[{"$ref":"#/components/parameters/file.id"}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/file.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/files":{"get":{"summary":"List files","description":"List and filter files.","operationId":"list-files","tags":["Files"],"parameters":[{"$ref":"#/components/parameters/files.search_parameters.limit"},{"$ref":"#/components/parameters/files.search_parameters.starting_after"},{"$ref":"#/components/parameters/list.common_parameters.sort_order"},{"$ref":"#/components/parameters/files.search_parameters.start_date"},{"$ref":"#/components/parameters/files.search_parameters.end_date"},{"name":"status","in":"query","description":"The status of the file.","schema":{"$ref":"#/components/schemas/file.status"}},{"name":"category","in":"query","description":"The category of the file.","schema":{"$ref":"#/components/schemas/file.category"}},{"name":"direction","in":"query","description":"The direction of the file.","schema":{"$ref":"#/components/schemas/file.direction"}},{"name":"format","in":"query","description":"The format of the file.","schema":{"$ref":"#/components/schemas/file.format"}},{"name":"connected_account_id","in":"query","description":"The ID of the connected account used to send or receive the file.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/file.details"}}}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/files/{id}":{"get":{"summary":"Retrieve file","description":"Retrieve the details of a file.","operationId":"retrieve-file","tags":["Files"],"parameters":[{"$ref":"#/components/parameters/file.id"}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/file.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/files/{id}/download":{"get":{"summary":"Download file","description":"Download a file.","operationId":"download-file","tags":["Files"],"parameters":[{"$ref":"#/components/parameters/file.id"}],"responses":{"302":{"description":"302","headers":{"Location":{"schema":{"type":"string"},"description":"The temporary URL to download the file, valid for 5 minutes."}},"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The temporary URL to download the file, valid for 5 minutes.","example":"https://temporary-url-example.com"}}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}}}}