From 01c348d5a7dee9d9e8df33bb89c0b565f65be4b9 Mon Sep 17 00:00:00 2001 From: srikar-methodfi Date: Wed, 5 Aug 2026 14:55:36 -0400 Subject: [PATCH] add files api + raw crpt to openapi spec --- latest/openapi.bundled.json | 277 +++++++++++++++++++- latest/openapi.bundled.yaml | 188 ++++++++++++- manifests/mounted-routes.json | 8 + manifests/operation-ids.json | 2 + openapi/components/parameters/path_ids.yaml | 9 + openapi/components/schemas/entity.yaml | 46 +++- openapi/components/schemas/file.yaml | 58 ++++ openapi/openapi.yaml | 6 + openapi/paths/entity_connects.yaml | 26 ++ openapi/paths/files.yaml | 79 ++++++ 10 files changed, 683 insertions(+), 16 deletions(-) create mode 100644 openapi/components/schemas/file.yaml create mode 100644 openapi/paths/files.yaml diff --git a/latest/openapi.bundled.json b/latest/openapi.bundled.json index e827686..ecd2e6f 100644 --- a/latest/openapi.bundled.json +++ b/latest/openapi.bundled.json @@ -145,6 +145,10 @@ "name": "Events", "description": "Webhook event log" }, + { + "name": "Files", + "description": "Downloadable artifacts generated by Method" + }, { "name": "Forwarding Requests", "description": "Request forwarding with sensitive data injection" @@ -4137,7 +4141,31 @@ "items": { "type": "string" } + }, + "bureau": { + "type": "string", + "description": "The credit bureau to pull the raw credit report from. Required when `artifacts` is set. Method configures which bureaus are permitted for your team; pulling from both bureaus requires two separate requests.", + "enum": [ + "equifax", + "transunion" + ] + }, + "artifacts": { + "type": "array", + "description": "Credit report artifacts to generate for this connect session. Each artifact is returned as a file in the `files` array of the response and can be downloaded through the Files API. Requires `bureau`. Raw credit report access is a restricted feature enabled per team.", + "items": { + "type": "string", + "enum": [ + "raw_credit_report", + "credit_report_pdf" + ] + } } + }, + "dependentRequired": { + "artifacts": [ + "bureau" + ] } } } @@ -6097,6 +6125,127 @@ } } }, + "/files/{fileId}": { + "get": { + "operationId": "retrieveFile", + "summary": "Retrieve a file", + "description": "Returns a single file by its identifier, including a temporary pre-signed `download_url`. A fresh URL is generated on every retrieve.", + "tags": [ + "Files" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/FileIdParam" + } + ], + "responses": { + "200": { + "description": "The requested file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/files/{fileId}/download": { + "get": { + "operationId": "downloadFile", + "summary": "Download a file", + "description": "Returns the raw contents of the file as an attachment. Use this endpoint for direct access to the file. To obtain a pre-signed link instead, use the retrieve endpoint and read `download_url`.", + "tags": [ + "Files" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/FileIdParam" + } + ], + "responses": { + "200": { + "description": "The raw file contents. The `Content-Type` header matches the file's `mime_type`.", + "headers": { + "Content-Disposition": { + "description": "Attachment filename for the downloaded file.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "application/pdf": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, "/forwarding_requests": { "post": { "operationId": "createForwardingRequest", @@ -9844,6 +9993,16 @@ "pattern": "^evt_\\w+$" } }, + "FileIdParam": { + "name": "fileId", + "in": "path", + "required": true, + "description": "Unique identifier for the file.", + "schema": { + "type": "string", + "pattern": "^file_\\w+$" + } + }, "expand_payments": { "name": "expand", "in": "query", @@ -15157,6 +15316,45 @@ } } }, + "EntityConnectFile": { + "type": "object", + "description": "A reference to a file generated for a connect session, along with the contextual metadata describing how it was produced.", + "required": [ + "id", + "type", + "bureau", + "mime_type" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the file. Retrieve the file through the Files API to obtain a download URL.", + "pattern": "^file_\\w+$", + "example": "file_jZWkPMhXPeYAn" + }, + "type": { + "type": "string", + "description": "The type of artifact this file contains.", + "enum": [ + "raw_credit_report", + "credit_report_pdf" + ] + }, + "bureau": { + "type": "string", + "description": "The credit bureau the file was generated from.", + "enum": [ + "transunion", + "equifax" + ] + }, + "mime_type": { + "type": "string", + "description": "The content type of the file, e.g. `application/json` or `application/pdf`.", + "example": "application/json" + } + } + }, "ConnectResourceError": { "type": [ "object", @@ -15214,6 +15412,7 @@ "accounts", "requested_products", "requested_subscriptions", + "files", "created_at", "updated_at" ], @@ -15278,13 +15477,10 @@ } }, "files": { - "type": [ - "array", - "null" - ], - "description": "Files associated with this connect session (e.g. manual connect uploads).", + "type": "array", + "description": "Credit report artifacts generated for this connect session. Only populated when `artifacts` are requested on creation. Retrieve or download a file's contents through the Files API.", "items": { - "$ref": "#/components/schemas/JsonObject" + "$ref": "#/components/schemas/EntityConnectFile" } }, "error": { @@ -17333,6 +17529,75 @@ "message": null } }, + "File": { + "type": "object", + "description": "A File is a downloadable artifact generated by Method. Files cannot be created directly. They are produced as a result of other API requests and are referenced by the resource that generated them.", + "required": [ + "id", + "type", + "mime_type", + "download_url", + "download_expires_at", + "created_at", + "updated_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the file.", + "pattern": "^file_\\w+$", + "example": "file_jZWkPMhXPeYAn" + }, + "type": { + "type": "string", + "description": "The type of artifact this file contains.", + "enum": [ + "raw_credit_report", + "credit_report_pdf" + ] + }, + "mime_type": { + "type": "string", + "description": "The content type of the file, e.g. `application/json` or `application/pdf`.", + "example": "application/json" + }, + "download_url": { + "type": "string", + "format": "uri", + "description": "A temporary, pre-signed URL to the file's contents. A new URL is generated on every retrieve." + }, + "download_expires_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when `download_url` expires. URLs are valid for 60 minutes (3600 seconds) by default. Retrieve the file again to receive a fresh URL." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the file was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the file was last updated." + } + } + }, + "FileResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/File" + } + } + } + ] + }, "ForwardingRequestCreateRequest": { "type": "object", "required": [ diff --git a/latest/openapi.bundled.yaml b/latest/openapi.bundled.yaml index f75311a..cbb2504 100644 --- a/latest/openapi.bundled.yaml +++ b/latest/openapi.bundled.yaml @@ -117,6 +117,8 @@ tags: description: Verification sessions for entities - name: Events description: Webhook event log + - name: Files + description: Downloadable artifacts generated by Method - name: Forwarding Requests description: Request forwarding with sensitive data injection - name: Managed Accounts @@ -2503,6 +2505,23 @@ paths: description: Subscriptions to request during the connect session. items: type: string + bureau: + type: string + description: The credit bureau to pull the raw credit report from. Required when `artifacts` is set. Method configures which bureaus are permitted for your team; pulling from both bureaus requires two separate requests. + enum: + - equifax + - transunion + artifacts: + type: array + description: Credit report artifacts to generate for this connect session. Each artifact is returned as a file in the `files` array of the response and can be downloaded through the Files API. Requires `bureau`. Raw credit report access is a restricted feature enabled per team. + items: + type: string + enum: + - raw_credit_report + - credit_report_pdf + dependentRequired: + artifacts: + - bureau responses: '200': description: The created entity connect session. @@ -3684,6 +3703,78 @@ paths: $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' + /files/{fileId}: + get: + operationId: retrieveFile + summary: Retrieve a file + description: Returns a single file by its identifier, including a temporary pre-signed `download_url`. A fresh URL is generated on every retrieve. + tags: + - Files + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - $ref: '#/components/parameters/FileIdParam' + responses: + '200': + description: The requested file. + content: + application/json: + schema: + $ref: '#/components/schemas/FileResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' + /files/{fileId}/download: + get: + operationId: downloadFile + summary: Download a file + description: Returns the raw contents of the file as an attachment. Use this endpoint for direct access to the file. To obtain a pre-signed link instead, use the retrieve endpoint and read `download_url`. + tags: + - Files + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - $ref: '#/components/parameters/FileIdParam' + responses: + '200': + description: The raw file contents. The `Content-Type` header matches the file's `mime_type`. + headers: + Content-Disposition: + description: Attachment filename for the downloaded file. + schema: + type: string + content: + application/json: + schema: + type: string + format: binary + application/pdf: + schema: + type: string + format: binary + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' /forwarding_requests: post: operationId: createForwardingRequest @@ -6122,6 +6213,14 @@ components: schema: type: string pattern: ^evt_\w+$ + FileIdParam: + name: fileId + in: path + required: true + description: Unique identifier for the file. + schema: + type: string + pattern: ^file_\w+$ expand_payments: name: expand in: query @@ -9869,6 +9968,36 @@ components: $ref: '#/components/schemas/EntityVerificationIdentity' phone: $ref: '#/components/schemas/EntityVerificationPhone' + EntityConnectFile: + type: object + description: A reference to a file generated for a connect session, along with the contextual metadata describing how it was produced. + required: + - id + - type + - bureau + - mime_type + properties: + id: + type: string + description: Unique identifier for the file. Retrieve the file through the Files API to obtain a download URL. + pattern: ^file_\w+$ + example: file_jZWkPMhXPeYAn + type: + type: string + description: The type of artifact this file contains. + enum: + - raw_credit_report + - credit_report_pdf + bureau: + type: string + description: The credit bureau the file was generated from. + enum: + - transunion + - equifax + mime_type: + type: string + description: The content type of the file, e.g. `application/json` or `application/pdf`. + example: application/json ConnectResourceError: type: - object @@ -9914,6 +10043,7 @@ components: - accounts - requested_products - requested_subscriptions + - files - created_at - updated_at properties: @@ -9959,12 +10089,10 @@ components: items: type: string files: - type: - - array - - 'null' - description: Files associated with this connect session (e.g. manual connect uploads). + type: array + description: Credit report artifacts generated for this connect session. Only populated when `artifacts` are requested on creation. Retrieve or download a file's contents through the Files API. items: - $ref: '#/components/schemas/JsonObject' + $ref: '#/components/schemas/EntityConnectFile' error: type: - object @@ -11373,6 +11501,56 @@ components: created_at: '2026-01-15T18:30:00.000Z' updated_at: '2026-01-15T18:30:00.000Z' message: null + File: + type: object + description: A File is a downloadable artifact generated by Method. Files cannot be created directly. They are produced as a result of other API requests and are referenced by the resource that generated them. + required: + - id + - type + - mime_type + - download_url + - download_expires_at + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the file. + pattern: ^file_\w+$ + example: file_jZWkPMhXPeYAn + type: + type: string + description: The type of artifact this file contains. + enum: + - raw_credit_report + - credit_report_pdf + mime_type: + type: string + description: The content type of the file, e.g. `application/json` or `application/pdf`. + example: application/json + download_url: + type: string + format: uri + description: A temporary, pre-signed URL to the file's contents. A new URL is generated on every retrieve. + download_expires_at: + type: string + format: date-time + description: Timestamp when `download_url` expires. URLs are valid for 60 minutes (3600 seconds) by default. Retrieve the file again to receive a fresh URL. + created_at: + type: string + format: date-time + description: Timestamp when the file was created. + updated_at: + type: string + format: date-time + description: Timestamp when the file was last updated. + FileResponse: + allOf: + - $ref: '#/components/schemas/SuccessEnvelope' + - type: object + properties: + data: + $ref: '#/components/schemas/File' ForwardingRequestCreateRequest: type: object required: diff --git a/manifests/mounted-routes.json b/manifests/mounted-routes.json index 787a93a..a7660b4 100644 --- a/manifests/mounted-routes.json +++ b/manifests/mounted-routes.json @@ -327,6 +327,14 @@ "method": "GET", "path": "/events/{evtId}" }, + { + "method": "GET", + "path": "/files/{fileId}" + }, + { + "method": "GET", + "path": "/files/{fileId}/download" + }, { "method": "POST", "path": "/forwarding_requests" diff --git a/manifests/operation-ids.json b/manifests/operation-ids.json index 952a368..88eb90a 100644 --- a/manifests/operation-ids.json +++ b/manifests/operation-ids.json @@ -34,6 +34,7 @@ "deleteSecret", "deleteTeamPublicKey", "deleteWebhook", + "downloadFile", "downloadReport", "elementsCreateToken", "elementsExchangeAccount", @@ -97,6 +98,7 @@ "retrieveEntityVehicle", "retrieveEntityVerificationSession", "retrieveEvent", + "retrieveFile", "retrieveForwardingRequest", "retrieveManagedAccount", "retrieveMerchant", diff --git a/openapi/components/parameters/path_ids.yaml b/openapi/components/parameters/path_ids.yaml index 170ac75..6a89fe9 100644 --- a/openapi/components/parameters/path_ids.yaml +++ b/openapi/components/parameters/path_ids.yaml @@ -34,6 +34,15 @@ WebhookIdParam: type: string pattern: '^whk_\w+$' +FileIdParam: + name: fileId + in: path + required: true + description: Unique identifier for the file. + schema: + type: string + pattern: '^file_\w+$' + EventIdParam: name: evtId in: path diff --git a/openapi/components/schemas/entity.yaml b/openapi/components/schemas/entity.yaml index 0493a3b..2f3cf36 100644 --- a/openapi/components/schemas/entity.yaml +++ b/openapi/components/schemas/entity.yaml @@ -643,6 +643,7 @@ EntityConnect: - accounts - requested_products - requested_subscriptions + - files - created_at - updated_at properties: @@ -690,12 +691,13 @@ EntityConnect: items: type: string files: - type: - - array - - 'null' - description: Files associated with this connect session (e.g. manual connect uploads). + type: array + description: >- + Credit report artifacts generated for this connect session. Only + populated when `artifacts` are requested on creation. Retrieve or + download a file's contents through the Files API. items: - $ref: common.yaml#/JsonObject + $ref: '#/EntityConnectFile' error: type: - object @@ -711,6 +713,40 @@ EntityConnect: type: string format: date-time description: Timestamp when the connect session was last updated. +EntityConnectFile: + type: object + description: >- + A reference to a file generated for a connect session, along with the + contextual metadata describing how it was produced. + required: + - id + - type + - bureau + - mime_type + properties: + id: + type: string + description: >- + Unique identifier for the file. Retrieve the file through the Files API + to obtain a download URL. + pattern: ^file_\w+$ + example: file_jZWkPMhXPeYAn + type: + type: string + description: The type of artifact this file contains. + enum: + - raw_credit_report + - credit_report_pdf + bureau: + type: string + description: The credit bureau the file was generated from. + enum: + - transunion + - equifax + mime_type: + type: string + description: The content type of the file, e.g. `application/json` or `application/pdf`. + example: application/json EntityCreditScore: type: object required: diff --git a/openapi/components/schemas/file.yaml b/openapi/components/schemas/file.yaml new file mode 100644 index 0000000..0666e78 --- /dev/null +++ b/openapi/components/schemas/file.yaml @@ -0,0 +1,58 @@ +File: + type: object + description: >- + A File is a downloadable artifact generated by Method. Files cannot be + created directly. They are produced as a result of other API requests and + are referenced by the resource that generated them. + required: + - id + - type + - mime_type + - download_url + - download_expires_at + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the file. + pattern: ^file_\w+$ + example: file_jZWkPMhXPeYAn + type: + type: string + description: The type of artifact this file contains. + enum: + - raw_credit_report + - credit_report_pdf + mime_type: + type: string + description: The content type of the file, e.g. `application/json` or `application/pdf`. + example: application/json + download_url: + type: string + format: uri + description: >- + A temporary, pre-signed URL to the file's contents. A new URL is + generated on every retrieve. + download_expires_at: + type: string + format: date-time + description: >- + Timestamp when `download_url` expires. URLs are valid for 60 minutes + (3600 seconds) by default. Retrieve the file again to receive a fresh + URL. + created_at: + type: string + format: date-time + description: Timestamp when the file was created. + updated_at: + type: string + format: date-time + description: Timestamp when the file was last updated. +FileResponse: + allOf: + - $ref: common.yaml#/SuccessEnvelope + - type: object + properties: + data: + $ref: '#/File' diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index f6abfe8..48761c6 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -78,6 +78,8 @@ tags: description: Verification sessions for entities - name: Events description: Webhook event log +- name: Files + description: Downloadable artifacts generated by Method - name: Forwarding Requests description: Request forwarding with sensitive data injection - name: Managed Accounts @@ -215,6 +217,10 @@ paths: $ref: paths/events.yaml#/collection /events/{evtId}: $ref: paths/events.yaml#/individual + /files/{fileId}: + $ref: paths/files.yaml#/individual + /files/{fileId}/download: + $ref: paths/files.yaml#/download /forwarding_requests: $ref: paths/forwarding_requests.yaml#/create /forwarding_requests/{id}: diff --git a/openapi/paths/entity_connects.yaml b/openapi/paths/entity_connects.yaml index 7f29ffd..19c5c15 100644 --- a/openapi/paths/entity_connects.yaml +++ b/openapi/paths/entity_connects.yaml @@ -67,6 +67,32 @@ collection: description: Subscriptions to request during the connect session. items: type: string + bureau: + type: string + description: >- + The credit bureau to pull the raw credit report from. Required + when `artifacts` is set. Method configures which bureaus are + permitted for your team; pulling from both bureaus requires two + separate requests. + enum: + - equifax + - transunion + artifacts: + type: array + description: >- + Credit report artifacts to generate for this connect session. + Each artifact is returned as a file in the `files` array of the + response and can be downloaded through the Files API. Requires + `bureau`. Raw credit report access is a restricted feature + enabled per team. + items: + type: string + enum: + - raw_credit_report + - credit_report_pdf + dependentRequired: + artifacts: + - bureau responses: '200': description: The created entity connect session. diff --git a/openapi/paths/files.yaml b/openapi/paths/files.yaml new file mode 100644 index 0000000..2bd52c4 --- /dev/null +++ b/openapi/paths/files.yaml @@ -0,0 +1,79 @@ +individual: + get: + operationId: retrieveFile + summary: Retrieve a file + description: >- + Returns a single file by its identifier, including a temporary pre-signed + `download_url`. A fresh URL is generated on every retrieve. + tags: + - Files + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - $ref: ../components/parameters/path_ids.yaml#/FileIdParam + responses: + '200': + description: The requested file. + content: + application/json: + schema: + $ref: ../components/schemas/file.yaml#/FileResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '404': + $ref: ../components/responses/error.yaml#/NotFound + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError +download: + get: + operationId: downloadFile + summary: Download a file + description: >- + Returns the raw contents of the file as an attachment. Use this endpoint + for direct access to the file. To obtain a pre-signed link instead, use + the retrieve endpoint and read `download_url`. + tags: + - Files + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - $ref: ../components/parameters/path_ids.yaml#/FileIdParam + responses: + '200': + description: >- + The raw file contents. The `Content-Type` header matches the file's + `mime_type`. + headers: + Content-Disposition: + description: Attachment filename for the downloaded file. + schema: + type: string + content: + application/json: + schema: + type: string + format: binary + application/pdf: + schema: + type: string + format: binary + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '404': + $ref: ../components/responses/error.yaml#/NotFound + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError