Bottomline PTX
API docs by Redocly

PTX Connect API (0.0)

Download OpenAPI specification:

PTX Connect API

Authentication

The process for API authentication uses Oauth2 and is used across PTX for One PTX modules and is not module specific. See Authentication for details.

Batches

These API calls are designed to collect reports for batches generated by PTX. Reports are of type PDF, PS or PCL format.

  • For Printing Services, reports are either produced and downloaded from the print factory or produced by the Document Object Model (DOM) engine.
  • For Cheques, reports are of type process (which may be used as batch separators), batch or print.

Get report files for a batch

Returns all report files for a batch.

Authorizations:
oauth2
path Parameters
batchId
required
integer <int64>

Batch ID.

Responses

Request samples 

https://documents.uk.pt-x.com/api/batches/1234/reportfiles

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get a report file for a batch

Retrieves the report file for a given batch ID and report file ID.

Authorizations:
oauth2
path Parameters
batchId
required
integer <int64>

Batch ID.

fileId
required
integer <int64>

File ID.

Responses

Request samples 

https://documents.uk.pt-x.com/api/batches/1234/reportfiles/5678

Printing Services

Printing Services enables customers to securely outsource the printing and delivery of cheques and other financial documents.

These API calls are designed to create a new batch, and to retrieve a list of batches or details of a specific batch.

Create a new Printing Services batch

Uploads a file to create a new Printing Services batch.

Authorizations:
oauth2
Request Body schema: multipart/form-data
BtsBatchOptions
required
string

JSON string options, e.g. {"profileId":"1"}.

File
required
string <binary>

File to upload.

Responses

Response samples

Content type
application/json
{
  • "model": {
    }
}

Get Printing Services batches

Returns a list of Printing Services batches based on specific criteria.

Authorizations:
oauth2
query Parameters
Name
string or null

Name of the batch.

CreationDate
string or null

Date that the batch was created.

creationdate_gte
string or null

Batch created later than a specific date.

creationdate_lte
string or null

Batch created earlier than a specific date.

BTSBatchStatus
string or null

Status of the batch.

Id
integer or null <int32>

Batch ID.

FileName
string or null

Name of the uploaded file.

TestMode
boolean or null

If set to true, batch created in test mode.

Archived
boolean or null

If set to true, batch has been archived.

sort
string (BtsBatchListRawQueryString.SortFields)
Enum: "Id" "Name" "CreationDate" "BtsBatchStatus" "FileName" "FileSize"

Sort results by particular column.

limit
integer <int32>

The maximum number of items to return.

startIndex
integer <int32>

The number of items to skip.

order
string (SortOrder)
Enum: "ASC" "DESC"

Sort results in ascending or descending order.

freetextsearch
string or null

Custom text search for File Name or Full Name.

Responses

Request samples 

1. List batches by name and status
https://documents.uk.pt-x.com/api/bts/batches?Name=Batch Name&BTSBatchStatus=Validating

2. Filter by creation date range
https://documents.uk.pt-x.com/api/bts/batches?creationdate_gte=2025-01-01T00:00:00Z&creationdate_lte=2025-03-31T23:59:59Z

3. Paginate with sorting by creation date descending
https://documents.uk.pt-x.com/api/bts/batches?limit=25&startIndex=0&sort=CreationDate&order=desc

4. Free text search
https://documents.uk.pt-x.com/api/bts/batches?freetextsearch=important batch

Response samples

Content type
application/json
{
  • "model": {
    }
}

Get Printing Services batch

Returns details of a Printing Services batch using given ID.

Authorizations:
oauth2
path Parameters
btsBatchId
required
integer <int64>

Batch ID.

Responses

Request samples 

https://documents.uk.pt-x.com/api/bts/batches/1234

Response samples

Content type
application/json
{
  • "model": {
    }
}

Documents

These API calls are designed to retrieve a list of documents or details of a specific document and can be used for standard or cheque documents.

List documents

Returns a list of documents based on specific criteria.

Authorizations:
oauth2
query Parameters
dir
string

Direction – set to out (outgoing) or in (incoming).

recipientemailaddress
string

Recipient email address.

documentdate
string

Document date.

documentdate_gte
string

Used to list documents later than a specified date.

documentdate_lte
string

Used to list documents earlier than a specified date.

documentdatetime_gte
string

Used to list documents later than a specified datetime.

documentdatetime_lte
string

Used to list documents earlier than a specified datetime.

creationdate
string

Creation date.

creationdate_gte
string

Used to list documents created later than a specified date.

creationdate_lte
string

Used to list documents created earlier than a specified date.

creationdatetime_gte
string

Used to list documents created later than a specified datetime.

creationdatetime_lte
string

Used to list documents created earlier than a specified datetime.

sentdate
string

