Dispute Attachments¶

Generating a Pre-signed Upload URL¶

Generates a pre-signed S3 URL that can be used to upload a file attachment directly to storage. After calling this endpoint, upload the file by making a PUT request to the returned uploadUrl. Once uploaded, the file is scanned asynchronously, poll Retrieving an Attachment by ID until status is no longer PendingScan. See Allowed File Types for supported extensions.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAttachmentV1/post_v1_tenants__tenantId__disputes__disputeId__attachments

Permission¶

Dispute Management : UPDATE

Example Request¶

curl -X POST 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}/attachments' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>' \
    -d '<request body>'

Example Request Body¶

{
  "fileName": "my_attachment.pdf",
  "visibility": "Internal"
}

Request Fields¶

Field	Type	Required	Description
`fileName`	string	Yes	The name of the file being uploaded, including extension
`visibility`	string	No	Visibility of attachment

Example Response¶

{
  "uploadId": "{uploadId}",
  "uploadUrl": "https://billtrust-prod-arc-file-sani-svc-dirty-bucket.s3.amazonaws.com/filescanning/{uploadId}/my_attachment.pdf?AWSAccessKeyId={accessKey}&Expires=1616950053&x-amz-security-token={securityToken}"
}

Updating an Attachment¶

Updates the visibility of an existing attachment. This is the only field that can be changed after upload.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAttachmentV1/put_v1_tenants__tenantId__disputes__disputeId__attachments__id_

Permission¶

Dispute Management : UPDATE

Example Request¶

curl -X PUT 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}/attachments/{attachmentId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>' \
    -d '<request body>'

Example Request Body¶

{
  "visibility": "All"
}

Request Fields¶

Field	Type	Required	Description
`visibility`	string	No	Visibility of attachment

Example Response¶

{
  "attachmentId": "{attachmentId}",
  "disputeId": "{disputeId}",
  "visibility": "All"
}

Retrieving an Attachment by ID¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAttachmentV1/get_v1_tenants__tenantId__disputes__disputeId__attachments__id_

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}/attachments/{attachmentId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Behavior Notes¶

downloadUrl is only populated when status is Available. For all other statuses it returns an empty string. The URL expires 1 hour after it is generated, so retrieve it close to when you intend to use it.

Example Response¶

See DisputeAttachmentV1Response.

Retrieving all Attachments for a Dispute¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAttachmentV1/get_v1_tenants__tenantId__disputes__disputeId__attachments

Permission¶

Dispute Management : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}/attachments' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Query Parameters¶

Field	Type	Description
`Visibility`	string	Pass as repeated params for multiple values: `?Visibility=Internal&Visibility=All`

Behavior Notes¶

downloadUrl is always null on the list endpoint. Use Retrieving an Attachment by ID to get a download URL for a specific attachment.

Example Response¶

See Dispute Attachment List.

Deleting an Attachment¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAttachmentV1/delete_v1_tenants__tenantId__disputes__disputeId__attachments__id_

Permission¶

Dispute Management : UPDATE

Example Request¶

curl -X DELETE 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/disputes/{disputeId}/attachments/{attachmentId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Behavior Notes¶

This is a hard delete. The record is permanently removed from the database and the file is deleted from S3. Unlike disputes, attachments cannot be recovered after deletion.

Appendix¶

DisputeAttachmentV1Response¶

Returned by Retrieving an Attachment by ID.

{
  "tenantId": "{tenantId}",
  "attachmentId": "{attachmentId}",
  "disputeId": "{disputeId}",
  "fileName": "my_attachment.pdf",
  "downloadUrl": "https://billtrust-prod-arc-dispute-service-attachments-bucket.s3.amazonaws.com/{attachmentS3Key}?AWSAccessKeyId={accessKey}&Expires=1616947202&x-amz-security-token={securityToken}",
  "uploadId": "{uploadId}",
  "status": "Available",
  "visibility": "Internal",
  "attachmentS3Key": "{attachmentS3Key}",
  "failureReasons": [],
  "createUser": "{userId}",
  "createDate": "2021-03-28T14:55:47.406Z",
  "updateUser": "{userId}",
  "updateDate": "2021-03-28T14:55:47.406Z"
}

Dispute Attachment List¶

Returned by Retrieving all Attachments for a Dispute. An array of DisputeAttachmentV1Responses. Note that downloadUrl is always null in list responses.

[
  {
    "tenantId": "{tenantId}",
    "attachmentId": "{attachmentId}",
    "disputeId": "{disputeId}",
    "fileName": "my_attachment.pdf",
    "downloadUrl": null,
    "uploadId": "{uploadId}",
    "status": "Available",
    "visibility": "Internal",
    "attachmentS3Key": "{attachmentS3Key}",
    "failureReasons": [],
    "createUser": "{userId}",
    "createDate": "2021-03-28T14:55:47.406Z",
    "updateUser": "{userId}",
    "updateDate": "2021-03-28T14:55:47.406Z"
  },
  ...
]

Allowed File Types¶

Category	Examples
Adobe	.pdf
Archive	.zip
Email	.eml
Image	.jpeg .gif .png
Media	.mov .mp4
Office Documents	.docx .xlsx
Text Files	.txt .rtf