Bureau Customer Operations
Bureau Customer Operations
There are several operations that can be used to create and manage Bureau Customers, which hold the banking and contact details used for Bureau Submissions.
Base URLs
There are two URLs that used, for development, it is recommeded that the Test URL is used. These URLs are:
- Test : https://api.paygateservicedemo.com/bureau_publicapi/api/v3.5
- Production: https://api.paygateservice.com/bureau_publicapi/api/v3.5
This tutorial will use the test URL.
A complete list of operations can be found on the API document:
Get Bureau Customers
Retrieves a list of available Bureau Customers. A filtered list of Bureau Customers can be retrieved by passing in a filterText querystring parameter, performing a “fuzzy” search on the underlying dataset.
HTTP GET
/bureau-customers/?filterText={OPTIONAL}
Example Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"customers": [
{
"name": "John Smith Business",
"contactFirstName": "John",
"contactSurname": "Smith",
"customerAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"telephone": "01234 567890",
"telephone2": "01234 567890",
"websiteUrl": "https://www.johnsmithsbusiness.fake/",
"emailAddress": "johnsmith@johnsmithsbusiness.fake",
"serviceUserNumber": "100000",
"paymentLimit": 10,
"submissionLimit": 10.5,
"deleted": false,
"contraNarrative": "CONTRA",
"bankName": "Trusted Bank Plc.",
"sortCode": "101010",
"accountNumber": "10101010",
"createdDate": "2019-08-24T14:15:22Z",
"modifiedDate": "2019-08-24T14:15:22Z",
"defaultImportSchema": "Mapping",
"defaultImportMapping": "Your Mapping",
"defaultImportFilename": "Filename.txt",
"tags": "TAG1",
"bankReference": "SMITH123",
"bankAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"reference": "YOURCUST001",
"customerUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/",
"notesUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/notes",
"jobsUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs",
"submissionsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/submissions"
}
]
}
Update Bureau Customer
A Bureau Customer can be update using the API. The Bureau Customer cannot be changed if it is being included in a current Submission.
HTTP PUT
/bureau-customers/
Example Request:
{
"name": "John Smith Business",
"contactFirstName": "John",
"contactSurname": "Smith",
"customerAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"telephone": "01234 567890",
"telephone2": "01234 567890",
"websiteUrl": "https://www.johnsmithsbusiness.fake/",
"emailAddress": "johnsmith@johnsmithsbusiness.fake",
"serviceUserNumber": "100000",
"paymentLimit": 10,
"submissionLimit": 10.5,
"deleted": false,
"contraNarrative": "CONTRA",
"bankName": "Trusted Bank Plc.",
"sortCode": "101010",
"accountNumber": "10101010",
"createdDate": "2019-08-24T14:15:22Z",
"modifiedDate": "2019-08-24T14:15:22Z",
"defaultImportSchema": "Mapping",
"defaultImportMapping": "Your Mapping",
"defaultImportFilename": "Filename.txt",
"tags": "TAG1",
"bankReference": "SMITH123",
"bankAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"reference": "YOURCUST001"
}
The response generated by the Update request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation.
Example Response:
{
"success": true,
"messages": [
"Bureau Customer Updated"
],
"customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"customerUrl": "/api/v1/customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"notesUrl": "/api/v1/customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/notes",
"jobsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs",
"submissionsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/submissions"
}
Delete Bureau Customer
Bureau Customers that are not included in a current submission can be deleted from the system by performing a DELETE request to the below endpoint, with the customer ID passed as a query parameter.
HTTP DELETE
/bureau-customers/?customerId={CUSTOMER-ID}
The response generated by the Update request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation.
Example Response:
{
"success": true,
"messages": [
"Bureau Customer Deleted"
]
}
Create Bureau Customers
Passing an array of Bureau Customers to the POST endpoint will allow Bureau Customers to be created.
HTTP POST
/bureau-customers/
Example Request:
{
"customers": [
{
"name": "John Smith Business",
"contactFirstName": "John",
"contactSurname": "Smith",
"customerAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"telephone": "01234 567890",
"telephone2": "01234 567890",
"websiteUrl": "https://www.johnsmithsbusiness.fake/",
"emailAddress": "johnsmith@johnsmithsbusiness.fake",
"serviceUserNumber": "100000",
"paymentLimit": 10,
"submissionLimit": 10.5,
"deleted": false,
"contraNarrative": "CONTRA",
"bankName": "Trusted Bank Plc.",
"sortCode": "101010",
"accountNumber": "10101010",
"createdDate": "2019-08-24T14:15:22Z",
"modifiedDate": "2019-08-24T14:15:22Z",
"defaultImportSchema": "Mapping",
"defaultImportMapping": "Your Mapping",
"defaultImportFilename": "Filename.txt",
"tags": "TAG1",
"bankReference": "SMITH123",
"bankAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
}
}
]
}
The response generated by the Create request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation.
Example Response:
{
"success": true,
"messages": [
"Operation Successful"
]
}
Get Bureau Customer
Appending the Customer ID to the Bureau Customers endpoint URL will allow the retrieval of Bureau Customer details:
HTTP GET
/bureau-customers/{CUSTOMER-ID}/
If no Bureau Customer exists with that matching ID, a HTTP Status code 404 (Not Found) is returned, this will also occur if the querying user does not have permission to access that resource.
Example Response:
{
"name": "John Smith Business",
"contactFirstName": "John",
"contactSurname": "Smith",
"customerAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"telephone": "01234 567890",
"telephone2": "01234 567890",
"websiteUrl": "https://www.johnsmithsbusiness.fake/",
"emailAddress": "johnsmith@johnsmithsbusiness.fake",
"serviceUserNumber": "100000",
"paymentLimit": 10,
"submissionLimit": 10.5,
"deleted": false,
"contraNarrative": "CONTRA",
"bankName": "Trusted Bank Plc.",
"sortCode": "101010",
"accountNumber": "10101010",
"createdDate": "2019-08-24T14:15:22Z",
"modifiedDate": "2019-08-24T14:15:22Z",
"defaultImportSchema": "Mapping",
"defaultImportMapping": "Your Mapping",
"defaultImportFilename": "Filename.txt",
"tags": "TAG1",
"bankReference": "SMITH123",
"bankAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"reference": "YOURCUST001",
"customerUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/",
"notesUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/notes",
"jobsUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs",
"submissionsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/submissions"
}
Get Bureau Customer Notes
Any notes associated with the Bureau Customer can be retrieved from the endpoint below, with {CUSTOMER-ID} replaced by the Bureau Customer ID (customerId in the returned JSON objects from the GET requests detailed previously).
HTTP GET
/bureau-customers/{CUSTOMER-ID}/notes
Example Response:
{
"customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"notes": [
{
"customerNoteId": "bd826636-a5c2-45f3-89ab-e5a82be15f83",
"bureauCustomerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"paygateId": "41df5120-1b8b-4a82-ab9f-52344426981a",
"userId": "a2eac239-ef39-4221-93cf-450747e2652a",
"userName": "Terri Coverly",
"creationDate": "2019-08-24T14:15:22Z",
"noteText": "There's an issue with this customer that requires addressing.",
"name": "Terri"
},
{
"customerNoteId": "c993db6b-105b-4af4-b20d-d2b0ebeb75d8",
"bureauCustomerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"paygateId": "41df5120-1b8b-4a82-ab9f-52344426981a",
"userId": "04711343-e841-4bb3-8239-c58a1a8fe175",
"userName": "Malcom Tucker",
"creationDate": "2019-09-24T14:15:22Z",
"noteText": "I finally fixed it, it's been a month!",
"name": "Malcom"
}
],
"customerUrl": "/api/v1/customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"notesUrl": "/api/v1/customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/notes",
"jobsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs",
"submissionsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/submissions"
}
Add Note to Bureau Customer
Notes can be added to a Bureau Customer by performing a POST to the endpoint below:
HTTP POST
/bureau-customers/add-note
Example Request:
Copy
{
"customerId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
"noteText": "Here's the what I'd like to add as a note"
}
The response generated by the Add Note request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation.
Response:
{
"success": true,
"messages": [
"Operation Successful"
]
}
Get Bureau Customer Jobs
Bureau Customers can be associated with Bureau Jobs. It is possible to retrieve a collection of lookup data regarding Bureau Customer Jobs by performing a GET request on the endpoint below:
HTTP GET
/bureau-customers/{CUSTOMER-ID}/jobs
Example Response:
{
"jobs": [
{
"jobId": "cfbd79f0-a000-4c89-bd71-e7348b1db92e",
"jobName": "My Job",
"lastRun": "2019-08-24T14:15:22Z",
"jobUrl": "/api/v1/bureau-jobs/cfbd79f0-a000-4c89-bd71-e7348b1db92e"
}
]
}
Get Bureau Customer Submissions
Bureau Customers can be associated with Bureau Submissions. It is possible to retrieve a collection of lookupdate regarding the Submissions that a Bureau Customer is being used in by performing a GET request on the endpoint below:
HTTP GET
/bureau-customers/{CUSTOMER-ID}/submissions
Example Response:
{
"submissions": [
{
"submissionId": "e3a41646-1466-426e-8808-12bb1b51d886",
"submissionReference": "Monthly Submission 4",
"submissionUrl": "api/v1/bureau-submissions/e3a41646-1466-426e-8808-12bb1b51d886"
}
]
}