Sent date.

sentdate_gte
string

Used to list documents sent later than a specified date.

sentdate_lte
string

Used to list documents sent earlier than a specified date.

sentdatetime_gte
string

Used to list documents sent later than a specified datetime.

sentdatetime_lte
string

Used to list documents sent earlier than a specified datetime.

expirydate
string

OutsideRetentionDate of the the document.

expirydate_lte
string

Used to list expired documents earlier than a specified date.

expirydate_gte
string

Used to list expired documents later than a specified date.

expirydatetime_lte
string

Used to list expired documents earlier than a specified datetime.

expirydatetime_gte
string

Used to list expired documents later than a specified datetime.

duedate
string

Due date of the document e.g. payment date.

duedate_lte
string

Used to list documents with due date earlier than a specified date.

duedate_gte
string

Used to list documents with due date later than a specified date.

duedatetime_lte
string

Used to list documents with due date earlier than a specified datetime.

duedatetime_gte
string

Used to list documents with due date later than a specified datetime.

documenttype
string (MailingType)
Enum: "Remittance" "Invoice" "SalesQuote" "DeliveryNote" "DunningLetter" "CreditNote" "StatementOfAccount" "Cheque" "PurchaseOrder" "Miscellaneous" "OrderAcknowledgement" "LegalCorrespondence" "Label"

Document type.

documenttype_include
Array of strings (MailingType)
Items Enum: "Remittance" "Invoice" "SalesQuote" "DeliveryNote" "DunningLetter" "CreditNote" "StatementOfAccount" "Cheque" "PurchaseOrder" "Miscellaneous" "OrderAcknowledgement" "LegalCorrespondence" "Label"

Document types to include.

documenttype_exclude
Array of strings (MailingType)
Items Enum: "Remittance" "Invoice" "SalesQuote" "DeliveryNote" "DunningLetter" "CreditNote" "StatementOfAccount" "Cheque" "PurchaseOrder" "Miscellaneous" "OrderAcknowledgement" "LegalCorrespondence" "Label"

Document types to exclude.

senderDocumentReference
string

Sender document reference.

recipientDocumentReference
string

Recipient document reference.

recipientReference
string

Recipient reference.

amount
string

Amount.

status
string (DocumentStatusQueryOptions)
Enum: "ReadyToSend" "Sending" "Warning" "Delivered" "SentManually" "Viewed" "Downloaded" "PrintedByRecipient" "Unpaid" "PartPaid" "Paid" "PaymentApproved" "PaymentInitiated" "PrintedBySender" "Printing" "Failed" "Actioned" "DeliveredAll"

Batch status.

paidStatus
string (DocumentPaidStatus)
Enum: "Unknown" "PartPaid" "Paid" "Failed" "PaymentApproved" "PaymentInitiated"

Invoice Outcome

groupBy
string (DocumentListRawQueryString.GroupByFields)
Enum: "MailingId" "MailingName" "Status" "RecipientEmailAddress" "DocumentType"

Specify how to group documents.

mailingId
integer <int64>

Batch Id.

profileId
integer <int64>

Document profile id.

mailingName
string

Batch name.

currency
string

Currency e.g. GBP, USD, EUR.

idle
integer <int32>

Period that document has been idle for.

idle_lte
integer <int32>

Used to list documents idle for less than a specified number of days.

idle_gte
integer <int32>

Used to list documents idle for more than a specified number of days.

timeuntilactioned
integer <int32>

Time taken to action the document.

discussion
string (DiscussionStatus)
Enum: "None" "Closed" "Open"

Discussion status. Possible values are: • None • Closed • Open

owner
string

Document owner.

testMode
boolean

If true, document has been uploaded using a document profile in test mode.

from
string

Email From address.

companyName
string

Company name.

sort
string (DocumentListRawQueryString.SortFields)
Enum: "RecipientEmailAddress" "DocumentDate" "DocumentType" "Amount" "Status" "From" "RecipientDocumentReference" "SenderDocumentReference" "RecipientReference" "MailingName" "Discussion" "Owner" "CompanyName" "SentDate" "CreationDate" "ExpiryDate" "DueDate" "PaidStatus"

Sort the results by column.

Done
boolean

Whether the document was marked as archived.

Archived
boolean

Whether the document was marked as archived.

IgnoreCompleteArchivedBatches
boolean

If true, batches that were archived should not be included.

Revoked
boolean

Revoked status of the document.

limit
integer <int32>

The maximum number of items to return.

startIndex
integer <int32>

The number of items to skip.

order
string (SortOrder)
Enum: "ASC" "DESC"

Sort results in ascending or descending order.

freetextsearch
string

Custom text search for File Name or Full Name.

Responses

Request samples 

1. List documents by date
https://documents.uk.pt-x.com/api/documents?documentdate=2019-07-16T09:28:12.004Z

2. List documents by status
https://documents.uk.pt-x.com/api/documents?status=sent

3. List documents by type and currency
https://documents.uk.pt-x.com/api/documents?documenttype=invoice&currency=GBP

4. List documents by recipient email address and date
https://documents.uk.pt-x.com/api/documents?recipientemailaddress=example@gmail.com&documentdate=2019-07-11T09:28:12.004Z

Response samples

Content type
application/json
{
  • "summary": {
    },
  • "data": [
    ],
  • "recordTotal": 2
}

List archived documents

Returns a list of archived documents.

Authorizations:
oauth2
query Parameters
pendingDeletion
boolean or null

If true, document is pending deletion.

done
boolean or null

If true, documents that are marked as archived or part of a Check batch that is archived.

archived
boolean or null

If true, documents that are marked as archived or part of a Check batch that is archived.

dir
string or null

Direction – set to out (outgoing) or in (incoming).

recipientemailaddress
string or null

Recipient email address.

documentdate
string or null

Document date.

documentdate_gte
string or null

Used to list documents later than a specified date.

documentdate_lte
string or null

Used to list documents earlier than a specified date.

documentdatetime_gte
string or null

Used to list documents later than a specified datetime.

documentdatetime_lte
string or null

Used to list documents earlier than a specified datetime.

creationdate
string or null

Creation date.

creationdate_gte
string or null

Used to list documents created later than a specified date.

creationdate_lte
string or null

Used to list documents created earlier than a specified date.

creationdatetime_gte
string or null

Used to list documents created later than a specified datetime.

creationdatetime_lte
string or null

Used to list documents created earlier than a specified datetime.

sentdate
string or null

Sent date.

sentdate_gte
string or null

Used to list documents sent later than a specified date.

sentdate_lte
string or null

Used to list documents sent earlier than a specified date.

sentdatetime_gte
string or null

Used to list documents sent later than a specified datetime.

sentdatetime_lte
string or null

Used to list documents sent earlier than a specified datetime.

expirydate
string or null

OutsideRetentionDate of the the document.

expirydate_lte
string or null

Used to list expired documents earlier than a specified date.

expirydate_gte
string or null

Used to list expired documents later than a specified date.

expirydatetime_lte
string or null

Used to list expired documents earlier than a specified datetime.

expirydatetime_gte
string or null

Used to list expired documents later than a specified datetime.

duedate
string or null

Due date of the document e.g. payment date.

duedate_lte
string or null

Used to list documents with due date earlier than a specified date.

duedate_gte
string or null

Used to list documents with due date later than a specified date.

duedatetime_lte
string or null

Used to list documents with due date earlier than a specified datetime.

duedatetime_gte
string or null

Used to list documents with due date later than a specified datetime.

documenttype
string (MailingType)
Enum: "Remittance" "Invoice" "SalesQuote" "DeliveryNote" "DunningLetter" "CreditNote" "StatementOfAccount" "Cheque" "PurchaseOrder" "Miscellaneous" "OrderAcknowledgement" "LegalCorrespondence" "Label"

Document type.

documenttype_include
Array of strings or null (MailingType)
Enum: "Remittance" "Invoice" "SalesQuote" "DeliveryNote" "DunningLetter" "CreditNote" "StatementOfAccount" "Cheque" "PurchaseOrder" "Miscellaneous" "OrderAcknowledgement" "LegalCorrespondence" "Label"

Document types to include.

documenttype_exclude
Array of strings or null (MailingType)
Enum: "Remittance" "Invoice" "SalesQuote" "DeliveryNote" "DunningLetter" "CreditNote" "StatementOfAccount" "Cheque" "PurchaseOrder" "Miscellaneous" "OrderAcknowledgement" "LegalCorrespondence" "Label"

Document types to exclude.

senderDocumentReference
string or null

Sender document reference.

recipientDocumentReference
string or null

Recipient document reference.

recipientReference
string or null

Recipient reference.

amount
string or null

Amount.

status
string (DocumentStatusQueryOptions)
Enum: "ReadyToSend" "Sending" "Warning" "Delivered" "SentManually" "Viewed" "Downloaded" "PrintedByRecipient" "Unpaid" "PartPaid" "Paid" "PaymentApproved" "PaymentInitiated" "PrintedBySender" "Printing" "Failed" "Actioned" "DeliveredAll"

Batch status.

paidStatus
string (DocumentPaidStatus)
Enum: "Unknown" "PartPaid" "Paid" "Failed" "PaymentApproved" "PaymentInitiated"

Invoice Outcome

groupBy
string (DocumentListRawQueryString.GroupByFields)
Enum: "MailingId" "MailingName" "Status" "RecipientEmailAddress" "DocumentType"

Specify how to group documents.

mailingId
integer or null <int64>

Batch Id.

profileId
integer or null <int64>

Document profile id.

mailingName
string or null

Batch name.

currency
string or null

Currency e.g. GBP, USD, EUR.

idle
integer or null <int32>

Period that document has been idle for.

idle_lte
integer or null <int32>

Used to list documents idle for less than a specified number of days.

idle_gte
integer or null <int32>

Used to list documents idle for more than a specified number of days.

timeuntilactioned
integer or null <int32>

Time taken to action the document.

discussion
string (DiscussionStatus)
Enum: "None" "Closed" "Open"

Discussion status. Possible values are: • None • Closed • Open

owner
string or null

Document owner.

testMode
boolean or null

If true, document has been uploaded using a document profile in test mode.

from
string or null

Email From address.

companyName
string or null

Company name.

sort
string (DocumentListRawQueryString.SortFields)
Enum: "RecipientEmailAddress" "DocumentDate" "DocumentType" "Amount" "Status" "From" "RecipientDocumentReference" "SenderDocumentReference" "RecipientReference" "MailingName" "Discussion" "Owner" "CompanyName" "SentDate" "CreationDate" "ExpiryDate" "DueDate" "PaidStatus"

Sort the results by column.

Done
boolean or null

Whether the document was marked as archived.

Archived
boolean or null

Whether the document was marked as archived.

IgnoreCompleteArchivedBatches
boolean or null

If true, batches that were archived should not be included.

Revoked
boolean or null

Revoked status of the document.

limit
integer <int32>

The maximum number of items to return.

startIndex
integer <int32>

The number of items to skip.

order
string (SortOrder)
Enum: "ASC" "DESC"

Sort results in ascending or descending order.

freetextsearch
string or null

Custom text search for File Name or Full Name.

Responses

Request samples 

1. List documents by date
https://documents.uk.pt-x.com/api/documents/archived?documentdate=2019-07-16T09:28:12.004Z

2. List documents by type
https://documents.uk.pt-x.com/api/documents/archived?documenttype=invoice&documenttype_exclude=salesqoute

3. List documents by type and currency
https://documents.uk.pt-x.com/api/documents/archived?documenttype=invoice&currency=GBP

4. List documents by recipient email address and date
https://documents.uk.pt-x.com/api/documents/archived?recipientemailaddress=example@gmail.com&documentdate=2019-07-11T09:28:12.004Z

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "recordTotal": 2
}

Retrieve a document

Retrieves details of a document using unique identifier.

Authorizations:
oauth2
path Parameters
documentId
required
integer <int64>

Document identifier, obtained from the List documents call.

query Parameters
dir
string (Document.Direction)
Enum: "Out" "In"

Determines whether this is an inbox or outbox query.

Responses

Request samples 

https://documents.uk.pt-x.com/api/documents/1234

Response samples

Content type
application/json
{
  • "id": 1234,
  • "documentType": "Miscellaneous",
  • "documentDate": null,
  • "senderDocumentReference": "",
  • "recipientDocumentReference": "REC-DOC-REF-002",
  • "amount": 456,
  • "currency": "GBP",
  • "creationDate": "2025-05-12T08:40:27.0781606Z",
  • "pageCount": 1,
  • "sentDate": "2025-05-12T08:40:27.0781679Z",
  • "viewedDate": null,
  • "subject": null,
  • "recipientCompanyNumber": "BOTTOM003",
  • "recipientVATNumber": "VAT004",
  • "recipientEmailAddress": "sandrashortland@example.com",
  • "recipientTelephoneNumber": "1234567890",
  • "allowSignUp": null,
  • "from": "noreply@dev.ptxtest2.co.uk",
  • "sentTo": "sandrashortland@example.com",
  • "status": "New",
  • "secretId": "ZOCAQW3IX128RQL7JZOX",
  • "lastStatusChangeDate": "2025-05-12T08:40:27.07817Z",
  • "comments": 0,
  • "discussion": "None",
  • "discussionOpen": true,
  • "discussionUrl": null,
  • "supportingFileTotal": 0,
  • "expiryDate": "0001-01-01T00:00:00Z",
  • "pendingDeletion": false,
  • "dueDate": null,
  • "recipientType": null,
  • "revoked": false,
  • "LayoutPdfFileId": null,
  • "recipientId": null,
  • "recipientUserId": null,
  • "done": false,
  • "archived": false,
  • "read": false,
  • "registrationUrl": null,
  • "printUrl": null,
  • "documentInboxUrl": null,
  • "companyName": null,
  • "isPromptToPayDocument": false,
  • "privateInbox": true,
  • "additionalRecipientsTotal": 0,
  • "paidStatus": "Unknown"
}